Architecture | Hakunai

Architecture (high level)

Hakunai runs as three Next.js applications plus PostgreSQL, fronted by HTTPS and a reverse proxy. Shared auth secrets and (when configured) cookie domain allow cross-subdomain sign-in between the main site, Talent, and Contractor Hub.

Runtime surfaces

Surface	Source	Default port	Responsibility
Main	`app/`, `components/`	3000	Public site, customer portal, admin, shared APIs
Talent	`apps/talent/`	3002	Candidates, job board, Talent Studio
Contractor	`apps/contractor/`	3003	Invoicing, expenses, tax helpers
PostgreSQL	`prisma/schema.prisma`	5432	Identity, tenancy, portal and product data

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.

Request flow

TLS terminates at the proxy; security headers are applied (config/security-headers.cjs).
proxy.ts performs early navigation gates for portal and admin paths (UX only — not authorization).
Route handlers validate Auth.js sessions and organisation membership again.
Domain services enforce business rules; Prisma persists durable state.
Some operational tools still read/write JSON under content/ (docs, tickets, etc.) until migrated.

For engineer-oriented detail, see Codebase architecture and the in-repo docs/ARCHITECTURE.md (operators).