How arman-rsheik/oralcare_ai works
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