System & Data Architecture
Enterprise architecture documentation, PostgreSQL migration roadmap, and AI integration points
Layered Clean Architecture Pattern
Strict separation of concerns ensures frontend components are completely decoupled from storage layers
UI Presentation Layer
Next.js App Router, Tailwind CSS, Recharts, Apple/Linear Design
/components /appAPI & Service Layer
Business logic, cohort queries, Kaplan-Meier engine, similarity vectors
/services /app/apiRepository Abstraction
TypeScript repository interfaces: IPatientRepository, ICohortRepository
/repositoriesStorage Engine
Current: Deterministic In-Memory. Future: PostgreSQL / Prisma
/data/generator.tsReplacing In-Memory Data with PostgreSQL
Step-by-step production database enablement
Because all components consume services through the repositories factory, switching to PostgreSQL requires zero frontend modifications:
- Implement Postgres Repositories: Create
PostgresPatientRepository.tsimplementingIPatientRepository. - Configure Database URL: Set
DATABASE_URL=postgresql://...in.env.local. - Update Repository Factory: In
/repositories/index.ts, switchRepositoryFactoryto return Postgres instances when database credentials are detected. - Frontend Zero-Change Guarantee: All UI pages and Recharts visualizations remain identical.
Future AI / LLM Extension Points
Architectural contracts ready for machine learning
Swap current deterministic regex extractor with Claude/Gemini multimodal document parsing for OCR on pathology and PET-CT scan PDFs.
Extend current rule-based parser in /api/query with Text-to-SQL / RAG embeddings for arbitrary clinical questions.
Upgrade multi-attribute Euclidean matching with clinical embeddings (BioBERT / clinical LLM vectors).
Synthetic Dataset Referential Integrity Audit
Verification assertions executed via scripts/validate-data.ts