92 lines
6.5 KiB
Markdown
92 lines
6.5 KiB
Markdown
# 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.
|