# arman-rsheik/oralcare_ai architecture

> Architecture diagram of the GitHub repository arman-rsheik/oralcare_ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arman-rsheik/oralcare_ai
- Repository: https://github.com/arman-rsheik/oralcare_ai

## Overview

This is a **full-stack clinical screening web app** with:
- **Frontend SPA** (Vanilla JS + Vite) that drives a **chat-based intake wizard**, uploads an oral cavity image, shows results, and generates a **PDF report client-side**.
- **Backend API** (FastAPI) that:
- runs **image inference** using a pre-trained **EfficientNetV2-B3** checkpoint
- runs a deterministic **risk stratification engine** (0–100)
- calls an external **Groq LLM** for answer validation/parsing, chat, and report content
- Optional **training pipeline** (TensorFlow/Keras) used offline to produce `checkpoints/best_model.weights.h5` (not generated at runtime).

##### Runtime serving path (browser ↔ FastAPI ↔ model/risk/LLM services)
2) **Offline training path** (dataset → training code → checkpoint artifact → used by runtime inference)

##### Backend (runtime)
- `backend/main.py` — **FastAPI server**: route definitions, static/frontend serving, API orchestration
- `backend/services/model_service.py` — **Image inference service** (lazy-loaded model weights)
- `backend/services/risk_engine.py` — **Risk scoring service** (5-section habits scoring)
- `backend/services/groq_chat.py` — **LLM integration**:
- parse/validate answers
- chat (streaming SSE and non-streaming)
- report generation (structured clinical summary)
- `backend/core/config.py` — **Configuration** (image size, paths, hyperparams, dataset dir)
- `checkpoints/best_model.weights.h5` (mentioned in README) — **Model artifact** required for inference

- `backend/core/train.py` — **Training pipeline** (phase 1 + phase 2 fine-tuning)
- `backend/core/dataset.py` — **Data loading & augmentation**
- `backend/core/models.py` — **EfficientNetV2-B3 definition**
- Output artifact: `checkpoints/best_model.weights.h5`

##### Frontend
- `frontend/src/main.js` — **Chat wizard UI**, state machine, API calls, PDF generation (jsPDF)
- `frontend/vite.config.js` — **Dev proxy** `/api/*` → backend `localhost:8000`
- `frontend/index.html`, `style.css` — static assets

- `test_api.py`, `test_risk*.py` — basic validation of endpoints and risk scoring
- `scripts/benchmarks/inference.py` — inference benchmarking
- `pyproject.toml` — Python deps (uv-managed)
- `.env` — `GROQ_API_KEY`

##### What to include from README (critical runtime interactions)
- `POST /api/predict` → image classifier inference
- `POST /api/risk-score` → habit risk scoring
- `POST /api/parse-answer` → LLM answer parsing/validation
- `POST /api/chat-stream` → LLM streaming chat (SSE)
- `POST /api/chat` → LLM non-streaming
- `POST /api/report` → LLM structured report generation
- `GET /` → serves frontend

External dependency:
- **Groq API** (Llama 3.3 70B)

And client-side capability:
- **PDF generation in browser** (jsPDF). The backend produces report content; browser renders/downloads PDF.

##### Architectural patterns to highlight (specific to this project)
- **Service decomposition inside a monolith**: one FastAPI app with distinct service modules:
- `model_service` (ML inference)
- `risk_engine` (rules/scoring)
- `groq_chat` (LLM adapter)
- **Adapter pattern** for external LLM: `groq_chat.py` wraps Groq API and exposes domain-specific functions (parse answer, report, chat).
- **Artifact-based ML deployment**: trained weights are a file-based dependency, loaded lazily at runtime.
- **Client-orchestrated workflow**: frontend drives a stepwise wizard; backend provides stateless computations (inference, scoring, LLM).

##### Split into internal calls
- Model Service → Checkpoints
- Risk Engine
- Groq Chat Service → Groq Cloud API
##### Back to Browser
- Results + PDF generation (jsPDF)

