decoda/README.md

Decoda - Plataforma Educacional

Plataforma para ensinar lógica de programação através de jogos educativos e blocos visuais.

📋 Índice

• Sobre o Projeto
• Arquitetura
• Pré-requisitos
• Instalação e Build
  • Opção 1: Docker Compose (Recomendado)
  • Opção 2: Desenvolvimento Local
• Estrutura do Projeto
• Git Flow
• Comandos Úteis
• Troubleshooting
• Contribuindo

---

🎯 Sobre o Projeto

O Decoda é uma plataforma educacional que oferece:

• 🎮 Jogos educativos interativos para aprender programação
• 📚 Documentação completa para educadores e desenvolvedores
• 🧩 Programação visual com blocos arrastar-e-soltar (sem necessidade de sintaxe), utilizando Blockly.
• 🆓 100% gratuito e sem necessidade de cadastro

Tecnologias Principais

• Frontend (App): React + Vite + Blockly
• Documentação: Docusaurus
• Servidor Web: Nginx
• Containerização: Docker + Docker Compose

---

Arquitetura

O projeto é dividido em 3 serviços principais:

┌─────────────────────────────────────┐
│         Nginx Proxy (porta 80)      │
│                                     │
│  /app/      → App (React/Vite)      │
│  /docs/     → Docs (Docusaurus)     │
└─────────────────────────────────────┘

• app/ - Aplicação React principal com os jogos
• docs/ - Documentação educacional e técnica
• proxy - Nginx fazendo roteamento entre app e docs

---

✅ Pré-requisitos

Para executar com Docker (Recomendado)

Você precisa apenas de:

• Docker (versão 20.10 ou superior)
• Docker Compose (versão 2.0 ou superior)

💡 Não precisa instalar Node.js, npm ou qualquer outra ferramenta!

Verificar se Docker está instalado

docker --version
docker compose version

Se não tiver instalado, siga os guias oficiais:

• Instalar Docker
• Docker Compose já vem incluído nas versões recentes do Docker

---

🚀 Instalação e Build

Opção 1: Docker Compose (Recomendado)

Esta é a forma mais simples e não requer conhecimento de React ou Node.js.

1. Clone o repositório

git clone https://git.mtst.tec.br/rui.moraes/plataforma-edu.git
cd plataforma-edu

2. Build e execução

Execute um único comando para construir e iniciar tudo:

docker compose up --build -d

O que esse comando faz:

• docker compose up - Inicia os serviços
• --build - Reconstrói as imagens se houver mudanças
• -d - Roda em segundo plano (detached mode)

3. Aguarde o build

O primeiro build pode demorar 5-10 minutos dependendo da sua internet e máquina.

Você verá logs parecidos com:

[+] Building 245.3s
 => [app] downloading dependencies...
 => [app] building application...
 => [docs] downloading dependencies...
 => [docs] building documentation...

4. Acesse a aplicação

Depois que o build terminar:

• Aplicação: http://localhost
• Documentação: http://localhost/docs

5. Verificar status

docker compose ps

Você deve ver algo como:

NAME                     STATUS          PORTS
plataforma-edu-app-1     Up 2 minutes
plataforma-edu-docs-1    Up 2 minutes
plataforma-edu-proxy-1   Up 2 minutes    0.0.0.0:80->80/tcp

---

Opção 2: Desenvolvimento Local

Para desenvolvedores que querem editar o código e ver mudanças em tempo real.

Pré-requisitos adicionais

• Node.js 20.x ou superior
• pnpm (gerenciador de pacotes)

Instalar pnpm

npm install -g pnpm

Rodar App (React)

cd app
pnpm install
pnpm run dev

A aplicação estará disponível em http://localhost:5173

Rodar Documentação (Docusaurus)

Em outro terminal:

cd docs
pnpm install
pnpm run start

A documentação estará disponível em http://localhost:3000

---

📁 Estrutura do Projeto

plataforma-edu/
├── app/                      # Aplicação React principal
│   ├── src/                  # Código fonte
│   │   ├── pages/           # Páginas (Home, Educadores, FAQ, etc)
│   │   ├── games/           # Jogos educativos
│   │   ├── components/      # Componentes reutilizáveis
│   │   └── styles/          # Estilos globais
│   ├── public/              # Arquivos estáticos
│   ├── Dockerfile           # Build da imagem Docker
│   ├── package.json         # Dependências npm
│   └── vite.config.js       # Configuração do Vite
│
├── docs/                     # Documentação Docusaurus
│   ├── docs/                # Documentação para desenvolvedores
│   ├── edu/                 # Guias para educadores
│   ├── src/                 # Componentes customizados
│   ├── Dockerfile           # Build da imagem Docker
│   ├── package.json         # Dependências npm
│   └── docusaurus.config.js # Configuração
│
├── docker-compose.yaml       # Orquestração dos containers
├── nginx.conf               # Configuração do proxy Nginx
└── README.md                # Este arquivo

---

🌳 Git Flow

Fluxo de Desenvolvimento

