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

Technology Stack

Analysis Date: 2026-02-26

Languages

Primary:

• TypeScript 5.7 - All application code (strict mode, noEmit, ES2022 target)

Secondary:

• CSS (Tailwind utility classes only, no custom CSS files)

Runtime

Environment:

• Node.js >=20.0.0 (engines field in package.json)

Package Manager:

• npm (standard)
• Lockfile: package-lock.json present

Frameworks

Core:

• Next.js 15.1 - App Router, standalone output, Turbopack dev mode
• React 19.0 - Server Components by default; 'use client' only where needed

API Layer:

• tRPC 11 (RC build 11.0.0-rc.678) - End-to-end typed RPC, superjson transformer
• @trpc/server, @trpc/client, @trpc/react-query - All at same version

Data:

• Prisma 6.19 - ORM and schema-first migrations; binary targets: native, windows, linux-musl-openssl-3.0.x
• @prisma/client 6.19 - Generated client with connection pool (limit=20, timeout=10)

Auth:

• NextAuth v5 (Beta 25) - JWT strategy, 24-hour sessions; Prisma adapter via @auth/prisma-adapter

Forms & Validation:

• Zod 3.24 - Input validation for all tRPC procedures
• React Hook Form 7.54 - Client-side form state; @hookform/resolvers for Zod integration

UI Components:

• shadcn/ui (configured via components.json) - Radix UI primitives styled with Tailwind
• Radix UI primitives: alert-dialog, avatar, checkbox, collapsible, dialog, dropdown-menu, label, popover, progress, radio-group, scroll-area, select, separator, slider, slot, switch, tabs, toggle, tooltip (all ^1.x or ^2.x)
• Tailwind CSS 4.1 - Utility-first, @tailwindcss/postcss plugin
• Lucide React 0.563 - Icon library (import-optimized via next.config.ts)
• Framer Motion 11 (motion package) - Animation
• Tremor 3.18 - Data visualization / chart components
• @blocknote/react, @blocknote/core, @blocknote/shadcn 0.46 - Rich text block editor
• next-themes 0.4 - Dark/light mode switching
• Sonner 2.0 - Toast notifications

Testing:

• Vitest 4.0 - Test runner, fileParallelism: false, pool: 'forks'
• @playwright/test 1.49 - E2E test runner

Build/Dev:

• Turbopack (built into Next.js 15) - Dev server via next dev --turbopack
• tsx 4.19 - Direct TypeScript execution for scripts and seeds
• ESLint 9.17 + eslint-config-next 15.1 - Linting
• Prettier 3.4 + prettier-plugin-tailwindcss 0.7 - Formatting

Key Dependencies

Critical:

• superjson 2.2 - tRPC transformer; enables Date, Map, Set serialization over the wire
• bcryptjs 3.0 - Password hashing (no native bcrypt — pure JS for portability)
• minio 8.0 - S3-compatible object storage client
• nodemailer 7.0 - SMTP email delivery
• openai 6.16 - OpenAI SDK for AI features
• @anthropic-ai/sdk 0.78 - Anthropic Claude SDK; wrapped in adapter matching OpenAI interface
• @notionhq/client 2.3 - Notion API for project import
• csv-parse 6.1 - CSV import for candidatures seed

Infrastructure:

• date-fns 4.1 - Date manipulation
• use-debounce 10.0 - Input debouncing
• @tanstack/react-query 5.62 - Server state caching (used via tRPC)
• @dnd-kit/core, @dnd-kit/sortable - Drag-and-drop ordering UI
• leaflet 1.9 + react-leaflet 5.0 - Map rendering
• mammoth 1.11 - DOCX to HTML conversion for file content extraction
• pdf-parse 2.4, unpdf 1.4 - PDF text extraction
• html2canvas 1.4, jspdf 4.1, jspdf-autotable 5.0 - PDF export for reports
• franc 6.2 - Language detection for multilingual project content
• papaparse 5.4 - CSV parsing in browser
• cmdk 1.0 - Command palette component
• react-easy-crop 5.5 - Avatar image cropping
• react-phone-number-input 3.4 - International phone number input
• react-day-picker 9.13 - Date picker calendar

Configuration

TypeScript:

• src/tsconfig.json: strict mode, ES2022 target, path alias @/* → ./src/*, bundler module resolution
• Config file: tsconfig.json

Next.js:

• Config file: next.config.ts
• output: 'standalone' for Docker deployment
• typedRoutes: true for compile-time route safety
• serverExternalPackages: ['@prisma/client', 'minio'] — not bundled

Tailwind:

• Config file: tailwind.config.ts
• PostCSS via postcss.config.mjs + @tailwindcss/postcss
• Brand palette: Primary Red #de0f1e, Dark Blue #053d57, White #fefefe, Teal #557f8c

Vitest:

• Config file: vitest.config.ts
• environment: 'node', testTimeout: 30000, sequential execution
• Path alias mirrors tsconfig

Environment:

• Required vars: DATABASE_URL, NEXTAUTH_URL, NEXTAUTH_SECRET, MINIO_ENDPOINT, MINIO_ACCESS_KEY, MINIO_SECRET_KEY, MINIO_BUCKET, SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, EMAIL_FROM, OPENAI_API_KEY, CRON_SECRET
• Optional vars: MINIO_PUBLIC_ENDPOINT, OPENAI_MODEL (default: gpt-4o), OPENAI_BASE_URL, ANTHROPIC_API_KEY, SESSION_MAX_AGE (default: 86400), MAX_FILE_SIZE (default: 524288000), LOG_LEVEL, MAGIC_LINK_EXPIRY (default: 900)
• All settings also configurable via SystemSettings DB table (DB takes priority over env vars)

Build:

• npm run build → next build → produces .next/standalone/ output
• npm run typecheck → tsc --noEmit (no emit, type checking only)

Platform Requirements

Development:

• Node.js >=20.0.0
• PostgreSQL 16 (via Docker or local)
• MinIO instance (optional in dev, defaults to localhost:9000)

Production:

• Docker (compose file: docker/docker-compose.yml)
• PostgreSQL 16 (postgres:16-alpine image) in Docker network
• Next.js app runs as standalone Node.js server on port 7600
• MinIO and Poste.io are external pre-existing services on VPS
• Nginx reverse proxy with SSL (external, not in compose)
• CI/CD: Gitea Actions (image pushed to container registry, pull_policy: always)
• App entrypoint (docker/docker-entrypoint.sh): runs prisma migrate deploy → prisma generate → auto-seeds if DB empty → node server.js

---

Stack analysis: 2026-02-26