Kodan é uma plataforma de treino para leitura, diagnóstico e explicação de código em TypeScript e React. A pessoa escolhe um desafio, analisa o snippet, envia o diagnóstico e acompanha o feedback e a evolução de ELO.

O repositório é um monorepo Bun com duas aplicações locais: o produto web e a documentação Docusaurus.

• Bun 1.3 ou superior;
• PostgreSQL apenas para os fluxos integrados com dados e autenticação;
• Git.

bun install

Crie seu arquivo local a partir do exemplo seguro:

cp apps/web/.env.example apps/web/.env

No PowerShell:

Copy-Item apps/web/.env.example apps/web/.env

Para desenvolver apenas a interface sem PostgreSQL nem Better Auth, ative temporariamente o mock em apps/web/src/lib/mock-mode.ts; nesse caso, os dados vivem apenas na memória. Não envie apps/web/.env para o Git.

As limitações e a troca para a integração real estão documentadas em Modo mock local.

Para trabalhar com banco, autenticação ou Prisma, mantenha o mock desativado e preencha DATABASE_URL, DIRECT_URL, BETTER_AUTH_SECRET, BETTER_AUTH_URL e CORS_ORIGIN.

bun run db:push

Use terminais separados durante o desenvolvimento:

# Aplicação Kodan
bun run dev:web

Abra http://localhost:3001.

# Documentação e referência de API
bun run docs:dev

Abra http://localhost:3002.

bun run docs:dev gera a especificação OpenAPI antes de iniciar o Docusaurus. Para trabalhar apenas na interface da documentação, sem regenerar a API, use bun run --filter docs dev.

Se uma porta já estiver em uso, finalize o processo que está usando 3001 ou 3002, ou reutilize o servidor que já está em execução. Evite iniciar bun run dev duas vezes.

apps/
  web/                  # Next.js: interface e Route Handlers HTTP
  docs/                 # Docusaurus e referência OpenAPI
packages/
  ui/                   # Primitives shadcn/ui, estilos e tokens
  db/                   # Prisma, schema e acesso a PostgreSQL
  auth/                 # Better Auth
  env/                  # Validação tipada de variáveis de ambiente
content/
  challenges/           # Desafios já disponíveis para treino
  question-bank/        # Seeds editoriais para curadoria
scripts/                # Geração OpenAPI e rotinas editoriais

Regra prática: mantenha código específico da aplicação em apps/web; extraia para packages/ui apenas o que for realmente reutilizável; use content/challenges para desafios jogáveis e content/question-bank para material editorial ainda não promovido.

Para mudanças de código:

bun run check-types
bun test

Para alterações em Docs, contratos HTTP ou OpenAPI:

bun run docs:build

Para alterações React, rode também:

bun run doctor

Veja o guia de contribuição para os fluxos de interface, API, dados e conteúdo.