Architecture Overview

Noumaris is a healthcare SaaS platform for clinical documentation and AI-powered scribing.

System Architecture

graph TB
    subgraph "Client Layer"
        Web[React Frontend<br/>Vite + TailwindCSS]
        Mobile[Mobile App<br/>Planned Q1 2026]
    end

    subgraph "Authentication"
        KC[Keycloak<br/>Port 8081<br/>Self-Hosted]
    end

    subgraph "Application Layer"
        API[FastAPI Backend<br/>Port 8000]
        WS[WebSocket Handler<br/>/transcribe]
    end

    subgraph "External Services"
        DG[Deepgram<br/>Transcription]
        CL[Claude API<br/>Note Generation]
    end

    subgraph "Data Layer"
        PG[(PostgreSQL<br/>Port 5433)]
    end

    Web -->|JWT Auth| KC
    Web -->|HTTP/WSS| API
    API -->|Validate Token| KC
    API -->|Query| PG
    WS -->|Stream Audio| DG
    API -->|Generate Notes| CL

    style KC fill:#f9f,stroke:#333,stroke-width:2px
    style API fill:#bbf,stroke:#333,stroke-width:2px
    style PG fill:#bfb,stroke:#333,stroke-width:2px

Architecture Components

Backend Architecture

• FastAPI-based REST API
• 23+ endpoints (superadmin, institution admin, clinical docs)
• WebSocket live transcription
• PostgreSQL with SQLAlchemy ORM
• Keycloak JWT authentication
• Role-based access control (RBAC)

Frontend Architecture

• React 18 with React Router v7
• React Query for data fetching
• TailwindCSS + Radix UI components
• Keycloakify custom theme
• TipTap rich text editor for clinical notes

Infrastructure

• Docker Compose for local dev
• Google Cloud Run for production (Canada + US regions)
• Terraform for infrastructure as code
• Cloud Build for CI/CD
• VPC connectors for private DB access

Key Design Decisions

• Why Keycloak? - Self-hosted auth for HIPAA compliance
• Why FastAPI? - Async, type-safe, auto docs
• Why Claude? - 200k context, cost-effective
• Why Terraform? - Infrastructure as code

Data Flow

Clinical Note Generation

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    participant Deepgram
    participant Claude
    participant DB

    User->>Frontend: Start encounter
    Frontend->>Backend: POST /documents/new
    Backend->>DB: Create document
    Backend-->>Frontend: encounter_id

    User->>Frontend: Record audio
    Frontend->>Backend: WebSocket /transcribe
    Backend->>Deepgram: Stream audio
    Deepgram-->>Backend: Transcript (interim/final)
    Backend-->>Frontend: Display transcript

    User->>Frontend: Generate note
    Frontend->>Backend: POST /summarize_transcription
    Backend->>Claude: Template + Transcript
    Claude-->>Backend: Structured JSON
    Backend->>Backend: Convert to TipTap
    Backend->>DB: Save document
    Backend-->>Frontend: Formatted note
    Frontend-->>User: Display editable note

Detailed Documentation

• Backend Architecture →
• Frontend Architecture →
• Infrastructure →