Implementation handoff draft

Draft v0.3 · 13 October 2026 · Portfolio Demo R1 on the agreed stack. Local application implementation now exists; see ../verification.md for actual acceptance results. VPS configuration remains separate.

Development baseline

Use the Portfolio R1 table and acceptance gates in the release plan for release scope, and technical architecture for implementation choices. The full company-oriented POC remains reference analysis; it does not expand the R1 build automatically. Preserve FR/US/BR/TC identifiers and annotate partial R1 coverage.

Agreed stack: Next.js App Router, TypeScript, Tailwind CSS, next-intl (EN/nl-BE), PostgreSQL with pg and SQL migrations, Vitest and Playwright. Deployment uses Node.js, systemd and Caddy on the user's new VPS, without Docker. Resolve compatible dependency versions and pin them during project setup.

Dated R1 extensions now specify session/reset contracts, data-model scope, localization, tests and traceability. See ../r1-devready-tickets.md for implementation tickets. Record a Git commit hash after these documents are synchronized so tickets can cite a reproducible baseline. No commit is created by this handoff update.

Folder ownership and proposed structure

Application work stays in project/Code/. Existing contracts and fixtures are implementation inputs; FA artifacts remain in project/Project documentation/FA Deliverables/. Do not follow the course prompt's 1-2-MVP/product-mvp/ location or its blanket prohibition on authorization. Account registration is omitted, but server demo-session authorization is required.

project/Code/
  README.md
  contracts/openapi.json
  fixtures/sample-data.json
  src/
    app/                  Next.js pages and /api/v1 route handlers
    components/           role screens and guided controls
    i18n/                 locale configuration
    domain/               pure rules and transitions
    server/
      sessions/           visitor scope and allowed actors
      services/           access policies and transaction orchestration
      persistence/        pg repositories
  messages/               en and nl-BE dictionaries
  migrations/             numbered SQL schema changes
  scripts/                migration, seed and cleanup commands
  tests/
    unit/                 Vitest domain tests
    integration/          Vitest API and PostgreSQL tests
    e2e/                  Playwright browser journeys
  ops/                    systemd/Caddy examples and VPS runbook

This tree is proposed, not a claim that files exist. API routes must keep the current contract's /api/v1 prefix. Locale-prefixed demo pages must not alter API paths.

Readiness work before implementation

Add R1/session coverage to model 09 and choose session lifetime, cleanup and reset generation behavior.
Specify demo start, role switching, scenario loading and reset in document 11 and OpenAPI, including payloads, cookies, authorization, errors and retry behavior.
Update R1 screen/localization guidance in 08/12, retaining full POC context and explicit coverage.
Add tests for session isolation, reset races, locale preservation and guided completion to 14 and map them in 15.
Prepare DevReady tickets with acceptance criteria, rule references, inputs/outputs, failure cases, fixtures and dependencies. Full POC scenarios outside R1 remain planned.

Local-first acceptance gate

Implement and run the application on the developer's computer first, with a local PostgreSQL development database and a separate local PostgreSQL test database. Browser, API, migrations, seeds and persistence must work locally without connecting to the VPS. A frontend connected only to a remote VPS database does not satisfy this gate.

Before starting BL20 server configuration or deployment:

Apply migrations and seed fixtures from documented local setup instructions.
Run the complete R1 Must journey locally, including role handoffs, EN/nl-BE, visitor isolation and reset.
Verify PostgreSQL persistence across a local application restart.
Pass the relevant Vitest and Playwright suites and record actual results.
Build the application and verify its production-mode startup locally, in addition to development mode.
Complete the local functional review and resolve release-blocking failures.

Local acceptance is a milestone, not a claim that the publicly shared R1 is released. VPS configuration and public deployment follow it as a separate task. systemd and Caddy are VPS concerns and are not required to run the app on the Windows development computer. Secrets and connection details stay in local environment configuration outside version control.

Build sequence

Create the Next.js project and establish development/test PostgreSQL connections; add SQL migrations, the fixed clock and session-scoped seed/reset. Verify two isolated visitors.
Deliver the first increment: enter the demo, choose preferences, propose and accept/decline a plan, create a manual record and reset the visitor dataset. Include EN/nl-BE, accessible controls and guidance from the start.
Add check-in and deterministic review. Use seeded Jules coverage for the missing-data scenario; do not claim an importer is implemented.
Add explicit support requests and the assigned-coach queue, including permission and duplicate-request checks.
Add coach proposals, member acceptance/decline and version conflict handling; demonstrate unchanged active state before acceptance.
Add coaching permission revocation and analyst decision inspection. Verify denied protected actions and exclusion of personal notes.
Complete self-guided handoffs, independent exploration and the English portfolio case page linking analysis, code and actual test evidence.
Execute the R1 verification suite and record results; capture an example of AI-generated work, human correction and validation.
Only after the local-first acceptance gate passes, execute the separate BL20 VPS setup/deployment task when OS, secure access and domain decisions are available. Verify the public URL, service restart and database restore.

BL04 imports, BL08 participation lifecycle, BL14 activity corrections and BL16 aggregate measures follow R1 priority decisions. If implemented, include all associated permissions, transaction checks and acceptance tests.

Example rule boundary

Input: plan state, fixed week, active version, normalized activities, coverage, check-in and permission state. Output: outcome, rule ID/version, next-action options and secondary data-quality flags. Rules do not access the database, generate medical predictions, send messages or create support requests as a side effect.

Test and evidence strategy

Vitest unit tests check pure rules; API integration tests use a dedicated PostgreSQL test database and verify persisted effects, access checks, idempotency and stale revisions. Playwright drives the real app/API to verify the main role journey, EN/nl-BE and isolated reset. Never run destructive test setup against the public demo database.

Record build revision, test IDs, fixture revision, time, actual result and pass/fail. Human review checks guidance, keyboard navigation and Dutch translation. Planned tests remain not executed until run. A passing build or screenshot alone does not establish functional acceptance.

VPS handoff

BL20 is a separate configuration task for a fresh server, not a prerequisite for local coding. Its inputs are OS/version, secure access, domain/DNS and existing service inventory. The runbook must cover PostgreSQL, Node.js, systemd, Caddy/HTTPS, firewall, backups/restore, logs and rollback. Secrets remain outside version control; document variable names only. The user's existing project/.env is not documentation or a fixture.

Completion boundaries

R1 is complete only when its Must items and acceptance gates are verified and the public link works. Full POC completion requires the broader POC baseline and its tests separately. Neither establishes clinical benefit, confirmed CM/MC requirements or production readiness.