Codebase architecture

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

Repository map

Path	Purpose
`app/`	Main Next.js routes: marketing, `/portal/`, `/admin/`, `/api/`, `/resources/`
`components/`	Shared UI, portal shell, marketing sections
`lib/`	Auth, stores, integrations, runtime, Talent/Contractor shared modules
`prisma/`	Schema and migrations (PostgreSQL)
`apps/talent/`	Talent Next.js app (separate deploy, shared DB)
`apps/contractor/`	Contractor Hub Next.js app
`content/`	JSON operational stores (docs, tickets, feedback — migrate path)
`tests/`, `e2e/`	Unit and Playwright suites

Data flow (authenticated portal API)

Browser → proxy.ts (path gate) → /api/portal/... route
  → auth() + PortalUserSession check
  → membership / role scope
  → Prisma → JSON response (no-store when sensitive)

Auth configuration

Root auth.ts / auth.config.ts — Auth.js providers and callbacks.
AUTH_SECRET required; optional AUTH_COOKIE_DOMAIN for subdomain SSO.
Talent and Contractor apps import the same patterns with host-specific proxy.ts.

Platform foundations

lib/platform-foundations.ts lists gated capabilities (e.g. marketplace checkout). Environment variables can enable readiness flags; 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.

In-repo operator map: docs/ARCHITECTURE.md
Portal route notes: app/portal/README.md
Security checklist: docs/SECURITY.md

Path

Purpose

app/

Main Next.js routes: marketing, /portal/*, /admin/*, /api/*, /resources/*

components/

Shared UI, portal shell, marketing sections

lib/

Auth, stores, integrations, runtime, Talent/Contractor shared modules

prisma/

Schema and migrations (PostgreSQL)

apps/talent/

Talent Next.js app (separate deploy, shared DB)

apps/contractor/

Contractor Hub Next.js app

content/

JSON operational stores (docs, tickets, feedback — migrate path)

tests/, e2e/

Unit and Playwright suites

┌─────────────────────────────────────┐ │ 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