MOPC-Portal/.planning/codebase/ARCHITECTURE.md

# Architecture

**Analysis Date:** 2026-02-26

## Pattern Overview

**Overall:** Role-gated multi-tenant monolith with end-to-end type safety (Prisma → tRPC → React)

**Key Characteristics:**
- Single Next.js 15 App Router application serving all roles (admin, jury, applicant, mentor, observer, public)
- All API calls go through tRPC with superjson serialization; no separate REST API for client data
- Role enforcement happens at two levels: layout-level (`requireRole()`) and procedure-level (tRPC middleware)
- Service layer (`src/server/services/`) contains all business logic — routers delegate immediately to services
- All state machine transitions are audited via `DecisionAuditLog` through `src/server/utils/audit.ts`

## Layers

**Data Layer:**
- Purpose: Schema definition, migrations, query client
- Location: `prisma/schema.prisma`, `src/lib/prisma.ts`
- Contains: Prisma schema, singleton PrismaClient with connection pool (limit=20, timeout=10)
- Depends on: PostgreSQL 16
- Used by: Service layer, tRPC context

**Service Layer:**
- Purpose: Business logic, state machines, external integrations
- Location: `src/server/services/`
- Contains: Round engine, deliberation, assignment, AI services, submission manager, live control, result lock, notification
- Depends on: Prisma client (passed as param to allow transactional usage), `src/lib/` utilities
- Used by: tRPC routers only

**API Layer (tRPC):**
- Purpose: Type-safe RPC procedures with role-based access control
- Location: `src/server/routers/`, `src/server/trpc.ts`, `src/server/context.ts`
- Contains: 44+ domain routers assembled in `src/server/routers/_app.ts`, middleware hierarchy, tRPC context
- Depends on: Service layer, Prisma (via context)
- Used by: Client components via `src/lib/trpc/client.ts`

**UI Layer:**
- Purpose: Server and client React components, pages, layouts
- Location: `src/app/`, `src/components/`
- Contains: Route groups per role, layouts with role guards, client components using tRPC hooks
- Depends on: tRPC client, shadcn/ui, Tailwind CSS
- Used by: Browser clients

**Shared Utilities:**
- Purpose: Cross-cutting helpers available everywhere
- Location: `src/lib/`
- Contains: Auth config, Prisma singleton, email, MinIO client, OpenAI client, logger, rate limiter, feature flags, storage provider abstraction
- Depends on: External services
- Used by: Service layer, routers, layouts

## Data Flow

**Client Query Flow:**

1. React component calls `trpc.domain.procedure.useQuery()` via `src/lib/trpc/client.ts`
2. Request hits `src/app/api/trpc/[trpc]/route.ts` — rate limited at 100 req/min per IP
3. tRPC resolves context (`src/server/context.ts`): auth session + prisma singleton + IP/UA
4. Middleware chain runs: authentication check → role check → procedure handler
5. Router delegates to service (e.g., `roundEngineRouter` → `src/server/services/round-engine.ts`)
6. Service queries Prisma, may call external APIs, writes audit log
7. Superjson-serialized result returns to React Query cache

**Mutation Flow (with audit trail):**

1. Component calls `trpc.domain.action.useMutation()`
2. tRPC middleware validates auth + role
3. Router calls `logAudit()` before or after service call
4. Service performs database work inside `prisma.$transaction()` when atomicity required
5. Service writes its own `logAudit()` for state machine transitions
6. Cache invalidated via `utils.trpc.invalidate()`

**Server-Sent Events Flow (live voting/deliberation):**

1. Client subscribes via `src/hooks/use-live-voting-sse.ts` or `src/hooks/use-stage-live-sse.ts`
2. SSE route `src/app/api/live-voting/stream/route.ts` polls database on interval
3. Events emitted for vote count changes, cursor position changes, status changes
4. Admin cursor controlled via `src/server/services/live-control.ts` → tRPC `liveRouter`

**State Management:**
- Server state: React Query via tRPC hooks (cache + invalidation)
- Edition/program selection: `src/contexts/edition-context.tsx` (localStorage + URL param + React Context)
- Form state: Local React state with autosave timers (evaluation page uses refs to prevent race conditions)
- No global client state library (no Redux/Zustand)

## Key Abstractions

**Competition/Round State Machine:**
- Purpose: Governs round lifecycle and per-project states within rounds
- Examples: `src/server/services/round-engine.ts`
- Pattern: Pure functions with explicit transition maps; `VALID_ROUND_TRANSITIONS` and `VALID_PROJECT_TRANSITIONS` constants define allowed moves. All transitions are transactional and audited.
- Round transitions: `ROUND_DRAFT → ROUND_ACTIVE → ROUND_CLOSED → ROUND_ARCHIVED`
- Project-in-round transitions: `PENDING → IN_PROGRESS → PASSED/REJECTED → COMPLETED/WITHDRAWN`

**tRPC Procedure Types (RBAC middleware):**
- Purpose: Enforce role-based access at the API boundary
- Examples: `src/server/trpc.ts`
- Pattern: `publicProcedure`, `protectedProcedure`, `adminProcedure`, `superAdminProcedure`, `juryProcedure`, `mentorProcedure`, `observerProcedure`, `awardMasterProcedure`, `audienceProcedure`
- Each is a pre-configured middleware chain; routers simply choose the correct type

