KrinosAI — High-Level Design (HLD)
Template ID: TPL-03-01 | Stage: 03-Design | Version: 0.3
Record: KAI-VORAL-HLD-001 — retrospective draft for Visionary Oral. Not approved.
Purpose: Describe the system architecture — context, containers, components, data stores, integrations, security and resilience — at a level a new engineer can follow.
Required inputs: Baselined SRS; DPIA; current architecture (for existing systems: repository, infrastructure code, deployment manifests).
Document control
| Field |
Required entry |
| Document ID |
KAI-VORAL-HLD-001 |
| Template used |
TPL-03-01 High-Level Design (HLD) v0.3 |
| Product / project / software version or commit SHA |
VORAL (Visionary Oral) / PRJ-001 / a6b4429e3165 (branch app_dev of AI-Dental-Project/Visionary_Oral) |
| Record status and version |
Draft v0.1 |
| Author / technical reviewer / quality reviewer |
Claude Code (drafted with Claude Code for KrinosAI) / Tech Lead (name to be assigned) / Security & Privacy Officer (name to be assigned) |
| Created / updated / approved dates |
2026-10-27 / 2026-10-27 / Pending |
| Applicable SOP and revision |
SOP-LC-03 v0.3 |
| Related issue, commit, requirement and evidence links |
KAI-VORAL-SRS-001, KAI-VORAL-DPIA-001, KAI-VORAL-IRS-001, KAI-VORAL-DEC-001; docs/lifecycle/_evidence/api-inventory-a6b4429.md |
| Approver and decision record |
Pending |
Applicability and evidence baseline
Product / system boundary: Web app and API (dentalapp/), doctor/admin mobile app (mobile/), PDF Lambda (dentalapp/pdf-lambda/) at a6b4429e3165, and the external services they call.
Related approved requirements, risks and change records: None approved. Related drafts are listed in document control.
Retrospective record? Yes — follows the Retrospective Documentation Protocol (KrinosAI lifecycle pack, 05-References/). Items are labelled Observed (code or Git at a6b4429), Measured (dated run), Stated (named person, dated) or Not recorded. Design is documented as built (observed in code at a6b4429); no prior design documents exist except the ADRs in mobile/docs/ml-repo/adr/ (summarised in KAI-VORAL-DEC-001).
Acceptable evidence: an implementation reference (file:line at a commit SHA), a dated test record, a signed decision, a vendor agreement, or another independently verifiable artifact. Never invent approvals, clinical results, measurements or performance data.
1. System context and actors
| Actor / external system |
Interaction |
Protocol |
| Doctor (web/mobile) |
Patients, scans, reports |
HTTPS (browser / app) |
| Admin (web/mobile) |
Doctor management, usage |
HTTPS |
| Patient (web, QR) |
Self-registration, own report |
HTTPS |
| Clerk |
Sign-in, sessions, invitations, webhooks |
HTTPS / webhooks |
| MongoDB |
All application data |
MongoDB driver (MONGODB_URI) |
| Cloudflare R2 / AWS S3 |
Photos; PDFs |
S3 API |
| ML service (Hugging Face Space) |
Server detections |
HTTPS (ML_BACKEND_URL, HF_TOKEN) |
| OpenRouter (Gemini), Groq |
AI text, image analysis, transcription |
HTTPS |
| Resend |
Email |
HTTPS |
| Cashfree |
Payments |
HTTPS / webhooks |
| Expo EAS |
App builds and updates |
HTTPS |
2. Deployment environments and C4 containers
| Container |
Technology |
Runs on |
Source |
| Web app + API |
Next.js 16 (dentalapp/package.json:25) |
Vercel or Render — not recorded (OPEN-022) |
dentalapp/ |
| PDF Lambda |
Node.js, puppeteer-core, @sparticuz/chromium |
AWS Lambda (LAMBDA_PDF_URL) |
dentalapp/pdf-lambda/ |
| Mobile app |
Expo SDK 57, React Native, onnxruntime-react-native |
Android/iOS phones; builds on Expo EAS (krinos_ai) |
mobile/ |
| ML service |
Python (separate repo) |
Hugging Face Space |
Visionary_oral_ML (external) |
| Database |
MongoDB (driver 6.x) |
Host not recorded (OPEN-016) |
— |
Figure 1 — Containers and external services (C4 container level). Hosting of the web app and the database are not recorded (OPEN-022, OPEN-016).
flowchart LR
doctor(["Doctor / admin"]) --> mobile["Mobile app<br/>Expo / React Native<br/>on-device ONNX models"]
doctor --> web["Web app + API<br/>Next.js 16"]
patient(["Patient (clinic QR)"]) --> web
mobile -->|HTTPS JSON| web
web --> db[("MongoDB")]
web --> r2[("Cloudflare R2<br/>scan photos")]
web --> ml["ML service<br/>Hugging Face Space"]
web --> ai["OpenRouter / Groq<br/>AI text"]
web --> pdf["PDF Lambda<br/>AWS"] --> s3[("AWS S3<br/>reports")]
web --> mail["Resend<br/>email"]
clerk["Clerk<br/>sign-in"] -->|signed webhook| web
cash["Cashfree<br/>payments"] <-->|webhook / API| web
mobile --> clerk
web --> clerk
3. Components and responsibilities
| DES ID |
Component |
Responsibility |
Owner |
| DES-01 |
Web front end (Next.js pages: scan, results, dashboards, admin) |
UI for doctors, admins and patients |
Backend Lead |
| DES-02 |
API layer (Next.js route handlers, 75 files) |
All business logic and data access |
Backend Lead |
| DES-03 |
Auth and roles (Clerk + auth-helpers.js + middleware) |
Identity, role, account status checks |
Backend Lead |
| DES-04 |
Patient service (patients APIs) |
Patient records and ownership |
Backend Lead |
| DES-05 |
Scan and upload service |
Scan documents, photo upload to R2 |
Backend Lead |
| DES-06 |
Server analysis orchestration (ML service + OpenRouter/Groq) |
Detections, annotated images, AI text |
ML Lead |
| DES-07 |
Report calculation and rendering |
Counts, risk levels, overall score; print page |
Backend Lead |
| DES-08 |
PDF Lambda |
Headless Chromium renders print page to PDF; S3 |
Backend Lead |
| DES-09 |
Admin console services |
Invite, approve, suspend, offline limit, usage, plans |
Backend Lead |
| DES-10 |
Billing service (Cashfree) |
Orders, subscriptions, webhooks |
Backend Lead |
| DES-11 |
Public QR registration and public scan sessions |
Patient self-registration; token sessions |
Backend Lead |
| DES-12 |
Mobile app shell (Expo Router, role gate, offline lock) |
Navigation by role; suspension and offline gate |
Mobile Lead |
| DES-13 |
Mobile offline store and sync (SQLite queue, patient outbox, sync manager) |
Offline capture, retries, upload |
Mobile Lead |
| DES-14 |
Mobile on-device ML (ONNX runtime, quality gate, detectors) |
Quality check and findings on the phone |
ML Lead |
| DES-15 |
Mobile report (renderer bundle, offline cache, PDF) |
Same report design as web, offline |
Mobile Lead |
| DES-16 |
Notifications, email and support |
Resend email, in-app notifications, support chat |
Backend Lead |
4. Data stores and service boundaries
| Store |
Holds |
Owner (writes) |
Readers |
MongoDB profiles |
Doctors, admins, patients' accounts |
DES-03, DES-09 |
Most APIs |
MongoDB patients |
Patient records |
DES-04, DES-11 |
DES-05, DES-06, DES-07 |
MongoDB scans |
Scan sessions, photo links, findings |
DES-05, DES-06 |
DES-07, DES-08, mobile |
| Cloudflare R2 |
Photos, annotated images, logos |
DES-05, DES-06 |
DES-07 via /api/image |
| AWS S3 |
Report PDFs |
DES-08 |
Download links |
| Phone SQLite + files |
Offline queue, caches |
DES-13, DES-15 |
Mobile only |
5. Integration architecture and protocol choices
| From → to |
Mechanism |
Failure behavior |
| Mobile/web → API |
HTTPS JSON; bearer token (mobile) or cookie (web) |
Mobile retries and queues offline (DES-13) |
| API → ML service |
HTTPS multipart, scan_type per view |
Analysis fails; report without server findings |
| API → OpenRouter/Groq |
HTTPS chat completions |
Fallback text / error |
| Clerk/Cashfree → API |
Signed webhooks |
Rejected if signature invalid; Cashfree logged in webhookLogs |
| API → PDF Lambda |
HTTPS |
Download fails; mobile renders PDF on the phone instead |
6. Security and trust boundaries
| Boundary |
AuthN |
Encryption |
| Internet → API |
Clerk session/token; 20 routes have none (OPEN-026, OPEN-033) |
TLS (hosting) |
| API → vendors |
API keys from env vars |
TLS |
| Phone storage |
Device lock only; no app-level encryption found |
Not recorded — OPEN-029 |
| Admin vs doctor |
Role from profiles (DES-03) |
— |
7. Reliability and disaster recovery approach
| Item |
Design |
| Backups |
Not recorded — OPEN-035 |
| Disaster recovery / RTO, RPO |
Not recorded — OPEN-035 |
| ML service cold start |
Keep-awake job every 5 min (.github/workflows/keep-hf-awake.yml:5) |
| Offline resilience (mobile) |
Capture and analysis work offline; sync later (DES-13, DES-14) |
8. Architecture risk decisions and review
| Item |
Link / outcome |
| Architecture decisions |
KAI-VORAL-ADR-001 (ADR-001 to ADR-005) |
| Threat model |
KAI-VORAL-THM-001 |
| Review |
Pending — OPEN-001 |
Open issues and decisions
| ID |
Specific gap or decision |
Responsible owner |
Due date |
Blocks gate? |
Evidence required |
Status |
| OPEN-001 |
Tracker project ID, named requester and sponsor, and named reviewers are not recorded |
Product Owner |
2026-11-10 (proposed) |
Yes |
Tracker entry; names with roles |
Open |
| OPEN-016 |
Data regions and transfers |
Security & Privacy Officer |
2026-11-30 (proposed) |
Yes |
Transfer assessment |
Open |
| OPEN-017 |
Admin session signing uses a hard-coded fallback secret when JWT_SECRET is unset (dentalapp/src/lib/admin/session.js:4) |
Backend Lead |
2026-11-10 (proposed) |
Yes |
Code fix; secret confirmed set |
Open |
| OPEN-022 |
Production hosting (Vercel vs Render), deployed version and dated integration checks for Clerk, MongoDB, R2, AWS, OpenRouter, Groq, Cashfree and Resend not recorded |
Tech Lead |
2026-11-30 (proposed) |
No |
Environment record (stage 05) with dated checks |
Open |
| OPEN-026 |
Critical: 20 API routes have no authentication check, incl. /api/admin/patient-sample (patient emails) and /api/admin/api-usage (doctor names and emails), support tickets/messages, and paid AI routes (/api/detect-gemini, /api/speech-to-text, /api/validate-scan) — see docs/lifecycle/_evidence/api-inventory-a6b4429.md |
Backend Lead |
2026-10-31 (proposed) |
Yes |
Auth added to each route; re-run of the inventory shows none unprotected |
Open |
| OPEN-029 |
No retention or deletion periods for patient data, photos, reports, backups or phone caches |
Security & Privacy Officer |
2026-11-30 (proposed) |
Yes |
Retention schedule in the DPIA |
Open |
| OPEN-033 |
Critical: deprecated POST /api/admin/signup is public and creates admin profiles with a password for anyone (dentalapp/src/app/api/admin/signup/route.js:14-60); POST /api/admin/auth issues admin sessions signed with a fallback secret (OPEN-017). Full privilege path not verified |
Backend Lead |
2026-10-31 (proposed) |
Yes |
Routes removed or locked down; check that no password-based admin can sign in |
Open |
| OPEN-035 |
No database schema definition, migrations or index plan in the repository (MongoDB collections created implicitly); backup and restore not recorded |
Backend Lead |
2026-11-30 (proposed) |
No |
Schema/validation rules and index list; backup and restore test |
Open |
Review and approval
| Review role |
Named individual |
Decision |
Date |
Signed / controlled record |
| Author |
Claude Code (drafted with Claude Code) |
Draft |
2026-10-27 |
This file at the commit that adds it |
| Technical reviewer |
Tech Lead (name to be assigned) |
Pending |
Pending |
Pending |
| Quality / regulatory reviewer (if applicable) |
Qualified regulatory reviewer (name to be assigned) |
Pending |
Pending |
Pending |
| Authorized approver |
Tech Lead (name to be assigned) |
Pending |
Pending |
Pending |