# prajwalmhetre/medilens-ai architecture

> Architecture diagram of the GitHub repository prajwalmhetre/medilens-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prajwalmhetre/medilens-ai
- Repository: https://github.com/prajwalmhetre/medilens-ai

## Overview

#### Purpose and entry points
MediLens AI is a full-stack healthcare demo for medicine scanning, medication tracking/reminders, profile-based safety guidance, and simulated AI-pharmacist chat. Flutter is the multi-platform client; FastAPI exposes the REST backend. Primary entry points are `lib/main.dart`, `lib/app/medilens_app.dart`, and `backend/main.py`.

#### Flutter composition and navigation
The application bootstrap installs app-wide composition, Material styling, and provider-backed state before presenting onboarding and the main tab shell. The shell hosts dashboard, scanning, reminders, chat, and profile presentation modules.
Paths: `lib/app/medilens_app.dart`, `lib/features/shell/presentation/main_shell.dart`, `lib/features/onboarding/presentation/splash_screen.dart`.

#### Global state and offline boundary
`AppStateProvider` is the client-side orchestration layer: it owns loaded/optimistic UI state and coordinates profile, medicines, reminders, and conversations. The README specifies offline-first fallback behavior, notably local simulated chat responses when API calls fail; feature screens should remain presentation-focused.
Paths: `lib/app/state/app_state_provider.dart`, `lib/shared/models/medicine.dart`, `lib/shared/models/reminder.dart`.

#### API integration boundary
Flutter feature/state code reaches the backend only through the HTTP service. Its base URL is runtime-configured through `API_BASE_URL`, allowing native development, web builds, and container deployments to target different API hosts.
Paths: `lib/core/network/api_service.dart`, `.env.example`, `pubspec.yaml`.

#### User-facing feature stages
Dashboard renders medication/adherence status; scan simulates medicine identification and allergy-conflict guidance; medicine details expose a selected medicine; reminders support creation and completion state; chat submits and displays medication guidance. These are separate feature presentation areas sharing state and model contracts.
Paths: `lib/features/dashboard/presentation/dashboard_tab.dart`, `lib/features/scan/presentation/scan_tab.dart`, `lib/features/reminders/presentation/reminders_tab.dart`.

#### FastAPI service and AI workflow
The FastAPI application owns `/api` endpoints for seeded user data, medicines, reminders, and chat. Chat is a deterministic safety-guidance pipeline: persist user text, classify intent, produce an allergy/safety/scheduling/general response, persist it, then return both messages. It is mock AI today; `AI_PROVIDER` and `OPENAI_API_KEY` are future integration seams, not evidence of an active external LLM dependency.
Paths: `backend/main.py`, `backend/schemas.py`, `backend/AI_IMPLEMENTATION.md`.

#### Persistence and deployment
SQLAlchemy models and database setup isolate persistence from HTTP handlers. SQLite is the default local store, seeded at backend startup; `DATABASE_URL` permits replacement with a production database. Docker Compose runs the static Flutter web frontend and FastAPI backend together; backend CORS is environment-configured.
Paths: `backend/database.py`, `backend/models.py`, `docker-compose.yml`.

#### Runtime surface
Flutter/Dart targets Android, iOS, web, Linux, macOS, and Windows through generated platform runners. The material deployment path is Flutter web in the root `Dockerfile`, with Python/FastAPI/Uvicorn in `backend/Dockerfile`; no authentication, real OCR, push notification, or production LLM service is currently implemented.
Paths: `Dockerfile`, `backend/Dockerfile`, `android/app/src/main/kotlin/com/prajwalmhetre/medilens_ai/medilens_ai/MainActivity.kt`.