**CompetitionContext resolver:**
- Purpose: Loads the full typed context for a round (competition + round + parsed configJson + juryGroup + submissionWindows)
- Examples: `src/server/services/competition-context.ts`
- Pattern: `resolveCompetitionContext(roundId)` used by any service that needs the full picture. Also provides `resolveMemberContext()` for jury-member-specific context with assignment counts.

**Round-Type Config Schemas:**
- Purpose: Each RoundType (`INTAKE`, `FILTERING`, `EVALUATION`, etc.) has a dedicated Zod config schema stored in `Round.configJson`
- Examples: `src/types/competition-configs.ts` — `IntakeConfigSchema`, `FilteringConfigSchema`, `EvaluationConfigSchema`, etc.
- Pattern: `safeValidateRoundConfig(roundType, configJson)` returns typed config or null; `validateRoundConfig()` throws on invalid

**Storage Provider Abstraction:**
- Purpose: Swap MinIO (production) for local filesystem (dev/test) without changing service code
- Examples: `src/lib/storage/types.ts`, `src/lib/storage/s3-provider.ts`, `src/lib/storage/local-provider.ts`, `src/lib/storage/index.ts`
- Pattern: `StorageProvider` interface with `getUploadUrl`, `getDownloadUrl`, `deleteObject`, `putObject`, `getObject`

**AI Pipeline with Anonymization:**
- Purpose: All AI calls strip PII before sending to OpenAI
- Examples: `src/server/services/anonymization.ts` + any `src/server/services/ai-*.ts`
- Pattern: `anonymizeProjectsForAI()` returns `AnonymizedProjectForAI[]` + `ProjectAIMapping`; AI service uses anonymous IDs; results mapped back via mapping object

## Entry Points

**tRPC API Handler:**
- Location: `src/app/api/trpc/[trpc]/route.ts`
- Triggers: All client data queries and mutations
- Responsibilities: Rate limiting (100 req/min), `fetchRequestHandler` with `appRouter` + `createContext`, error logging

**Auth Handler:**
- Location: `src/app/api/auth/[...nextauth]/route.ts`
- Triggers: Login, magic link verification, session management
- Responsibilities: NextAuth v5 with Email + Credentials providers, 5-attempt lockout

**Cron Endpoints:**
- Location: `src/app/api/cron/` (audit-cleanup, digest, draft-cleanup, reminders)
- Triggers: External scheduler via `CRON_SECRET` header check
- Responsibilities: Periodic maintenance — evaluation reminders, draft cleanup, digest emails, audit log rotation

**SSE Stream:**
- Location: `src/app/api/live-voting/stream/route.ts`
- Triggers: Live voting/deliberation pages subscribe as long-running GET connections
- Responsibilities: Poll DB for changes, push events for vote counts, cursor position, status transitions

**Next.js Middleware:**
- Location: `middleware.ts` (root, uses `src/lib/auth.config.ts`)
- Triggers: Every request
- Responsibilities: Auth check (edge-compatible), redirect to `/login` if unauthenticated, redirect to `/set-password` if `mustSetPassword` flag set

**Role Layout Guards:**
- Location: `src/app/(admin)/layout.tsx`, `src/app/(jury)/layout.tsx`, etc.
- Triggers: Navigation into role-specific route group
- Responsibilities: Server-side `requireRole()` call, redirect to role dashboard if unauthorized, onboarding gate (jury)

## Error Handling

**Strategy:** Boundary-based — tRPC errors propagate to React Query; service errors use `TRPCError`; audit never throws

**Patterns:**
- Services return typed result objects (`{ success: boolean, errors?: string[] }`) for state machine operations — no throwing
- tRPC procedures throw `TRPCError` with code (`NOT_FOUND`, `FORBIDDEN`, `CONFLICT`, `BAD_REQUEST`) for client-visible errors
- `logAudit()` is wrapped in try-catch — audit failures are logged to console but never surface to users
- AI services use `classifyAIError()` from `src/server/services/ai-errors.ts` to translate OpenAI errors
- Round notification functions explicitly catch all errors and log them — notifications never block round transitions
- Client uses `toast.error()` from sonner for user-facing error display

## Cross-Cutting Concerns

**Logging:**
- `src/lib/logger.ts` — tagged, level-aware (`debug/info/warn/error`), respects `LOG_LEVEL` env var, defaults to `debug` in development and `warn` in production
- Pattern: `logger.info('ServiceName', 'message', { data })` — tag identifies the calling service

**Validation:**
- Zod schemas on all tRPC procedure inputs (`.input(z.object({...}))`)
- `ZodError` is formatted and included in tRPC error response via `errorFormatter` in `src/server/trpc.ts`
- Round config Zod schemas in `src/types/competition-configs.ts` validate `configJson` at activation time

**Authentication:**
- NextAuth v5 with JWT strategy; session available server-side via `auth()` from `src/lib/auth.ts`
- `requireRole(...roles)` in `src/lib/auth-redirect.ts` used by all role layouts — checks `user.roles[]` array with `user.role` fallback
- `userHasRole()` in `src/server/trpc.ts` used inline for fine-grained procedure-level checks

**Audit Trail:**
- `logAudit()` in `src/server/utils/audit.ts` — writes to `AuditLog` table
- Called from both routers (with `ctx.prisma` to share transaction) and services
- Never throws — always wrapped in try-catch

**Feature Flags:**
- `src/lib/feature-flags.ts` — reads `SystemSetting` records with `category: FEATURE_FLAGS`
- Currently one active flag: `feature.useCompetitionModel` (defaults to `true`)

---

*Architecture analysis: 2026-02-26*