# Utopia Brands ATS — Architecture Package

**Status: awaiting architecture review. No implementation has begun, and none should begin until
this package is signed off.**

An implementation-ready system architecture and database plan for the internal Utopia Brands HR
Recruitment and Applicant Tracking System. 22,700 lines across 32 documents, 50 diagrams.

---

## Start here

| If you are… | Read, in this order |
|---|---|
| **Reviewing and approving** | [`00-scope-classification.md`](00-scope-classification.md) → [`09-end-to-end-flow.md`](09-end-to-end-flow.md) → [`07-implementation-plan.md`](07-implementation-plan.md) → [`_open-items.md`](_open-items.md) |
| **Building it (Talha)** | [`_decisions.md`](_decisions.md) → [`02-system-architecture.md`](02-system-architecture.md) → [`03-database-design.md`](03-database-design.md) → [`04-integrations-and-processing.md`](04-integrations-and-processing.md) |
| **Building screens (Ahmed)** | [`09-end-to-end-flow.md`](09-end-to-end-flow.md) → [`06-api-boundaries.md`](06-api-boundaries.md) → [`07-implementation-plan.md`](07-implementation-plan.md) §10 |
| **Deciding the open questions** | [`_open-items.md`](_open-items.md) §2 — twelve decisions an engineer cannot make, each with a recommended assumption so design is not blocked |
| **Checking nothing was lost** | [`08-requirements-traceability.md`](08-requirements-traceability.md) |

---

## Documents

| File | Lines | What it is |
|---|---:|---|
| [`00-scope-classification.md`](00-scope-classification.md) | 584 | Confirmed vs proposed vs deferred vs rejected. 158 `REQ-` ids. Verdicts on all 17 unconfirmed ideas. 25 open business decisions |
| [`01-repository-assessment.md`](01-repository-assessment.md) | 620 | What the repository actually contains, with 212 `file:line` citations. Retain / refactor / rebuild verdicts |
| [`02-system-architecture.md`](02-system-architecture.md) | 1,257 | Modular monolith decision, scored comparison, 25 logical modules, deployment topology, 8 diagrams |
| [`03-database-design.md`](03-database-design.md) | 6,431 | The full schema. Every table with §11 documentation, 7 ERDs, search design, 29-migration sequence |
| [`04-integrations-and-processing.md`](04-integrations-and-processing.md) | 1,461 | Careers mailbox (Graph + IMAP fallback), careers website, 17-step CV pipeline, 24-job background catalogue, file storage |
| [`05-security-rbac-ai-governance.md`](05-security-rbac-ai-governance.md) | 814 | Access-scope model, threat model, AI governance, chatbot controlled-tool architecture, audit design |
| [`06-api-boundaries.md`](06-api-boundaries.md) | 2,723 | 25 API groups — endpoints, permissions, validation, idempotency, audit. Contracts only, no implementation |
| [`07-implementation-plan.md`](07-implementation-plan.md) | 1,566 | Phases 0–4, 96 enumerated tasks split Talha/Ahmed, review gates, testing strategy, risk register |
| [`08-requirements-traceability.md`](08-requirements-traceability.md) | 713 | Every requirement → module → entity → API → phase, plus an honest gap table |
| [`09-end-to-end-flow.md`](09-end-to-end-flow.md) | 304 | The whole candidate journey in one place. 5 flow diagrams, also exported to [`diagrams/`](diagrams/) |

### Working files

| File | Purpose |
|---|---|
| [`_decisions.md`](_decisions.md) | The binding architecture and database decisions. Every document must agree with this |
| [`_open-items.md`](_open-items.md) | **The arbitration register.** 9 binding rulings, 12 escalated decisions, 11 items closed on inspection. When two documents disagree, this is where it is settled |
| [`_glossary.md`](_glossary.md) | Module-vocabulary ↔ database-vocabulary name mapping |
| [`_repo-findings.md`](_repo-findings.md) | The verified repository evidence brief every author worked from |
| [`adr/`](adr/) | 18 Architecture Decision Records |

---

## The decisions, in one screen

| | Decision |
|---|---|
| **Architecture** | Modular monolith. Two processes (web + worker) from one image, one database |
| **Database** | PostgreSQL 16. JSONB for raw payloads only; core recruitment data is normalised |
| **Search** | Phase 1: PostgreSQL FTS + `pg_trgm`. `pgvector` installed at provisioning, used from Phase 2 |
| **Queue** | Database-backed. No Redis, no Kafka in Phase 1 |
| **Object storage** | S3-compatible, content-addressed. CV bytes never in relational rows |
| **Email** | Microsoft Graph assumed (**unconfirmed** — OPEN item). Webhooks *plus* scheduled reconciliation, never webhooks alone |
| **Permissions** | Enforced in the application service layer as primary, with database roles and constraints as defence in depth |
| **Frontend** | Retain the design system and UI primitives; strangler-migrate the rendering layer. XSS/CSP hardening is Phase 0 work |
| **AI** | Advisory only. Every result versioned and explainable. `actor_kind = 'user'` required for any terminal-negative transition — enforced by service guard *and* database constraint |
| **Chatbot** | Read-only, allowlisted typed tools. No generated SQL, no service account |

---

## Two things a reviewer should not miss

**1. The repository has no backend.** No `package.json`, no database, no auth, no tests, no build
step, no Docker, no env files. Zero network calls in the frontend — all 100 candidates are generated
in-browser by a seeded PRNG (`js/data.js:8-10`). The backend is therefore a greenfield choice, and
the ATS score in the prototype is `int(52,98)` (`js/data.js:123`) — random, with nothing to migrate.

**2. There is a P0 security defect in the existing prototype.** No HTML escaping exists anywhere;
34 `innerHTML` sites interpolate data straight into markup (`js/candidates.js:68`). Harmless today
with synthetic data — but the two Phase 1 intake sources are CVs and inbound email, both
attacker-supplied. This is scheduled as Phase 0 work
([`adr/0014`](adr/0014-phase-0-xss-csp-hardening.md)); real candidate data must not be rendered
before it is fixed.

---

## Honest delivery position

The plan's own bottom-up roll-up of 96 tasks is **56–75 weeks** for the full platform, not the
31–45 originally carried forward. Phase 1 alone is **24–30 weeks**. Within the first month what can
be demonstrated is Phase 0 output plus the beginnings of the Phase 1 spine — not a working ATS.
[`07-implementation-plan.md`](07-implementation-plan.md) §15.3 states plainly what cannot be shown.

No meeting transcript exists in the repository. The assignment brief is the authoritative
requirements source; the BRD in `docs/` is corroborating, not independent.