Implementation Plan

Status: Living document — updated at the end of every phase.

Goal

A production-grade Canadian dental clinical documentation, treatment-planning, patient-communication, and clinic-management assistance platform. AI output is always a draft; an authorized dental professional must review and explicitly approve everything before it can be charted, exported, sent, or signed.

Delivery phases

Phase	Scope	Definition of working	Status (2026-07-24)
0	Discovery, plan, ADRs, threat model, structure	Docs merged, repo builds empty	Done
1	Monorepo, tooling, tokens, UI foundation, auth, tenancy, RLS, audit chain, local env	`make bootstrap && make dev` yields a signed-in shell	Done (backend committed; design system + clinic-web BFF auth + Keycloak dev realm)
2	Organizations, clinics, locations, rooms, staff, roles, patients, medical data, appointments, timeline, search	Clinic staff can manage patients and appointments end-to-end	Done server-side; clinic-web covers dashboard/patients/schedule/staff/settings/reports
3	Recording consent, recorder, waveform, chunked resumable upload, context island, realtime gateway, transcription, transcript editor	Audio recorded in a treatment room survives network loss and produces an editable speaker-aware transcript	Done (recorder + transcript editor + realtime ticket/WS client; interim text via BFF refetch on PHI-free events)
4	AI gateway (privacy modes, prompt registry, structured outputs, routing), clinical note generation, patient summary, diagnosis/code suggestions, evidence mapping, evaluations	Drafts generate from a transcript with evidence links and land in review as unapproved	Backend done; clinic-web generate + review workspace UI landed
5	Procedure catalog + fee guides, treatment plans/options/comparison, consents, instructions, referrals, prescriptions, clearance, lab prescriptions, review + approval workspace	A dentist can approve section-by-section with hash-chained approval events	Backend done; clinic-web plans/consents/rx/referrals/review workspaces landed
6	Document rendering, exports, secure delivery, secure messaging, patient portal, signatures, treatment acceptance	Patient reviews, signs, accepts/declines through the portal	Backend done; patient-portal app landed
7	Integration framework, ABELDent adapter boundary, email/SMS/signature abstraction, insurance estimates, reporting	Reports and reconciliations run tenant-scoped	Backend done; admin/reporting surfaces partial
8	RKE2/K8s manifests, Helm, Argo CD, Terraform, Ansible, observability, backups, DR	Staging manifests validate; GitOps tree complete	Reference K8s manifests for all Go services + Argo CD root; Terraform/Ansible scaffolded, blocked on procurement
9	Hardening, security scans, performance, accessibility, full E2E, restore tests, docs, completion report	Completion report issued with honest status	CI + scans + boundary checks + first E2E suites in place; full pass pending

The build must remain green after every phase.

Non-negotiable platform rules

Drafts never auto-finalize. Approval is an explicit, audited, hash-chained event.
The browser never talks to PostgreSQL, MinIO admin, OpenBao, Keycloak admin, or OpenAI.
Only ai-gateway may call OpenAI. AI_PHI_MODE gates PHI processing and defaults to disabled.
Every tenant-owned row carries clinic_id (and organization_id where relevant) and is protected by PostgreSQL row-level security.
Audit events are append-only and tamper-evident (hash chain).
No PHI in logs, traces, metrics, queue payloads, URLs, object keys, or error reports.
Transcript text is untrusted data — never instructions.
Synthetic fixtures only; they are marked synthetic: true everywhere.

Repository layout

See docs/architecture/system-overview.md and the top-level README.md for the authoritative directory map and ownership table.

Sequencing rationale

Database schema and tenancy land first because every feature depends on RLS and audit. The AI gateway lands after transcription because its inputs are versioned transcripts. Infrastructure manifests are written alongside services but validated in Phase 8 once all workloads exist.

Out-of-repo dependencies (tracked, not fabricated)

Dependency	Needed for	Status
OpenAI org with DPA + Canadian residency + ZDR	`AI_PHI_MODE=approved_phi`	Blocked on client contract
Licensed provincial fee guide data	Fee guide import	Clinic supplies licensed file
ABELDent vendor API access	Practice-management sync	Blocked on vendor agreement
SMTP/SMS production credentials	Deliveries	Client accounts
Qualified signature provider agreement (if provider-backed signing)	E-signature	Optional; built-in signing implemented
Canadian data-centre hardware + network	Production topology	Client procurement