6.5 KiB
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 → 09-end-to-end-flow.md → 07-implementation-plan.md → _open-items.md |
| Building it (Talha) | _decisions.md → 02-system-architecture.md → 03-database-design.md → 04-integrations-and-processing.md |
| Building screens (Ahmed) | 09-end-to-end-flow.md → 06-api-boundaries.md → 07-implementation-plan.md §10 |
| Deciding the open questions | _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 |
Documents
| File | Lines | What it is |
|---|---|---|
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 |
620 | What the repository actually contains, with 212 file:line citations. Retain / refactor / rebuild verdicts |
02-system-architecture.md |
1,257 | Modular monolith decision, scored comparison, 25 logical modules, deployment topology, 8 diagrams |
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 |
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 |
814 | Access-scope model, threat model, AI governance, chatbot controlled-tool architecture, audit design |
06-api-boundaries.md |
2,723 | 25 API groups — endpoints, permissions, validation, idempotency, audit. Contracts only, no implementation |
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 |
713 | Every requirement → module → entity → API → phase, plus an honest gap table |
09-end-to-end-flow.md |
304 | The whole candidate journey in one place. 5 flow diagrams, also exported to diagrams/ |
Working files
| File | Purpose |
|---|---|
_decisions.md |
The binding architecture and database decisions. Every document must agree with this |
_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 |
Module-vocabulary ↔ database-vocabulary name mapping |
_repo-findings.md |
The verified repository evidence brief every author worked from |
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 |
| 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); 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 §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.