Main entry points: [`lib/app/state/app_state_provider.dart`](https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/app/state/app_state_provider.dart) (App state provider), [`backend/main.py`](https://github.com/prajwalmhetre/medilens-ai/blob/main/backend/main.py) (FastAPI application), [`lib/app/medilens_app.dart`](https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/app/medilens_app.dart) (App composition), [`lib/features/shell/presentation/main_shell.dart`](https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/features/shell/presentation/main_shell.dart) (Main tab shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_flutter["Flutter client"]
  node_flutter_entry["Flutter entry<br/>Dart bootstrap<br/>[main.dart]"]
  node_app_composition["App composition<br/>Flutter app<br/>[medilens_app.dart]"]
  node_onboarding["Splash onboarding<br/>presentation<br/>[splash_screen.dart]"]
  node_main_shell["Main tab shell<br/>presentation<br/>[main_shell.dart]"]
  node_dashboard["Dashboard<br/>presentation<br/>[dashboard_tab.dart]"]
  node_scan["Medicine scan<br/>presentation<br/>[scan_tab.dart]"]
  node_reminders_ui["Reminders<br/>presentation<br/>[reminders_tab.dart]"]
  node_app_state{{"App state provider<br/>client orchestration"}}
  node_client_models["Medicine and reminder models<br/>shared contracts<br/>[medicine.dart]"]
  node_api_service["HTTP API service<br/>network boundary<br/>[api_service.dart]"]
end

subgraph group_backend["FastAPI backend"]
  node_api_app["FastAPI application<br/>REST API<br/>[main.py]"]
  node_api_schemas["API schemas<br/>request/response contracts<br/>[schemas.py]"]
  node_chat_pipeline{{"Safety chat pipeline<br/>deterministic mock AI<br/>[main.py]"}}
  node_persistence["SQLAlchemy persistence<br/>database layer<br/>[database.py]"]
  node_sqlite[("SQLite default store<br/>database<br/>[models.py]")]
end

subgraph group_deployment["Deployment"]
  node_web_container["Flutter web container<br/>Docker image"]
  node_api_container["FastAPI/Uvicorn container<br/>Docker image"]
  node_compose["Docker Compose<br/>deployment orchestration<br/>[docker-compose.yml]"]
end

node_flutter_entry -->|"starts"| node_app_composition
node_app_composition -->|"presents"| node_onboarding
node_app_composition -->|"presents"| node_main_shell
node_main_shell -->|"hosts"| node_dashboard
node_main_shell -->|"hosts"| node_scan
node_main_shell -->|"hosts"| node_reminders_ui
node_app_composition -->|"provides"| node_app_state
node_dashboard -->|"reads state"| node_app_state
node_scan -->|"reads and updates"| node_app_state
node_reminders_ui -->|"reads and updates"| node_app_state
node_app_state -->|"uses"| node_client_models
node_app_state -->|"calls"| node_api_service
node_api_service -->|"REST /api"| node_api_app
node_api_service -.->|"simulated chat fallback"| node_app_state
node_api_app -->|"validates with"| node_api_schemas
node_api_app -->|"chat requests"| node_chat_pipeline
node_api_app -->|"reads and writes"| node_persistence
node_chat_pipeline -->|"persists both messages"| node_persistence
node_persistence -->|"stores data"| node_sqlite
node_compose -->|"runs"| node_web_container
node_compose -->|"runs"| node_api_container
node_web_container -->|"serves client"| node_api_service
node_api_container -->|"hosts"| node_api_app

click node_flutter_entry "https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/main.dart"
click node_app_composition "https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/app/medilens_app.dart"
click node_onboarding "https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/features/onboarding/presentation/splash_screen.dart"
click node_main_shell "https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/features/shell/presentation/main_shell.dart"
click node_dashboard "https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/features/dashboard/presentation/dashboard_tab.dart"
click node_scan "https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/features/scan/presentation/scan_tab.dart"
click node_reminders_ui "https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/features/reminders/presentation/reminders_tab.dart"
click node_app_state "https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/app/state/app_state_provider.dart"
click node_client_models "https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/shared/models/medicine.dart"
click node_api_service "https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/core/network/api_service.dart"
click node_api_app "https://github.com/prajwalmhetre/medilens-ai/blob/main/backend/main.py"
click node_api_schemas "https://github.com/prajwalmhetre/medilens-ai/blob/main/backend/schemas.py"
click node_chat_pipeline "https://github.com/prajwalmhetre/medilens-ai/blob/main/backend/main.py"
click node_persistence "https://github.com/prajwalmhetre/medilens-ai/blob/main/backend/database.py"
click node_sqlite "https://github.com/prajwalmhetre/medilens-ai/blob/main/backend/models.py"
click node_web_container "https://github.com/prajwalmhetre/medilens-ai/blob/main/Dockerfile"
click node_api_container "https://github.com/prajwalmhetre/medilens-ai/blob/main/backend/Dockerfile"
click node_compose "https://github.com/prajwalmhetre/medilens-ai/blob/main/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flutter_entry,node_app_composition,node_onboarding,node_main_shell,node_dashboard,node_scan,node_reminders_ui,node_app_state,node_client_models,node_api_service toneBlue
class node_api_app,node_api_schemas,node_chat_pipeline,node_persistence,node_sqlite toneAmber
class node_web_container,node_api_container,node_compose toneMint
```

## Components

### Flutter client

Multi-platform presentation and client orchestration.

- [Flutter entry](https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/main.dart): Dart bootstrap · `lib/main.dart`
- [App composition](https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/app/medilens_app.dart): Flutter app · Installs styling and provider-backed application composition. · `lib/app/medilens_app.dart`
- [Splash onboarding](https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/features/onboarding/presentation/splash_screen.dart): presentation · `lib/features/onboarding/presentation/splash_screen.dart`
- [Main tab shell](https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/features/shell/presentation/main_shell.dart): presentation · Hosts the primary feature tabs. · `lib/features/shell/presentation/main_shell.dart`
- [Dashboard](https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/features/dashboard/presentation/dashboard_tab.dart): presentation · Shows medication and adherence status. · `lib/features/dashboard/presentation/dashboard_tab.dart`
- [Medicine scan](https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/features/scan/presentation/scan_tab.dart): presentation · Simulates identification and allergy-conflict guidance. · `lib/features/scan/presentation/scan_tab.dart`
- [Reminders](https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/features/reminders/presentation/reminders_tab.dart): presentation · Creates and completes reminder state. · `lib/features/reminders/presentation/reminders_tab.dart`
- [App state provider](https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/app/state/app_state_provider.dart): client orchestration · Coordinates profile, medicines, reminders, and conversations with optimistic state. · `lib/app/state/app_state_provider.dart`
- [Medicine and reminder models](https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/shared/models/medicine.dart): shared contracts · `lib/shared/models/medicine.dart`
- [HTTP API service](https://github.com/prajwalmhetre/medilens-ai/blob/main/lib/core/network/api_service.dart): network boundary · Uses runtime API_BASE_URL and enables local chat fallback on failures. · `lib/core/network/api_service.dart`

### FastAPI backend

REST API, deterministic chat workflow, and persistence.

- [FastAPI application](https://github.com/prajwalmhetre/medilens-ai/blob/main/backend/main.py): REST API · Serves seeded user data, medicines, reminders, and chat under /api. · `backend/main.py`
- [API schemas](https://github.com/prajwalmhetre/medilens-ai/blob/main/backend/schemas.py): request/response contracts · `backend/schemas.py`
- [Safety chat pipeline](https://github.com/prajwalmhetre/medilens-ai/blob/main/backend/main.py): deterministic mock AI · Persists input, classifies intent, produces guidance, and persists the reply. · `backend/main.py`
- [SQLAlchemy persistence](https://github.com/prajwalmhetre/medilens-ai/blob/main/backend/database.py): database layer · Separates database setup and models from HTTP handlers. · `backend/database.py`
- [SQLite default store](https://github.com/prajwalmhetre/medilens-ai/blob/main/backend/models.py): database · Seeded at backend startup; DATABASE_URL can replace it. · `backend/models.py`

### Deployment

Containerized web frontend and API runtime.

- [Flutter web container](https://github.com/prajwalmhetre/medilens-ai/blob/main/Dockerfile): Docker image · `Dockerfile`
- [FastAPI/Uvicorn container](https://github.com/prajwalmhetre/medilens-ai/blob/main/backend/Dockerfile): Docker image · `backend/Dockerfile`
- [Docker Compose](https://github.com/prajwalmhetre/medilens-ai/blob/main/docker-compose.yml): deployment orchestration · Runs the static web frontend and API together. · `docker-compose.yml`

## Connections

- Flutter entry → App composition: starts
- App composition → Splash onboarding: presents
- App composition → Main tab shell: presents
- Main tab shell → Dashboard: hosts
- Main tab shell → Medicine scan: hosts
- Main tab shell → Reminders: hosts
- App composition → App state provider: provides
- Dashboard → App state provider: reads state
- Medicine scan → App state provider: reads and updates
- Reminders → App state provider: reads and updates
- App state provider → Medicine and reminder models: uses
- App state provider → HTTP API service: calls
- HTTP API service → FastAPI application: REST /api
- HTTP API service → App state provider: simulated chat fallback
- FastAPI application → API schemas: validates with
- FastAPI application → Safety chat pipeline: chat requests
- FastAPI application → SQLAlchemy persistence: reads and writes
- Safety chat pipeline → SQLAlchemy persistence: persists both messages
- SQLAlchemy persistence → SQLite default store: stores data
- Docker Compose → Flutter web container: runs
- Docker Compose → FastAPI/Uvicorn container: runs
- Flutter web container → HTTP API service: serves client
- FastAPI/Uvicorn container → FastAPI application: hosts