Dataset → dataset.py → models.py → train.py → weights file → used by model_service.py

## Diagram (Mermaid)

```mermaid
flowchart TD

  %% =========================
  %% Diagram 1: Runtime Serving Path
  %% =========================
  subgraph "Runtime Architecture (Serving Path)"
    direction TB

    subgraph "Client / Presentation (Browser)"
      direction TB
      USER["User"]:::external
      BROWSER["User Browser"]:::external
      FE_UI["Chat Wizard UI (Vanilla JS SPA)"]:::frontend
      FE_PDF["PDF Generation (jsPDF, client-side)"]:::frontend
      USER -->|"uses"| BROWSER
      BROWSER -->|"runs"| FE_UI
      FE_UI -->|"renders/downloads"| FE_PDF
    end

    subgraph "Frontend Delivery (Prod Runtime)"
      direction TB
      FE_SHELL["Frontend Static Assets (HTML/CSS/JS)"]:::frontend
      FE_HTML["HTML Shell (index.html)"]:::frontend
      FE_CSS["Styling (style.css)"]:::frontend
      FE_ENTRY["SPA Entry (main.js)"]:::frontend
      FE_SHELL -->|"includes"| FE_HTML
      FE_SHELL -->|"includes"| FE_CSS
      FE_SHELL -->|"includes"| FE_ENTRY
    end

    subgraph "Backend API (FastAPI Monolith w/ Internal Services)"
      direction TB

      FASTAPI["FastAPI App & Static Server (backend/main.py)"]:::api

      subgraph "Routes (HTTP + SSE)"
        direction TB
        R_GET["GET / (serve SPA)"]:::route
        R_PARSE["POST /api/parse-answer (JSON)"]:::route
        R_RISK["POST /api/risk-score (JSON)"]:::route
        R_PRED["POST /api/predict (multipart image)"]:::route
        R_CHAT_SSE["POST /api/chat-stream (SSE stream)"]:::route
        R_CHAT["POST /api/chat (JSON)"]:::route
        R_REPORT["POST /api/report (JSON)"]:::route
      end

      subgraph "Internal Services (Decomposed Modules)"
        direction TB
        MODEL_SVC["Model Service (EfficientNetV2-B3 inference)"]:::service
        RISK_ENG["Risk Engine (deterministic 0–100)"]:::service
        GROQ_SVC["Groq Chat Service (LLM adapter)"]:::service
      end

      subgraph "Configuration"
        direction TB
        CFG["Backend Config (core/config.py)"]:::config
        ENV[".env (GROQ_API_KEY)"]:::config
      end
    end

    subgraph "Artifacts / External Systems"
      direction TB
      CKPT["Model Checkpoint Artifact (best_model.weights.h5)"]:::artifact
      GROQ_API["Groq Cloud API (Llama 3.3 70B)"]:::externalSvc
      NOTE_NODB["Note: No database (client-managed state)"]:::note
    end

    %% ---- Runtime flows (Browser <-> FastAPI) ----
    FE_UI -->|"HTTP GET / (HTML/CSS/JS)"| FASTAPI
    FASTAPI -->|"serves static assets"| FE_SHELL

    FE_UI -->|"HTTP POST /api/parse-answer (free-text JSON)"| FASTAPI
    FE_UI -->|"HTTP POST /api/risk-score (habits JSON)"| FASTAPI
    FE_UI -->|"HTTP POST /api/predict (multipart image)"| FASTAPI
    FE_UI -->|"HTTP POST /api/report (intake+results JSON)"| FASTAPI
    FE_UI -->|"HTTP POST /api/chat (JSON)"| FASTAPI
    FE_UI -->|"SSE POST /api/chat-stream (stream)"| FASTAPI

    %% ---- FastAPI routes wiring ----
    FASTAPI -->|"handles"| R_GET
    FASTAPI -->|"handles"| R_PARSE
    FASTAPI -->|"handles"| R_RISK
    FASTAPI -->|"handles"| R_PRED
    FASTAPI -->|"handles"| R_CHAT_SSE
    FASTAPI -->|"handles"| R_CHAT
    FASTAPI -->|"handles"| R_REPORT

    %% ---- Internal orchestration ----
    FASTAPI -->|"run inference"| MODEL_SVC
    MODEL_SVC -->|"lazy load weights/read"| CKPT

    FASTAPI -->|"compute score"| RISK_ENG

    FASTAPI -->|"parse/validate answers"| GROQ_SVC
    FASTAPI -->|"chat completion"| GROQ_SVC
    FASTAPI -->|"report generation"| GROQ_SVC
    GROQ_SVC -->|"HTTPS LLM completion/stream"| GROQ_API

    %% ---- Config inputs ----
    CFG -->|"settings (paths,image size,hyperparams)"| FASTAPI
    CFG -->|"settings"| MODEL_SVC
    CFG -->|"settings"| RISK_ENG
    CFG -->|"settings"| GROQ_SVC
    ENV -->|"API key"| GROQ_SVC

    %% ---- Client-side PDF ----
    FASTAPI -->|"returns report content (JSON/text)"| FE_UI
    FE_UI -->|"builds PDF from report content"| FE_PDF

    %% ---- Notes ----
    NOTE_NODB -.->|"no persistent storage layer in repo"| FASTAPI
  end

  %% =========================
  %% Diagram 2: Offline Training & Artifact Flow
  %% =========================
  subgraph "Offline Training & Artifact Lifecycle (Optional)"
    direction TB

    DATASET_DIR["Dataset Directory (Config.DATASET_DIR)"]:::data
    DATASET_LOADER["Dataset Loader & Augmentation (core/dataset.py)"]:::offline
    MODEL_DEF["Model Definition (EfficientNetV2-B3, core/models.py)"]:::offline
    TRAIN_ORCH["Training Orchestrator (core/train.py)"]:::offline
    PHASE1["Phase 1: Head-only training"]:::offlineStep
    PHASE2["Phase 2: Fine-tuning"]:::offlineStep
    OUT_CKPT["Output: checkpoints/best_model.weights.h5"]:::artifact

    DATASET_DIR -->|"load/augment"| DATASET_LOADER
    DATASET_LOADER -->|"batches"| TRAIN_ORCH
    MODEL_DEF -->|"build model"| TRAIN_ORCH
    TRAIN_ORCH -->|"runs"| PHASE1
    PHASE1 -->|"then"| PHASE2
    PHASE2 -->|"writes"| OUT_CKPT

    OUT_CKPT -->|"used by runtime inference"| MODEL_SVC
  end

  %% =========================
  %% Dev / Supporting Lane
  %% =========================
  subgraph "Dev & Supporting Tooling (Non-prod Runtime)"
    direction TB
    VITE_CFG["Vite Dev Proxy Config (vite.config.js)"]:::dev
    BENCH["Inference Benchmark (scripts/benchmarks/inference.py)"]:::dev
    TEST_API["API Endpoint Tests (test_api.py)"]:::test
    TEST_RISK["Risk Engine Unit Tests (test_risk.py)"]:::test
    TEST_RISK_API["Risk API Tests (test_risk_api.py)"]:::test
    PYPROJ["Python Project Metadata (pyproject.toml)"]:::dev

    VITE_CFG -.->|"dev proxy /api/* -> localhost:8000"| FASTAPI
    BENCH -.->|"calls inference"| MODEL_SVC
    TEST_API -.->|"tests endpoints"| FASTAPI
    TEST_RISK -.->|"tests scoring"| RISK_ENG
    TEST_RISK_API -.->|"tests /api/risk-score"| FASTAPI
    PYPROJ -.->|"deps (uv-managed)"| FASTAPI
  end

  %% =========================
  %% Click Events (from component mapping)
  %% =========================
  click FASTAPI "https://github.com/arman-rsheik/oralcare_ai/blob/main/backend/main.py"
  click CFG "https://github.com/arman-rsheik/oralcare_ai/blob/main/backend/core/config.py"
  click MODEL_SVC "https://github.com/arman-rsheik/oralcare_ai/blob/main/backend/services/model_service.py"
  click RISK_ENG "https://github.com/arman-rsheik/oralcare_ai/blob/main/backend/services/risk_engine.py"
  click GROQ_SVC "https://github.com/arman-rsheik/oralcare_ai/blob/main/backend/services/groq_chat.py"
  click TRAIN_ORCH "https://github.com/arman-rsheik/oralcare_ai/blob/main/backend/core/train.py"
  click DATASET_LOADER "https://github.com/arman-rsheik/oralcare_ai/blob/main/backend/core/dataset.py"
  click MODEL_DEF "https://github.com/arman-rsheik/oralcare_ai/blob/main/backend/core/models.py"
  click FE_ENTRY "https://github.com/arman-rsheik/oralcare_ai/blob/main/frontend/src/main.js"
  click FE_HTML "https://github.com/arman-rsheik/oralcare_ai/blob/main/frontend/index.html"
  click FE_CSS "https://github.com/arman-rsheik/oralcare_ai/blob/main/frontend/src/style.css"
  click VITE_CFG "https://github.com/arman-rsheik/oralcare_ai/blob/main/frontend/vite.config.js"
  click BENCH "https://github.com/arman-rsheik/oralcare_ai/blob/main/scripts/benchmarks/inference.py"
  click TEST_API "https://github.com/arman-rsheik/oralcare_ai/blob/main/test_api.py"
  click TEST_RISK "https://github.com/arman-rsheik/oralcare_ai/blob/main/test_risk.py"
  click TEST_RISK_API "https://github.com/arman-rsheik/oralcare_ai/blob/main/test_risk_api.py"
  click PYPROJ "https://github.com/arman-rsheik/oralcare_ai/blob/main/pyproject.toml"

  %% =========================
  %% Styles
  %% =========================
  classDef frontend fill:#d6ecff,stroke:#1b65a6,stroke-width:1.5px,color:#0b2b44;
  classDef api fill:#bfe3ff,stroke:#0b4f8a,stroke-width:2px,color:#07243f;
  classDef route fill:#e8f4ff,stroke:#2a74b9,stroke-width:1px,color:#0b2b44;
  classDef service fill:#cfe7ff,stroke:#145a9c,stroke-width:1.5px,color:#07243f;
  classDef external fill:#f2f2f2,stroke:#6b6b6b,stroke-width:1.5px,color:#222;
  classDef externalSvc fill:#eadcff,stroke:#6b2fb8,stroke-width:2px,color:#2c0f52;
  classDef artifact fill:#d9f5d9,stroke:#2e7d32,stroke-width:2px,color:#103b16;
  classDef config fill:#fff1cc,stroke:#b7791f,stroke-width:1.5px,color:#3a2606;
  classDef offline fill:#ffe0cc,stroke:#c05621,stroke-width:1.5px,color:#3a1f0e;
  classDef offlineStep fill:#fff0e6,stroke:#c05621,stroke-width:1px,color:#3a1f0e;
  classDef data fill:#e3ffe3,stroke:#2f855a,stroke-width:1.5px,color:#103b16;
  classDef dev fill:#eeeeee,stroke:#666666,stroke-width:1.5px,color:#222,stroke-dasharray: 5 5;
  classDef test fill:#f3e8ff,stroke:#6b46c1,stroke-width:1.5px,color:#2c0f52,stroke-dasharray: 4 4;
  classDef note fill:#fffbea,stroke:#b08900,stroke-width:1px,color:#3a2d00,stroke-dasharray: 3 3;
```
