✨ StarDust

Plataforma educativa gamificada desenvolvida para o ensino de lógica de programação. O projeto utiliza uma metáfora espacial para engajar os estudantes em uma jornada de aprendizado, combinando elementos de jogos com conteúdo técnico estruturado.

🚀 Visão Geral

O objetivo do StarDust é tornar o aprendizado de programação acessível e divertido, oferecendo:

• Gamificação Robusta: Sistema de pontos (XP), moedas (StarCoins), ofensiva (Streak) e conquistas.
• Jornada Espacial: Organização do conteúdo em "Planetas" (temas) e "Estrelas" (fases).
• Arquitetura Modular: Separação clara de responsabilidades com foco em escalabilidade.
• Ambiente Completo: Inclui plataforma de estudo (Web), área administrativa (Studio) e API (Server).

🛠 Tech Stack

O projeto é um monorepo gerenciado pelo TurboRepo e utiliza as tecnologias mais modernas do ecossistema JavaScript/TypeScript:

• Gerenciamento: TurboRepo + NPM
• Linguagem: TypeScript 5.8+
• Frontend (Web): Next.js 15 + React 19
• Estilização: Tailwind CSS + Radix UI
• Backend (Server): Node.js + Hono
• Fila/Jobs: Inngest
• App Interno (Studio): React Router v7
• Banco de Dados: Supabase (PostgreSQL)
• Qualidade: Biome + Jest

🏗 Arquitetura

O StarDust segue os princípios da Arquitetura Limpa (Clean Architecture) e Domain-Driven Design (DDD), adotando um modelo Hexagonal (Ports and Adapters).

• Core Agnóstico: O pacote @stardust/core contém toda a lógica de negócio e é independente de frameworks.
• Camadas Bem Definidas: Separação estrita entre Domínio, Casos de Uso, Interfaces e Infraestrutura.
• Adaptação: As aplicações (web, server, studio) atuam como adaptadores que consomem o núcleo do sistema.

Para detalhes profundos sobre as decisões técnicas, consulte a Documentação de Arquitetura.

📂 Estrutura do Projeto

stardust/
├── apps/                  # Aplicações executáveis
│   ├── web/               # Frontend principal (Next.js)
│   ├── server/            # Backend API (Hono/Node)
│   └── studio/            # Painel Administrativo (React Router)
├── packages/              # Bibliotecas compartilhadas
│   ├── core/              # Regras de Negócio e Domínio (DDD)
│   ├── validation/        # Schemas de validação (Zod)
│   ├── email/             # Serviços de Email
│   ├── lsp/               # Language Server Protocol (Lógica)
│   └── typescript-config/ # Configurações base de TS
└── documentation/         # Documentação centralizada

⚙️ Configuração e Instalação

Pré-requisitos

• Node.js 22 ou superior.
• NPM (gerenciador de pacotes).

Passo a Passo

1. Clone o repositório:

   git clone https://github.com/JohnPetros/stardust.git
   cd stardust

2. Configure o Ambiente: Crie um arquivo .env na raiz do projeto (e nos apps específicos, se necessário) contendo as variáveis de ambiente. Consulte o time de desenvolvimento para obter as credenciais do Supabase e outros serviços.

3. Instale as dependências:

   npm install

4. Execute o projeto (modo desenvolvimento):

   npm run dev

   Isso iniciará todas as aplicações do monorepo simultaneamente via TurboRepo.

📖 Documentação

A documentação completa do projeto está organizada no diretório documentation/. Comece por aqui:

• Visão Geral do Produto
• Arquitetura e Decisões Técnicas
• Regras e Convenções
  • Convenções de Código
  • Core e Domínio
  • Regras de UI
  • Camada REST
  • Camada RPC
  • Camada de Fila
  • Banco de Dados
  • Providers
  • Aplicação Web
  • Aplicação Studio
  • Testes de Handlers
  • Testes de Casos de Uso
  • Testes de Widgets
  • Testes de Objetos de Domínio

🧪 Testes

O projeto utiliza Jest para testes automatizados, cobrindo desde regras de negócio no core até componentes de UI.

# Executar todos os testes
npm run test

# Executar testes apenas do core
npm run test:core

📝 Licença

Este projeto está sob a licença MIT. Consulte o arquivo LICENSE para mais detalhes.

---

Feito com 💜 por John Petros 👋🏻