Plataforma de estudos para criação, edição, publicação e execução de simulados, construída a partir de material fornecido pelo mentor em formatos variados.
Status: Etapa 2 concluída (Marcos 2.1–2.6: fluxo DraftQuestion ponta a ponta e contexto identity scaffoldado). Etapa 3 (MVP 1) é a próxima; o Marco 3.1 está parcial (UserRepository com findByEmail e save).
O projeto nasce da experiência real de mentoria voluntária em uma escola de formação para certificações AWS. A criação de simulados hoje é manual e não existe uma plataforma que permita transformar material de estudo — em diferentes formatos — em simulados interativos sem forçar o conteúdo a um formato rígido de entrada.
Uma plataforma onde o mentor fornece conteúdo em formatos variados (inicialmente por modelo estruturado (JSON e Markdown), com um modelo para baixar e preencher; futuramente PDF e DOCX que sigam esse modelo), e o sistema transforma esse material em uma estrutura de questões editável — sempre revisável pelo mentor antes de qualquer publicação.
O estudante responde aos simulados publicados e acompanha seus resultados. O mentor cria, revisa, configura e publica simulados dentro de uma organização.
No médio/longo prazo, a mesma base evolui para cursos, trilhas de estudo, certificados e acompanhamento de progresso.
- AWS é o primeiro contexto de uso, não o domínio estrutural do sistema. O núcleo de domínio (quiz, questão, tentativa) é genérico e não conhece "certificação AWS" como conceito de primeira classe.
- Novos formatos de entrada não devem exigir reescrever o núcleo de quizzes. Importação de material é um módulo plugável, separado do domínio de quiz.
- Nada de complexidade prematura. O backend começa como uma aplicação modular, organizada dentro de um monorepo Nx, sem microserviços, filas ou múltiplos bancos nesta fase.
- Revisão humana é obrigatória. Nenhum conteúdo gerado automaticamente (heurística ou IA) é publicado sem passar pela revisão explícita do mentor.
- Multi-tenancy desde o início. Todo recurso pertencente a uma organização
(material, quiz, tentativa, curso etc.) pertence a uma organização desde o modelo
inicial.
Userrepresenta a identidade global e se relaciona às organizações porMembership.
Camadas conceituais, independentemente de app/lib física:
┌───────────────┐
│ Interface │
│ Web / API │
└───────┬───────┘
↓
┌───────────────┐
│ Application │
│ Use Cases │
└───────┬───────┘
↓
┌───────────────┐
│ Domain │
│ Quiz / User │
└───────┬───────┘
↑
┌─────────────┴─────────────┐
│ │
Import / Infra Database / Auth
Importadores, banco, autenticação e outros serviços externos implementam portas usadas pela camada de aplicação; o domínio permanece independente dessas tecnologias.
- O núcleo de domínio de quiz não conhece a origem do conteúdo (PDF, texto
colado, IA etc.) nem detalhes de persistência ou autenticação — essas
dependências são invertidas via portas declaradas em
application. - A ingestão produz um formato intermediário (
DraftQuestion) que passa por revisão antes de virar umaQuestionoficial do domínio de quiz. quizeimportnunca dependem um do outro diretamente — comunicam-se apenas via contratos compartilhados (DTOs).
studyforge/
├── apps/
│ ├── api/ # NestJS (com ZodValidationPipe, POST /api/draft-questions)
│ ├── api-e2e/
│ ├── web/ # Next.js (App Router, sem acesso a libs de domínio)
│ └── web-e2e/
├── libs/
│ ├── shared/
│ │ ├── domain/ # kernel comum (EntityId, OrganizationId, Result, DomainError, Alternative, QuestionType)
│ │ ├── contracts/ # DTOs/Zod schemas (CreateDraftQuestionCommandSchema)
│ │ └── prisma/ # PrismaService centralizado
│ ├── identity/ # ✅ NOVO (Etapa 2, Marco 2.6)
│ │ ├── domain/ # User (com createdAt), Organization, Membership, MembershipRole
│ │ ├── application/ # port UserRepository, DuplicateEmailError (use cases na Etapa 3)
│ │ └── infra/ # PrismaUserRepository (ainda não registrado no IdentityInfraModule)
│ ├── quiz/ # ⏳ TODO (Etapa 3)
│ │ ├── domain/
│ │ ├── application/
│ │ └── infra/
│ └── import/ # ✅ Marcos 2.2–2.5
│ ├── domain/ # DraftQuestion, Alternative, QuestionType
│ ├── application/ # CreateDraftQuestionUseCase, ports (IdGenerator, DraftQuestionRepository)
│ └── infra/ # CryptoIdGeneratorAdapter, PrismaDraftQuestionRepository, ImportInfraModule
├── prisma/
│ ├── schema.prisma # models: User, DraftQuestion, Alternative; Prisma 7.10 + pg adapter
│ └── migrations/ # 20261001231755_init, 20261109190000_create_users
├── prisma.config.ts # DATABASE_URL via env (na raiz do repositório)
└── nx.json
Estrutura-alvo: adicionar quiz (domain + application + infra) na Etapa 3 e course na Etapa 4.
websó depende deshared/contracts— nunca de domínio/aplicação/infra do backend.domainnão depende de nada (sem framework, sem Nest, sem Prisma).applicationdepende dodomaindo próprio contexto e pode depender deshared/domain/shared/contractspara atravessar fronteiras; declara ports e nunca importa implementações concretas deinfra. Inversão de dependência:infra → application.quizeimportnunca dependem um do outro — só viashared/contracts.shared/contractsnão contém lógica de negócio, apenas tipos/DTOs/validação.- Todo recurso pertencente a uma organização (
Quiz,DraftQuestion,Attempt,Material,Courseetc.) carregaorganizationIdcomo invariante de domínio, não como filtro opcional de query.Useré a exceção: é a identidade global do usuário e se relaciona a organizações viaMembership(ver seção 6.1). - Nenhum fluxo automatizado (IA, importer) publica conteúdo diretamente — publicação é uma ação explícita do mentor, modelada como use case próprio.
- Controllers são "burros": recebem DTO validado, chamam use case, mapeiam saída. Nenhuma regra de negócio vive em controller.
Essas fronteiras são reforçadas via tags do Nx (type:*, scope:*) e
enforce-module-boundaries no ESLint.
SINGLE_CHOICE: 4 alternativas (A–D), exatamente 1 correta e 3 incorretas.MULTIPLE_CHOICE: 5 alternativas (A–E), exatamente 2 corretas e 3 incorretas.
Não implementados neste momento: dissertativa, verdadeiro/falso.
- Mentor cria uma organização.
- Todo acesso a dados respeita o vínculo do usuário com a organização.
- Entrada em uma organização é por convite com link (ver ADR-005): o professor gera o convite e o aluno aceita após autenticar com Google OAuth, o que cria a
Membership.
User representa a identidade global do usuário e não carrega organizationId
diretamente. O vínculo com uma ou mais organizações é modelado por Membership:
User
│
└── Membership ──▶ Organization
Recursos que pertencem a uma organização (Quiz, DraftQuestion, Attempt,
Material, Course, entre outros) carregam organizationId como invariante do
próprio recurso — não como um atributo herdado do usuário. Isso permite que um
mesmo User participe de múltiplas organizações (ex.: mentor em uma escola e
estudante em outra) sem ambiguidade no modelo de dados.
| Camada | Escolha |
|---|---|
| Monorepo | Nx |
| Backend | NestJS (use cases como interactors, ports como interfaces) |
| Frontend | Next.js (App Router) |
| Banco | PostgreSQL |
| ORM | Prisma |
| Contratos/validação | Zod (shared/contracts) |
| Autenticação | Google OAuth |
| Importação de conteúdo | Modelo estruturado (JSON e Markdown) validado com Zod, sem IA paga, via port QuestionImporter. A porta pode ganhar adaptadores de PDF/DOCX depois do MVP 1 (ver ADR-004) |
| Testes | Jest |
Etapa 1 — Fundação documental (concluída)
README.md, CLAUDE.md, AGENT.md revisados antes de qualquer código.
Etapa 2 — Primeiro artefato (concluída)
Criação do monorepo Nx e implementação do menor fluxo que valida a arquitetura de
ponta a ponta: texto estruturado → DraftQuestion → persistência → consulta.
- Marco 2.1 — infraestrutura do monorepo (Nx,
api,web, Prisma) (concluído) - Marco 2.2 — domínio mínimo (
shared/domaineimport/domain) (concluído) - Marco 2.3 — application layer: ports, use cases, contratos Zod (concluído)
- Marco 2.4 — infra: PrismaDraftQuestionRepository, CryptoIdGeneratorAdapter, módulos NestJS (concluído)
- Marco 2.5 — API REST: ZodValidationPipe, POST /api/draft-questions, testes e2e (concluído)
- Marco 2.6 — contexto
identity: User, Organization, Membership, MembershipRole (domínio scaffoldado) (concluído)
Etapa 3 — MVP 1 (próxima) Implementação das camadas application e infra dos contextos, importação por modelo estruturado, publicação e execução de quiz.
- Marco 3.1: fechar
identity(findById,OrganizationRepository,MembershipRepository, entidadeInvitation, migrations) e registrar os repositórios noIdentityInfraModule(parcial:UserRepositorycomfindByEmailesave) - Marco 3.2: autenticação (Google OAuth) e fluxo de convite por link
- Marco 3.3: importação por modelo estruturado (
JsonImportereMarkdownImporter, modelo para download, erros de validação por questão) - Marco 3.4: contexto
quiz(scaffold + domain: Quiz, Question, Attempt, Answer) - Marco 3.5: publicação (
DraftQuestionaprovado viraQuestion, ação explícita do mentor) - Marco 3.6: execução pelo aluno (responder e calcular resultado)
Etapa 4 — Cursos e novos formatos (planejada)
- Banco de questões e simulados por certificação (ADR-008), primeiro item da etapa, depois de quiz, publicação e execução.
- Contexto
course(scaffold + domain models), fora do MVP 1 porque nenhum fluxo do MVP depende dele (ver ADR-006). - Importers de PDF e DOCX (candidatas gratuitas:
pdfjs-distoupdf-parse, emammoth), só para materiais que sigam o modelo estruturado. - Organização pessoal, visibilidade e moderação (ADR-007), a implementar depois do Marco 3.5.
- Sem IA paga: a importação usa modelo estruturado (JSON/Markdown) validado com Zod; quem quiser pode pedir a uma IA externa que preencha o modelo. ADR-004
- Importers de PDF e DOCX: ficam para depois do MVP 1 (Etapa 4), só para materiais que sigam o modelo. ADR-004
- Entrada em organização: convite por link com token e
Invitation; no MVP o professor copia e envia o link, e o envio automático de email fica para depois. ADR-005 - Contexto
course: sai do MVP 1 e vai para a Etapa 4. ADR-006 - Organização pessoal, visibilidade e moderação: todo usuário tem organização pessoal automática; simulados são
PRIVATE,UNLISTEDouPUBLIC; o admin da plataforma (platformRolenoUser) modera. Depois do Marco 3.5. ADR-007 - Banco de questões e simulados por certificação: banco mantido só pelo admin da plataforma, numa organização da plataforma; simulados de 25 ou 65 questões por sorteio estratificado por domínio, com cotas pelo método do maior resto. Primeiro item da Etapa 4. ADR-008
Nenhuma no momento.
Ver DELIVERABLES.md para histórico completo:
- Semanas 1 a 8 (S1–S8): entregues ✅, exceto a Semana 7 (3 specs de quiz), que segue como está no DELIVERABLES.md (🔄 planejada)
- Marco 3.1: parcial 🔄 (Semana 8)
- Marcos 3.2–3.6: planejados ⏳
Inclui:
- Status de cada entregável
- Localização de arquivos
- Como testar
- Commits relacionados