# Technical design and handover

## Stack

Next.js 16.4.6 App Router, React 19.2.6, TypeScript, PostgreSQL 16+, node-postgres (`pg`). Server runs on Node.js; React/CSS implement the screens. This is a full-stack application, not a static export. The Docker image uses standalone Next.js output. Dependency versions are pinned in package.json and package-lock.json.

Framework references used when preparing the build:
- https://nextjs.org/docs/app/api-reference/config/next-config-js/output
- https://nextjs.org/docs/app/guides/self-hosting
- https://node-postgres.com/features/transactions
- https://node-postgres.com/features/queries

## Request sequence

| Step | What happens |
|---|---|
| Sign in | Server verifies scrypt password hash, stores only a token hash, issues an HttpOnly cookie. Role is read from PostgreSQL on every request. |
| Open a question | Server starts or reuses a session automatically, recording identity and timestamps. Testers do not supply build or environment details. |
| Choose question | UI reads current database question and document records. Ask the OI is a prominent copyable block. |
| Record attempt | Server validates active session owner, question version, linked document versions, verdict and evidence. |
| Save | One PostgreSQL transaction writes immutable attempt snapshot, file bytes/links, technical issue links and audit entries. Duplicate operation IDs do not create another attempt. |
| Add searches | Manual entry or server-to-server telemetry attaches measurements to the saved attempt. These are evidence records, not new verdicts. |
| Investigate | Technical adds notes, owner, priority, fix and fixed build. Duplicate issues can consolidate their evidence. |
| Retest | New attempt references the original. A passing linked retest on the named fixed build resolves the technical issue. |
| Report | Administrator/technical views aggregate the shared records; testers see their own records. Dashboard refreshes every 30 seconds. |

## Database map

| Table | Why it exists |
|---|---|
| users | Account identity, role, active status and password hash |
| auth_sessions / login_attempts | Signed-in sessions and persistent login throttling |
| documents / document_versions | Stable document identity with editable codes and retained versions |
| files | Uploaded bytes, filename, type, size and SHA-256 |
| questions / question_versions | Live test definitions and retained revisions |
| question_documents | Stable question-to-document links; codes are display data |
| test_sessions / session_events | Tester sessions, optional test sets and start/pause/resume/finish events |
| runs / run_files | Immutable attempt snapshots and screenshot links |
| search_checks | Individual search measurements with provenance and optional external trace ID |
| issues / issue_runs | Technical investigation and multiple supporting attempts |
| comments | Discussion attached to an attempt |
| drafts | Private per-tester, per-question unfinished notes with revision checks |
| events | Audit history |
| schema_migrations | Applied database schema version |

Payload JSONB retains question snapshots and evidence details while indexed relational IDs provide ownership, link integrity and query lookup. Uploaded file bytes are in PostgreSQL for an initially simple, consistent backup boundary. For large-scale use, a later object-storage adapter should preserve the same file IDs, permission checks and backup contract.

## Important rules in code

- Browser identifiers are never treated as authority. Actor comes from the authenticated cookie and current user row.
- Only administrators create accounts, edit questions and upload authoritative documents.
- Testers cannot read another tester's private result/evidence; technical and administrators can inspect consolidated evidence.
- Drafts, questions, documents and technical records use conflict/version checks. Session transitions and result saves use row locks inside one transaction.
- A run snapshots question content, question version, tester, OI, channel, build, environment and linked document versions.
- Document rename/recode does not change its ID. Existing links remain valid; prior attempts still download the earlier document version.
- No guessing that missing cost equals zero. No summing currencies. Overall attempt cost is not automatically added to search costs.
- Confirmed setup and checked actual outcome are necessary for Pass; evidence is required. Blocked means the test could not be completed and needs an explanation.
- A merged issue retains its original identity and redirects future work to its target; attempt records are unchanged.

## Deliberate limits

- Question/expected-answer quality must be approved against the uploaded authoritative documents. The package does not use an LLM to certify correctness.
- The included judging guidance is generic starter guidance; administrators should strengthen it per test.
- No background task claims to monitor the OI. Automatic measurement collection is a documented integration point, not an installed connection.
- Change detection reports historical question/document differences; it does not automatically mark a new release safe.
- No SSO, email delivery, multi-tenant separation or external ticket integration in this release.
- Current list endpoints return the whole visible pilot dataset. For very large deployments, introduce indexed pagination and server-side aggregation before expanding beyond the pilot workload.
- JSON export contains visible data/metadata, not uploaded file contents. PostgreSQL backup is the complete recovery artifact.
- The administrator/technical dashboard is not an employee attendance tracker.

## Suggested rollout

Install on staging, run the acceptance checklist with two testers and one engineer, upload and link approved references, then admit the wider tester group. Keep the currently hosted system available until any historical-data migration is reviewed and verified. Production deployment, external PostgreSQL networking/TLS, reverse proxy and backup restoration must be verified by your server team.
