Directory Architecture

Overall Layout

arrange/
├── heineken-interview-arrange-backend/    # Bun + Hono REST API
├── heineken-interview-arrange-frontend/   # Next.js App Router admin console
└── heineken-interview-arrange-docs/       # This documentation (MkDocs)

The two applications are coupled only through OpenAPI: the backend generates /openapi.json from its route definitions, and the frontend generates React Query hooks and types from it with Orval.

Backend

heineken-interview-arrange-backend/
├── src/
│   ├── app.ts             # Hono app assembly (CORS, OpenAPI, Swagger UI, 404/error)
│   ├── server.ts          # Entry point
│   ├── error.ts           # Domain-specific AppError subclasses
│   ├── routes/
│   │   ├── index.ts
│   │   └── v1/            # HTTP layer; createRoute() pairs an OpenAPI definition with its handler
│   ├── schemas/           # Zod schemas for requests/responses (public fields are snake_case)
│   ├── services/          # Business logic
│   ├── repositories/      # Drizzle queries only
│   ├── db/
│   │   └── schema.ts      # Single source of truth for all tables, enums and domain types
│   ├── lib/               # response / errors / logger / pagination / date / databricks-client, etc.
│   ├── middlewares/       # protected-route / error-handler / request-id / winston-logger
│   ├── config/            # env / database / google / business-hours
│   ├── types/             # Import related types
│   └── batch/             # Batches that run independently of the API (import / databricks-meta-sync / pii-cleanup)
├── __tests__/
│   └── unit/services/     # Vitest unit tests
├── scripts/               # setup.sh / migrate.ts / seed.ts
├── drizzle.config.ts
├── docker-compose.yml     # PostgreSQL 17
├── Dockerfile             # App (Lambda + aws-lambda-adapter)
├── Dockerfile.migration   # Migration Lambda
└── Dockerfile.sync        # Sync batch (ECS Fargate)

Layering

A one-way dependency: routes → services → repositories → Drizzle.

Directory	Responsibility	What it must not do
src/routes/v1/	HTTP layer: OpenAPI definitions, auth and role control, snake_case ↔ camelCase conversion	Contain business logic or call Drizzle directly
src/schemas/	Zod schemas. Public API fields are snake_case	Expose raw DB column names
src/services/	Business logic, re-exported as namespaces from services/index.ts via export * as xxxService	Depend on Hono's Context
src/repositories/	Drizzle queries only; failures wrapped in DatabaseQueryError and friends	Make business decisions
src/db/schema.ts	Single source of truth for tables, enums and $inferSelect / $inferInsert types	Be split across multiple files

ESM extensions

Imports must carry the .js extension (from '../lib/index.js'), even when pointing at TypeScript sources.

Where auth and roles are applied

Per router, never in individual handlers.

candidatesRoutes.use('*', protectedRoute());
candidatesRoutes.on(['POST', 'PATCH', 'PUT', 'DELETE'], ['/*'], requireRole('member'));

Frontend

heineken-interview-arrange-frontend/
├── src/
│   ├── app/
│   │   ├── (dashboard)/          # Authenticated admin console
│   │   │   ├── page.tsx          # Dashboard
│   │   │   ├── projects/         # Project list, creation, detail (arrange flow)
│   │   │   └── surveys/          # Survey browsing
│   │   ├── login/                # Login
│   │   └── scheduling/[token]/   # Public candidate page (unauthenticated)
│   ├── api/                      # Orval output. Never edit by hand
│   │   ├── custom-fetch.ts       # Adds Bearer token, returns { data, status, headers }
│   │   ├── endpoints/            # Hooks grouped by tag
│   │   └── models/               # Type definitions
│   ├── components/
│   │   ├── ui/                   # Generic UI (button / table / modal / slot-calendar, etc.)
│   │   ├── layout/               # app-layout / header / sidebar
│   │   ├── projects/             # arrange-steps / step1-form / dashboard-stats
│   │   ├── step2/                # segment-sidebar / candidate-table / question-filter
│   │   ├── candidates/           # candidate-row / summary-bar / status-helpers
│   │   └── providers.tsx         # Shared providers such as React Query
│   ├── lib/                      # auth / utils / candidate-status / response-filter
│   └── types/
│       └── arrange-settings.ts   # Arrange settings type, duplicated with the backend
├── orval.config.ts
├── next.config.ts
└── Dockerfile

Directory notes

Directory	Description
src/app/(dashboard)/	Authenticated console. A route group, so it does not appear in the URL
src/app/scheduling/[token]/	Public page reachable with a token only; no authentication
src/api/	Orval output. Named after paths, e.g. useGetApiV1ProjectsProjectId
src/components/ui/	Reusable UI components
src/lib/	The single gateway for auth tokens (auth.ts) plus utilities
src/types/	Types not expressible via OpenAPI (JSON column contents, etc.)

Reading API responses

custom-fetch.ts returns { data, status, headers }, and that data is the API envelope ({ success, data, ... }), so screens end up traversing response.data.data. Use the apiData() helper in lib/utils.ts.

const { data } = useGetApiV1Projects();
const projects = apiData<GetApiV1Projects200>(data);
// projects?.data → Project[]

Where to Put New Files

Backend

What you are adding	Where it goes
A new endpoint	src/routes/v1/<resource>.ts (extend an existing router, or create one and register it in routes/v1/index.ts)
Request/response definitions	src/schemas/<resource>.ts
Business logic	src/services/<resource>.ts, re-exported from services/index.ts
DB queries	src/repositories/<resource>.ts
Tables, enums, domain types	src/db/schema.ts (single file)
Environment variables	Both src/config/env.ts and .env.example
Generic errors	src/lib/errors.ts
Domain-specific errors	src/error.ts
Batches	src/batch/<name>.ts

Frontend

What you are adding	Where it goes
A screen	src/app/(dashboard)/**/page.tsx
Generic UI component	src/components/ui/
Screen-specific component	src/components/<screen>/
API calls	Do not add them — regenerate src/api/** with bun run generate-api
Type definitions	src/types/