KrinosAI — Repository README

Template ID: TPL-06-06 | Stage: 06-Build-and-Document | Version: 0.3
Record: KAI-VORAL-RDM-001 — retrospective draft for Visionary Oral. Not approved.

Purpose: Give a new engineer everything needed to understand, run, test and contribute to the repository.

Required inputs: Repository setup; environment configuration; coding standards.

Document control

Field	Required entry
Document ID	KAI-VORAL-RDM-001
Template used	TPL-06-06 Repository README 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-06 v0.3
Related issue, commit, requirement and evidence links	README.md, mobile/README.md @ a6b4429
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. Describes what a project README must contain, checked against the existing READMEs: the root README is the default Next.js template (README.md:1-36) plus a stray command (README.md:39); mobile/README.md is detailed. 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. Purpose and status

Item	Entry
Purpose	Guided 3-view dental photo scan with AI findings and a report (see KAI-VORAL-BRF-001)
Status	In use; lifecycle records drafted 2026-10-27; root README needs rewriting — OPEN-005

2. Architecture overview

Item	Link
Architecture	KAI-VORAL-HLD-001
API	KAI-VORAL-APII-001

3. Prerequisites and setup

Tool	Version	Command
Node.js	LTS (version not pinned — not recorded)	npm ci in dentalapp/ and mobile/
Python	3.x	pip install -r mobile/ml/requirements.txt
Expo CLI / EAS	via npx	npx expo start; npx eas-cli build

4. Run, test and lint

Task	Command
Run web	cd dentalapp && npm run dev
Run mobile	cd mobile && npx expo start
Test mobile	cd mobile && npx jest; npm run typecheck
Lint web	cd dentalapp && npm run lint
Test web	None — OPEN-027

5. Configuration and secrets

Variable	Purpose	Source
MONGODB_URI	See KAI-VORAL-ACC-001	Host env vars / local .env (never committed)
CLERK_SECRET_KEY	See KAI-VORAL-ACC-001	Host env vars / local .env (never committed)
CLERK_WEBHOOK_SECRET	See KAI-VORAL-ACC-001	Host env vars / local .env (never committed)
R2_ACCOUNT_ID / R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY	See KAI-VORAL-ACC-001	Host env vars / local .env (never committed)
AWS_REGION / S3_BUCKET_NAME / LAMBDA_PDF_URL	See KAI-VORAL-ACC-001	Host env vars / local .env (never committed)
OPENROUTER_API_KEY	See KAI-VORAL-ACC-001	Host env vars / local .env (never committed)
GROQ_API_KEY	See KAI-VORAL-ACC-001	Host env vars / local .env (never committed)
HF_TOKEN / ML_BACKEND_URL / FIT_VALIDATOR_URL	See KAI-VORAL-ACC-001	Host env vars / local .env (never committed)
RESEND_API_KEY / EMAIL_FROM	See KAI-VORAL-ACC-001	Host env vars / local .env (never committed)
CASHFREE_APP_ID / CASHFREE_SECRET_KEY / CASHFREE_WEBHOOK_SECRET	See KAI-VORAL-ACC-001	Host env vars / local .env (never committed)
CLOUDINARY_*	See KAI-VORAL-ACC-001	Host env vars / local .env (never committed)
JWT_SECRET	See KAI-VORAL-ACC-001	Host env vars / local .env (never committed)
PDF_ACCESS_SECRET	See KAI-VORAL-ACC-001	Host env vars / local .env (never committed)
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY	See KAI-VORAL-ACC-001	Host env vars / local .env (never committed)

6. Contributing, ownership and support

Item	Entry
Contributing	PR with review (not enforced — OPEN-038)
Ownership	Tech Lead — Sponsor (name to be assigned)
Support	SUPPORT_EMAIL (value not recorded)

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-005	Documents disagree with code: PRD/system flow say 5 views, Cloudinary and direct Gemini; code uses 3 views, Cloudflare R2/S3 storage and OpenRouter/Groq	Tech Lead	2026-11-30 (proposed)	No	Updated PRD, or a recorded decision to keep the code behaviour	Open
OPEN-027	The web app (dentalapp/) has no automated tests and no test script	Tech Lead	2026-12-15 (proposed)	Yes	Test suite and CI run for the web app	Open
OPEN-038	No branch protection, required reviews or CODEOWNERS recorded; changes are pushed directly to shared branches (app_dev, non-compliance)	Tech Lead	2026-11-15 (proposed)	Yes	Branch protection settings; PR template; CODEOWNERS	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