ML-nextjs-board-game

KO | EN

gitlite — search

#javascript #react #typescript #go #android #machine-learning #deep-learning #java #awesome #cli #awesome-list #pytorch #security #open-source

ML-nextjs-board-game

(★ 10)

No description available.

ML-nextjs-board-game Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Boardgames Recommendation System - Next.js + TensorFlow.js

Sistema de recomendação de jogos de tabuleiro utilizando **TensorFlow.js** para machine learning no servidor.

## 🎯 Objetivo

Este projeto é uma implementação de sistema de recomendação usando redes neurais com TensorFlow.js. O sistema:

1. Processa características de jogos de tabuleiro (categorias, mecânicas, complexidade, etc.)
2. Codifica jogos em vetores numéricos (embeddings)
3. Treina um modelo de rede neural para prever preferências
4. Recomenda novos jogos baseado no perfil do usuário

## 🛠️ Tecnologias

- **Next.js 14** - Framework React fullstack
- **TensorFlow.js** - Machine Learning no JavaScript (server-side)
- **MongoDB + Mongoose** - Banco de dados para jogos e embeddings
- **Tailwind CSS** - Estilização
- **localStorage** - Persistência de dados do usuário (jogos jogados)

## 🚀 Como Executar

### 1. Instalar dependências

```bash
npm install
```

### 2. Configurar variáveis de ambiente

```bash
# Copiar o exemplo
cp .env.example .env

# Editar .env com sua string de conexão MongoDB
# MONGODB_URI=mongodb://localhost:27017/boardgames
```

### 3. Popular o banco de dados (opcional, mas recomendado)

```bash
# Certifique-se que o MongoDB está rodando
npm run seed
```

> Sem MongoDB, o sistema usa fallback para os arquivos JSON estáticos.

### 4. Rodar em desenvolvimento

```bash
npm run dev
```

### 5. Build para produção

```bash
npm run build
npm start
```

## 🏗️ Arquitetura

### Server-Side ML

Toda a lógica pesada de Machine Learning roda no **servidor**:

- **GET /api/games** - Busca jogos (MongoDB ou JSON)
- **GET /api/metadata** - Metadados para encoding
- **POST /api/embeddings** - Gera embeddings server-side
- **POST /api/train** - Treina modelo e retorna recomendações
- **POST /api/recommendations** - Recomendações rápidas (sem treinar)

### Encoding de Jogos

Cada jogo é convertido em um vetor numérico considerando:

- **Categorias** (one-hot encoding) - 84 dimensões
- **Mecânicas** (one-hot encoding) - 191 dimensões  
- **Complexidade** (normalizada 0-1)
- **Rating** (normalizado 0-1)
- **Ano** (normalizado 0-1)
- **Nº jogadores** (normalizado 0-1)
- **Tempo de jogo** (normalizado 0-1)
- **Cooperativo** (0 ou 1)

### Modelo Neural

```
Entrada: [vetor_usuario, vetor_jogo]
   ↓
Dense(128, relu)
   ↓
Dense(64, relu)
   ↓
Dense(32, relu)
   ↓
Dense(1, sigmoid) → Score de recomendação (0-1)
```

### Fluxo de Recomendação

1. Usuário marca jogos que já jogou
2. Sistema calcula vetor médio do perfil do usuário
3. Para cada jogo do catálogo, combina [perfil_usuario, vetor_jogo]
4. Modelo prediz score de compatibilidade
5. Retorna top N jogos com maior score

## 📁 Estrutura do Projeto

```
├── src/
│   ├── app/                    # App Router Next.js
│   │   ├── layout.js           # Layout principal
│   │   ├── page.js             # Página inicial
│   │   └── api/                # API Routes (server-side)
│   │       ├── games/          # CRUD de jogos
│   │       ├── metadata/       # Metadados para encoding
│   │       ├── embeddings/     # Geração de embeddings
│   │       ├── train/          # Treinamento do modelo
│   │       └── recommendations/ # Recomendações
│   ├── components/             # Componentes React
│   ├── lib/                    # Utilitários
│   │   ├── db/                 # Mongoose config + models
│   │   │   ├── mongoose.js     # Conexão singleton
│   │   │   └── models/         # Game, Category, Mechanic, Embedding
│   │   └── tensorflow/         # Lógica TensorFlow.js
│   │       ├── model.js        # Configuração do modelo
│   │       └── encoder.js      # Encoding de features
│   └── hooks/                  # React hooks customizados
│       ├── usePlayedGames.js   # Persistência localStorage
│       └── useRecommendationServer.js  # API calls
├── public/
│   └── data/                   # Dados dos jogos (JSON fallback)
├── scripts/
│   ├── prepareData.mjs         # Preparar JSONs
│   └── seedDatabase.mjs        # Popular MongoDB
└── .env.example                # Variáveis de ambiente
```

## 🎮 Dataset

Utiliza dados do BoardGameGeek com ~1000 jogos selecionados (top rated).

Campos principais:
- `bgg_id`: ID único
- `name`: Nome do jogo
- `year`: Ano de lançamento
- `categories`: Categorias (ex: Fantasy, Card Game)
- `mechanics`: Mecânicas (ex: Dice Rolling, Hand Management)
- `complexity`: Complexidade (1-5)
- `avg_rating`: Nota média
- `min_players`, `max_players`: Número de jogadores
- `min_time`, `max_time`: Duração

## 🔧 Deploy na Vercel

O projeto está configurado para deploy fácil na Vercel:

```bash
# Via CLI
vercel

# Ou conecte o repositório GitHub na Vercel
```

## 📝 Licença

MIT

ML-nextjs-board-game

ML-nextjs-board-game Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ML-nextjs-board-game

ML-nextjs-board-game Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README