Visão Geral dos Workers

O backend do Neemias roda em Cloudflare Workers com D1 (SQLite) como banco de dados serverless. Toda a API é construída sobre um pipeline declarativo de middleware com tipagem forte.

Stack

Camada	Tecnologia
Runtime	Cloudflare Workers
Banco de Dados	D1 (SQLite)
Autenticação	PBKDF2 (100k iterações, SHA-256) + JWT HS256 (jose)
Validação	Zod schemas
Tipos	TypeScript com @neemias/schemas (package compartilhado)

Ponto de Entrada

O arquivo workers/src/index.ts é o entry point. Ele:

1. Cria o roteador via createRouter() (importado de workers/src/router.ts)
2. Expõe o handler fetch que despacha request.method + pathname → handler registrado
3. Injeta Env (bindings do Cloudflare) e ExecutionContext

Roteador

O roteador (workers/src/router.ts) mapeia cada rota como uma chave no formato "METHOD /path":

routes["POST /api/v1/students"] = {
  handler: route(
    "POST",
    "/api/v1/students",
    [pipelineRequireAuth(), pipelineRequireRole(["ADMIN", "CADASTRO"])],
    handleCreateStudentPipeline,
  ).handler,
};

Rotas não encontradas retornam 404 com corpo { error: "NOT_FOUND", message: "Route not found" }.

Pipeline de Middleware

O helper route() (workers/src/middleware/pipeline.ts) aceita um array declarativo de middlewares que executam em sequência antes do handler final:

MiddlewareContext

interface MiddlewareContext {
  request: Request;
  env: Env;
  ctx: ExecutionContext;
  principal: AuthPrincipal | null; // populado por requireAuth()
  correlationId: string;
}

Middlewares Internos

Middleware	Origem	Função
requireAuth()	pipeline.ts	Extrai Bearer token, valida JWT (ou dev token), popula ctx.principal
requireRole(roles[])	pipeline.ts	Verifica se ctx.principal.role está na lista permitida
rateLimit({ windowMs, maxRequests })	rate-limit.ts	Rate limiting por IP/chave usando D1

Fluxo de uma Requisição

Request
  → rateLimit? (pré-auth)
  → requireAuth (JWT verify ou dev token)
  → requireRole (verifica permissão)
  → Handler (lógica de negócio)
  → Response

Módulos Principais

Módulo	Arquivo	Responsabilidade
Auth	workers/src/modules/auth/	Login, refresh token, revogação, validação de sessão
Password	workers/src/modules/auth/password.ts	Hash PBKDF2 e verificação
Session Tokens	workers/src/modules/auth/sessionTokens.ts	JWT sign/verify + refresh token creation/rotation
Students	workers/src/modules/students/	CRUD de alunos + soft-delete com justificativa
Attendance	workers/src/routes/attendance.ts	Marcação de presença (MARK_PRESENT/MARK_ABSENT)
Sync	workers/src/modules/sync/	Processamento de eventos offline + conflitos
EventReplay	workers/src/modules/sync/eventReplay.ts	Resolução de conflitos por evento
Idempotency	workers/src/modules/idempotency.ts	Hash de payload para ledger de idempotência
Rate Limit	workers/src/middleware/rate-limit.ts	Rate limiting com D1
Students	workers/src/routes/students.ts	Handlers REST para /students
Users	workers/src/routes/users.ts	Handlers REST para /users
Roles	workers/src/routes/roles.ts	Handlers REST para /roles
Classes	workers/src/routes/classes.ts	Handlers REST para /classes
Nuclei	workers/src/routes/nuclei.ts	Handlers REST para /nuclei
Seed	workers/src/routes/seed.ts	Dados demo (POST /_seed, dev only)
Security.txt	workers/src/routes/security-txt.ts	RFC 9116 (/.well-known/security.txt)

Prefixo da API

Todas as rotas da API usam o prefixo /api/v1.

Arquivos-Chave

Arquivo	Função
workers/src/index.ts	Entry point + bootstrap do roteador
workers/src/router.ts	Definição de todas as rotas
workers/src/schemas.ts	Zod schemas para todos os corpos de requisição
workers/src/shared/types.ts	UserRole, AuthPrincipal, ErrorEnvelope
workers/src/db/d1.ts	Fábrica do client D1
workers/src/db/queries.ts	Queries reutilizáveis (auth, idempotência)
workers/src/middleware/auth.ts	Verificação JWT + dev mode + role guard
workers/src/middleware/pipeline.ts	Helper route() + middlewares built-in
workers/src/middleware/rate-limit.ts	Rate limiting via D1
workers/src/shared/errors.ts	Classe HttpError
migrations/0001_init.sql	Schema core (users, students, events, audit)
migrations/0002_auth_sessions.sql	Sessões de refresh token
migrations/0007_rate_limits.sql	Rate limiting

---

Fonte: workers/CONTEXT.md