gitGraph
    commit
    branch develop
    checkout develop
    commit
    branch feature/nova-funcionalidade
    checkout feature/nova-funcionalidade
    commit id: "Implementa funcionalidade A"
    commit id: "Ajusta funcionalidade A"
    checkout develop
    merge feature/nova-funcionalidade
    commit id: "Prepara para um novo pacote"
    checkout main
    merge develop
    commit id: "Release v1.0"

Fluxo Simplificado

1. Criar Feature
   git checkout -b feature/xyz (a partir de develop)
        ↓
2. Desenvolver e Commitar
   git commit -m "feat: descrição"
        ↓
3. Push e PR para Develop
   git push origin feature/xyz
   (Abrir PR no GitHub)
        ↓
4. Code Review + Merge em Develop
   Aprovação e merge automático
        ↓
5. PR de Develop para Main
   (Abrir PR: develop → main)
        ↓
6. Merge em Main
   Release pronta para produção

Regras e Configurações

Para informações detalhadas sobre:

• ✅ Como criar branches (a partir de develop)
• ✅ Padrão de commits
• ✅ Regras de PR
• ✅ Deploy em homologação com script
• ✅ Variáveis de ambiente e token GitHub

👉 Consulte: README-HOMOLOGACAO.md

---

🛠️ Comandos Úteis

Docker Compose

Iniciar aplicação

docker compose up -d

Parar aplicação

docker compose down

Ver logs em tempo real

# Todos os serviços
docker compose logs -f

# Apenas app
docker compose logs -f app

# Apenas documentação
docker compose logs -f docs

# Apenas proxy
docker compose logs -f proxy

Rebuild completo (após mudanças no código)

docker compose up --build -d

Rebuild apenas um serviço

docker compose up --build app -d

Verificar status

docker compose ps

Entrar dentro de um container

# App
docker compose exec app sh

# Docs
docker compose exec docs sh

Remover tudo (containers, volumes, imagens)

docker compose down --volumes --rmi all

---

Troubleshooting

Erro: "port 80 already in use"

Problema: Outra aplicação está usando a porta 80.

Solução:

# Linux/Mac - Ver o que está usando a porta 80
sudo lsof -i :80

# Parar o serviço (exemplo com Apache)
sudo systemctl stop apache2

Ou edite docker-compose.yaml para usar outra porta:

proxy:
  ports:
    - "8080:80" # Mude para 8080 ou qualquer porta livre

---

Erro: "COPY nginx-spa.conf: not found"

Problema: Arquivo nginx-spa.conf não está no diretório app/.

Solução:

# Certifique-se de que o arquivo está na pasta correta
ls app/nginx-spa.conf

# Se não estiver, mova da raiz
mv nginx-spa.conf app/

---

Erro: "Minimum Node.js version not met"

Problema: O Dockerfile está usando Node.js 18, mas o projeto requer Node 20.

Solução: Os Dockerfiles já foram corrigidos para usar Node 20. Se ainda encontrar este erro:

# Rebuild forçando recriação das imagens
docker compose build --no-cache
docker compose up -d

---

Build muito lento

Dicas para acelerar:

1. Use cache de build do Docker:

   # Docker irá reusar layers anteriores
   docker compose up --build
   

2. Aumente recursos do Docker:

   • Docker Desktop → Settings → Resources
   • Aumente CPU e Memória

3. Limpe imagens antigas:

   docker system prune -a
   

---

Acesso retorna 403 ao acessar /docs

Problema: Configuração incorreta do proxy Nginx.

Solução: Verifique se nginx.conf tem a barra final no proxy_pass:

location /docs/ {
    proxy_pass http://docs/;
}

Se necessário, rebuild:

docker compose restart proxy

---

Mudanças no código não aparecem

Problema: Docker está usando build antigo em cache.

Solução:

# Rebuild sem cache
docker compose build --no-cache app
docker compose up -d

---

🔄 Fluxo de Deploy em Produção

1. Preparação

# Garantir que está na branch correta
git checkout main
git pull origin main

2. Build

# Rebuild completo sem cache
docker compose build --no-cache

3. Deploy

# Parar versão antiga
docker compose down

# Iniciar nova versão
docker compose up -d

# Verificar logs
docker compose logs -f

4. Verificação

# Checar se todos os containers estão rodando
docker compose ps

# Testar endpoints
curl http://localhost
curl http://localhost/docs

---

📝 Variáveis de Ambiente

O projeto atualmente não usa variáveis de ambiente complexas, mas se precisar:

Crie um arquivo .env na raiz:

# Exemplo
APP_PORT=80
NODE_ENV=production

E referencie no docker-compose.yaml:

services:
  app:
    env_file:
      - .env

---

🤝 Contribuindo

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/nova-funcionalidade)
3. Commit suas mudanças (git commit -m 'Adiciona nova funcionalidade')
4. Push para a branch (git push origin feature/nova-funcionalidade)
5. Abra um Pull Request

---

Para Educadores

Se você é educador e quer usar a plataforma, acesse:

• http://localhost/educadores - Guia de como começar
• http://localhost/docs/edu - Documentação pedagógica completa

---

Desenvolvido com ❤️ para educação em programação