Codebase architecture

Monorepo layout for the Hakunai web platform (TypeScript, Next.js App Router).

Repository map

Area	Purpose
Main app	Marketing site, Customer Portal, admin, shared APIs, product docs at `/resources/docs/*`
Shared components	UI, portal shell, marketing sections
Shared libraries	Auth, integrations, agent runtime, cross-app modules
Database schema	PostgreSQL via Prisma migrations
Talent app	Separate Next.js deploy, shared database
Contractor app	Contractor Hub Next.js deploy
Content stores	JSON-backed operational data (docs, tickets) with a migration path to Postgres
Tests	Unit policies and browser e2e suites

Data flow (authenticated portal API)

Browser → early path gate → portal API route
  → session validation
  → membership / role scope
  → database → JSON response (no-store when sensitive)

Auth configuration

Auth.js providers and callbacks on the main app.
Server auth secret required (see .env.example); optional shared cookie domain for subdomain SSO.
Talent and Contractor apps follow the same session patterns on their hosts.

Platform foundations

Readiness flags can enable marketplace checkout and similar capabilities in a given environment; each route must still enforce session and tenant checks.

Diagram

Runtime topology (main monorepo)

┌─────────────────────────────────────┐
│  Browser / Companion apps (mobile)   │
└──────────────────┬──────────────────┘
                   │ HTTPS (TLS)
┌──────────────────▼──────────────────┐
│  Reverse proxy (e.g. nginx)         │
│  security headers + host routing    │
└───┬─────────────┬─────────────┬─────┘
    │             │             │
hakunai.xyz       │ talent.*    │ contractor.*
    ▼             ▼             ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Main    │ │ Talent  │ │Contractor│
│ :3000   │ │ :3002   │ │ :3003   │
└────┬────┘ └────┬────┘ └────┬────┘
     └───────────┼───────────┘
                 ▼
        ┌────────────────┐
        │ PostgreSQL     │
        │ (Prisma)       │
        └────────┬───────┘
                 ▼
        ┌────────────────┐
        │ content/ JSON  │
        │ (legacy ops)   │
        └────────────────┘

proxy.ts → API auth → services → DB

Companion Android/iOS shells live under android/ and ios/; wire them to production APIs before field use.

Operator architecture and security guides in the private repository (for deployers with repo access).