🏥 CureCode Technical Architecture

Complete Technical Documentation - Production System

System Overview

3
Services
20
Document Types
6
Medical Specialties

Tech Stack (TypeScript Full-Stack)

Frontend

React 18 + TypeScript SPA

React 18 TypeScript Vite TanStack Router TanStack Query Tailwind CSS TipTap Editor

Backend

2x NestJS Services

NestJS TypeScript Prisma ORM PostgreSQL JWT Auth

AI Services

Intelligent Processing

Speech-to-Text PDF/Word Extraction AI Text Generation

Infrastructure

Azure Switzerland North

Azure App Service Azure Blob Storage Docker GitHub Actions
✅ Production Status: Live system with real doctors as customers
✅ Swiss Compliance: ICD-10-GM, TARMED, FADP, GDPR
✅ Data Residency: All data remains in Switzerland (Azure Switzerland North)

✨ Key Features & Differentiators

🇨🇭 Swiss Data Sovereignty

  • 100% Swiss-hosted infrastructure
  • Azure Switzerland North (Zürich)
  • FADP & GDPR compliant by design
  • No data leaves Switzerland

🎯 Medical Domain Expertise

  • 20 Swiss medical document types
  • ICD-10-GM diagnosis coding
  • TARMED billing code integration
  • Swiss AHV number validation

⚡ Efficiency Gains

  • Audio → Document in ~3-5 minutes
  • AI-assisted medical terminology
  • Rich-text editor with auto-save
  • Multi-specialty support

🔒 Enterprise Security

  • JWT-based authentication
  • Role-based access control
  • Complete audit trail
  • Encrypted storage at rest

Three-Tier Service Architecture

PRESENTATION Layer 1 BUSINESS Layer 2 DATA Layer 3 🎯 Frontend React SPA • TipTap Editor • Tailwind REST API ⚙️ App Service Business Logic • Auth Patient • Document CRUD 🧠 AI Service Speech-to-Text • LLM Document Generation Internal API 🗄️ PostgreSQL pgvector • Prisma ORM ☁️ Azure Blob Audio • Documents • Assets

🎨 Layer 1: Frontend (curecode-app-client)

React SPA

Responsibilities:

  • Patient Management (AHV Validation)
  • Consultation Management
  • Document Generation Wizard (3-Step)
  • Rich-Text Editor (TipTap/ProseMirror)
  • File Upload UI (Audio up to 50MB)
React 18 TypeScript TanStack Router TanStack Query Tailwind CSS TipTap Editor
Production: https://[redacted]-client-prod.azurewebsites.net
Staging: https://[redacted]-client-staging.azurewebsites.net
Deployment: Azure App Service (Docker Container)
Build: Vite
↓

⚙️ Layer 2: Backend Services

curecode-app-service

Main Business Logic API

  • Patient CRUD
  • Consultation CRUD
  • Document CRUD
  • User Management
  • JWT Authentication
  • Organisation Management
NestJS TypeScript Prisma ORM PostgreSQL
Deployment: Azure App Service (Docker)
Database: PostgreSQL with Prisma ORM
API Docs: OpenAPI/Swagger

curecode-ai-service

AI Processing Service

  • Audio Transcription (Whisper)
  • Document Extraction (PDF/DOCX)
  • AI Document Generation (LLM)
  • Azure Blob Storage Management
  • Retry Logic & Error Handling
NestJS Speech-to-Text Document Extraction Azure Blob
Deployment: Azure App Service (Docker)
Storage: Azure Blob for audio/documents
Max Upload: 50MB
↓

💾 Layer 3: Data & Storage

PostgreSQL Database

Schema Isolation:

  • Business logic schema (patients, docs, users)
  • AI processing schema (transcriptions, completions)
PostgreSQL 15 pgvector extension Prisma Migrations

Azure Blob Storage

File Storage:

  • Audio files (MP3, M4A, WAV, WEBM)
  • Uploaded documents (PDF, DOCX)
  • Organisation logos
Azure Blob Encrypted
🔒 Security: All services communicate via JWT Tokens. No API keys in the frontend. CORS is strictly configured for Production & Staging domains.

Complete Data Flow: Audio → Final Document

Step 1: User Authentication

Flow:

  1. User logs in with email/password
  2. Backend verifies credentials securely
  3. JWT token generated and returned
  4. Frontend stores token for subsequent requests
Authentication: JWT-based
Password Storage: bcrypt hashed
Session: Secure token management

Step 2: Patient Selection/Creation

Flow:

  1. Frontend fetches patient list for organisation
  2. User selects existing patient or creates new
  3. Swiss AHV number validation applied
  4. Patient record loaded with insurance data
Validation: Swiss AHV format (756.XXXX.XXXX.XX)
Data: Patient demographics + insurance info

Step 3: Consultation Creation

Flow:

  1. User creates new consultation for patient
  2. Consultation record linked to user and patient
  3. Consultation date recorded
  4. Ready for audio upload
Relationships: User → Consultation → Patient
Tracking: Full audit trail maintained

Step 4: Audio Upload & Transcription

Flow:

  1. User uploads audio file (up to 50MB)
  2. File securely stored in cloud storage
  3. Transcription job queued
  4. Whisper API processes audio to text
  5. Frontend polls for completion status
  6. Transcription text ready for document generation
Transcription: Whisper API (configurable vendor)
Language: German (Swiss medical terminology)
Reliability: Automatic retry with backoff

Step 5: Document Generation Wizard

Flow:

  1. Step 1: Select Medical Specialty
  2. Step 2: Select Document Type (20 types available)
  3. Step 3: Select Sections to include
  4. User clicks "Generate with AI"
UI: 3-step wizard interface
Customization: Specialty-specific templates

Step 6: AI Document Generation

Flow:

  1. Backend retrieves transcription text
  2. Loads appropriate prompt template
  3. Constructs prompt with:
    • Transcription content
    • Selected document sections
    • Doctor and organisation context
    • Swiss medical coding guidelines
  4. LLM generates structured medical document
  5. Document formatted for rich-text editor
  6. Saved to database for review
AI Model: LLM (configurable vendor)
Compliance: ICD-10-GM + TARMED guidelines
Processing: ~10-20 seconds

Step 7: Document Review & Edit

Flow:

  1. Document opens in rich-text editor
  2. Doctor reviews AI-generated content
  3. Full editing capabilities (Word-like experience)
  4. Auto-save ensures no work is lost
  5. Document progresses through workflow states
Editor: TipTap (ProseMirror-based)
Features: Formatting, tables, lists, headings
Save: Automatic with manual option

Step 8: Document Finalization

Flow:

  1. Doctor clicks "Approve"
  2. Document status updated to approved
  3. Audit trail entry recorded
  4. Document linked to consultation record
  5. Ready for export (PDF, print)
Workflow: Draft → Pending → Approved
Audit: Complete history of all changes
Export: PDF generation available
⚡ Performance Metrics:
50MB Audio: ~2-4 minutes transcription
Document Generation: ~10-20 seconds
Total Time: Audio → Final Document = ~3-5 minutes

Data Management Capabilities

🗄️ PostgreSQL Switzerland North 🏢 Multi- Tenant 🔍 Semantic Search 📝 Audit Trail 🔐 Role-Based Access 🗑️ Soft Delete 🔒 Encrypted Storage

🏢 Multi-Tenant Isolation

Complete data separation between medical practices. Each organisation's data is logically isolated with enforced access boundaries.

Row-Level Security Organisation Scoping

🔍 AI-Powered Search

Semantic search across medical documents using vector embeddings. Find relevant patient history using natural language queries.

Vector Similarity Natural Language

📝 Complete Audit Trail

Every document modification is logged with timestamp, user, and action type. Full history for compliance and accountability.

Immutable Logs User Attribution

🔐 Access Control

Role-based permissions from System Admin to standard users. Specialty-specific access and organisation-level administration.

4 Permission Levels JWT Claims

🗑️ Data Recovery

Soft delete pattern ensures no accidental data loss. Records can be recovered within retention period. Hard delete for GDPR compliance.

Soft Delete GDPR Right to Erasure

🇨🇭 Swiss Data Residency

All data stored exclusively in Azure Switzerland North (Zürich). Encrypted at rest and in transit. FADP & GDPR compliant.

AES-256 Encryption TLS 1.3
🛠️ Technology Foundation: PostgreSQL database with modern ORM • Automated schema migrations • Service-level isolation

Azure Switzerland North Deployment

🌍 Azure Resources

Region: Switzerland North (Zürich)
Environments: Production + Staging
Compliance: FADP & GDPR compliant hosting
Compute: Azure App Service (Linux)
Runtime: Docker Containers
Scaling: Horizontal scaling ready

🚀 Production Environment

Frontend App

React SPA

Runtime: Docker Container
Image Tag: :prod
Status: ✅ Running

Backend API

Main Business Logic

Runtime: Docker Container
Image Tag: :prod
Status: ✅ Running

AI Service

AI Processing

Runtime: Docker Container
Image Tag: :prod
Status: ✅ Running

🧪 Staging Environment

Frontend App

React SPA

Runtime: Docker Container
Image Tag: :staging
Status: ✅ Running

Backend API

Main Business Logic

Runtime: Docker Container
Image Tag: :staging
Status: ✅ Running

AI Service

AI Processing

Runtime: Docker Container
Image Tag: :staging
Status: ✅ Running

Database

Azure Database for PostgreSQL Flexible Server

Hosting: Azure Database for PostgreSQL Flexible Server
Version: PostgreSQL 15
Extensions: pgvector (semantic search), pg_trgm
Architecture: Multi-schema isolation
Compute: Production tier (auto-scaling)
Backup: Automated with retention policy

Storage

Azure Blob Storage

Purpose: Audio files, uploaded documents, organisation assets
Encryption: Server-side encryption at rest
Access: Private containers with SAS tokens
Region: Switzerland North (data residency)

CI/CD Pipeline (GitHub Actions)

Build & Deploy Workflow

Production Deployment:

  1. Create/push prod Git tag
  2. GitHub Actions triggers production build
  3. Run tests (npm test)
  4. Build Docker image with :prod tag
  5. Push to Azure Container Registry
  6. Deploy to Production App Services
  7. Health check verification

Staging Deployment:

  1. Create/push staging Git tag
  2. GitHub Actions triggers staging build
  3. Build Docker image with :staging tag
  4. Deploy to Staging App Services
Registry: Azure Container Registry

Image Tagging Strategy:
  • Production: :prod tag
  • Staging: :staging tag

Services: Frontend, Backend API, AI Service
✅ Swiss Data Residency: All services and databases run in Switzerland (Switzerland North).
✅ Compliance: FADP & GDPR compliant through Swiss Azure deployment.
✅ Security: HTTPS enforced, JWT tokens, CORS configured, Azure AD authentication.
🔒 Secrets Management:
All sensitive configuration (API keys, connection strings) stored securely in Azure App Service.
No secrets in code, Git repository, or Docker images.