# agrimgarg08/drishti architecture

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

- Interactive diagram: https://gitdiagram.com/agrimgarg08/drishti
- Repository: https://github.com/agrimgarg08/drishti

## Overview

1. **Overall shape**
   - DRISHTI is a Python-based monitoring platform with three main layers: a Streamlit dashboard, a FastAPI backend, and a Supabase-hosted PostgreSQL/auth layer.
   - The intended architecture is “UI → API/ML → database/auth,” but the README notes that the backend is not fully wired in yet, so the frontend currently bypasses parts of that path in places.

2. **Primary user-facing entrypoint**
   - `streamlit_app.py` is the top-level app entrypoint.
   - `frontend/app.py` contains the dashboard UI logic: charts, readings, alerts, simulation views, and issue workflows.
   - This is the operational interface users interact with directly.

3. **Backend service boundary**
   - `backend/main.py` is the FastAPI service boundary and likely exposes REST endpoints for sensors, readings, alerts, issues, prediction, and simulation.
   - `backend/models.py` defines the data model, while `backend/db.py` handles database connectivity/session setup.
   - `backend/auth.py` encapsulates authentication integration and protected access behavior.

4. **Machine learning subsystem**
   - `backend/ml.py` contains the anomaly detection and prediction logic.
   - The README identifies two distinct ML behaviors: an `IsolationForest`-based anomaly detector for abnormal water-quality patterns, and a lightweight regression-based risk/simulation layer for short-term projection and scenario comparison.
   - This ML layer sits between incoming readings and alert generation.

5. **Data and auth platform**
   - `supabase_client.py` indicates direct Supabase access from the application layer.
   - Supabase is the hosted data/auth boundary: PostgreSQL for persistent state and Supabase Auth for sign-in/sign-up and protected workflows.
   - This is a key architectural point because it explains how the app persists operational data and manages authenticated actions.

6. **Persistence and schema management**
   - `migrations/initial.sql` defines the baseline schema.
   - `scripts/init_db.py` and `scripts/apply_migrations.py` support local/bootstrap database setup.
   - `dev.db` suggests there is also a local development database artifact, likely for offline or simplified development.

7. **Data generation and test tooling**
   - `scripts/generate_data.py` seeds sample sensor/operational data.
   - `scripts/test_api.py` and `scripts/test_ml.py` exercise the backend endpoints and ML behavior separately.
   - These scripts indicate that API, database, and ML are treated as distinct testable subsystems.

8. **Operational workflow**
   - The application’s business flow is: ingest sensor or sample data, persist it, run anomaly/risk logic, surface alerts in the dashboard, and track follow-up issues.
   - Alerts and issues are not just outputs; they form the response-management loop that closes the monitor/detect/predict/respond cycle.

9. **Deployment and runtime**
   - `Procfile` suggests the repo is designed for platform-style deployment.
   - `.github/workflows/ci.yml` provides CI coverage, and `.devcontainer/devcontainer.json` supports a reproducible development environment.
   - `requirements.txt` shows the project is fully Python-managed rather than split across multiple runtime stacks.

10. **Important architectural boundary to capture**
   - There are effectively two data paths: a “preferred” backend/API path and a currently practical frontend-to-Supabase path.
   - For an architecture diagram, treat FastAPI, ML, and database as distinct backend services, but note that the Streamlit UI may directly consume Supabase data today because the backend is still partial.

Main entry points: [`backend/main.py`](https://github.com/agrimgarg08/drishti/blob/main/backend/main.py) (API service), [`frontend/app.py`](https://github.com/agrimgarg08/drishti/blob/main/frontend/app.py) (Dashboard UI), [`backend/db.py`](https://github.com/agrimgarg08/drishti/blob/main/backend/db.py) (DB layer), [`backend/ml.py`](https://github.com/agrimgarg08/drishti/blob/main/backend/ml.py) (ML engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI"]
  node_streamlit_app["Streamlit app<br/>entrypoint<br/>[streamlit_app.py]"]
  node_frontend_app["Dashboard UI<br/>[app.py]"]
end

subgraph group_backend["Backend"]
  node_backend_main["API service<br/>fastapi<br/>[main.py]"]
  node_backend_ml{{"ML engine<br/>anomaly/risk<br/>[ml.py]"}}
  node_backend_db[("DB layer<br/>persistence<br/>[db.py]")]
  node_backend_auth(("Auth layer<br/>[auth.py]"))
  node_backend_models["Data models<br/>schema<br/>[models.py]"]
end

subgraph group_data["Data"]
  node_supabase_client["Supabase client<br/>[supabase_client.py]"]
  node_initial_sql["Initial schema<br/>sql<br/>[initial.sql]"]
  node_dev_db[("Dev database<br/>local db<br/>[dev.db]")]
end

subgraph group_ops["Ops"]
  node_init_db["Init DB<br/>bootstrap<br/>[init_db.py]"]
  node_apply_migrations["Migrations<br/>bootstrap"]
  node_generate_data["Seed data<br/>fixture<br/>[generate_data.py]"]
  node_test_api["API tests<br/>test script<br/>[test_api.py]"]
  node_test_ml["ML tests<br/>test script<br/>[test_ml.py]"]
  node_procfile["Procfile<br/>deploy"]
  node_ci_workflow["CI workflow<br/>[ci.yml]"]
  node_devcontainer["Dev container<br/>dev env<br/>[devcontainer.json]"]
end

node_streamlit_app -->|"loads UI"| node_frontend_app
node_frontend_app -->|"reads/writes"| node_supabase_client
node_frontend_app -.->|"preferred API path"| node_backend_main
node_backend_main -->|"uses"| node_backend_models
node_backend_main -->|"persists via"| node_backend_db
node_backend_main -->|"protects with"| node_backend_auth
node_backend_main -->|"invokes"| node_backend_ml
node_backend_ml -->|"consumes"| node_backend_models
node_backend_db -->|"schema source"| node_initial_sql
node_backend_db -->|"local store"| node_dev_db
node_backend_auth -->|"integrates with"| node_supabase_client
node_supabase_client -.->|"backs data path"| node_dev_db
node_init_db -->|"bootstraps"| node_initial_sql
node_apply_migrations -->|"applies"| node_initial_sql
node_generate_data -->|"seeds"| node_dev_db
node_test_api -->|"tests"| node_backend_main
node_test_ml -->|"tests"| node_backend_ml
node_procfile -->|"runs"| node_backend_main
node_ci_workflow -->|"runs"| node_test_api
node_ci_workflow -->|"runs"| node_test_ml
node_devcontainer -.->|"supports"| node_init_db

click node_streamlit_app "https://github.com/agrimgarg08/drishti/blob/main/streamlit_app.py"
click node_frontend_app "https://github.com/agrimgarg08/drishti/blob/main/frontend/app.py"
click node_backend_main "https://github.com/agrimgarg08/drishti/blob/main/backend/main.py"
click node_backend_ml "https://github.com/agrimgarg08/drishti/blob/main/backend/ml.py"
click node_backend_db "https://github.com/agrimgarg08/drishti/blob/main/backend/db.py"
click node_backend_auth "https://github.com/agrimgarg08/drishti/blob/main/backend/auth.py"
click node_backend_models "https://github.com/agrimgarg08/drishti/blob/main/backend/models.py"
click node_supabase_client "https://github.com/agrimgarg08/drishti/blob/main/supabase_client.py"
click node_initial_sql "https://github.com/agrimgarg08/drishti/blob/main/migrations/initial.sql"
click node_dev_db "https://github.com/agrimgarg08/drishti/blob/main/dev.db"
click node_init_db "https://github.com/agrimgarg08/drishti/blob/main/scripts/init_db.py"
click node_apply_migrations "https://github.com/agrimgarg08/drishti/blob/main/scripts/apply_migrations.py"
click node_generate_data "https://github.com/agrimgarg08/drishti/blob/main/scripts/generate_data.py"
click node_test_api "https://github.com/agrimgarg08/drishti/blob/main/scripts/test_api.py"
click node_test_ml "https://github.com/agrimgarg08/drishti/blob/main/scripts/test_ml.py"
click node_procfile "https://github.com/agrimgarg08/drishti/tree/main/Procfile"
click node_ci_workflow "https://github.com/agrimgarg08/drishti/blob/main/.github/workflows/ci.yml"
click node_devcontainer "https://github.com/agrimgarg08/drishti/blob/main/.devcontainer/devcontainer.json"

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_streamlit_app,node_frontend_app toneBlue
class node_backend_main,node_backend_ml,node_backend_db,node_backend_auth,node_backend_models toneAmber
class node_supabase_client,node_initial_sql,node_dev_db toneMint
class node_init_db,node_apply_migrations,node_generate_data,node_test_api,node_test_ml,node_procfile,node_ci_workflow,node_devcontainer toneRose
```

## Components

### UI

User-facing dashboard and app entrypoints

- [Streamlit app](https://github.com/agrimgarg08/drishti/blob/main/streamlit_app.py): entrypoint · Top-level Streamlit entrypoint for the dashboard · `streamlit_app.py`
- [Dashboard UI](https://github.com/agrimgarg08/drishti/blob/main/frontend/app.py): ui · Main dashboard logic for charts, readings, alerts, simulation, and issues · `frontend/app.py`

### Backend

API, ML, auth, and persistence boundary

- [API service](https://github.com/agrimgarg08/drishti/blob/main/backend/main.py): fastapi · FastAPI boundary exposing backend workflows and endpoints · `backend/main.py`
- [ML engine](https://github.com/agrimgarg08/drishti/blob/main/backend/ml.py): anomaly/risk · Anomaly detection and short-term prediction/simulation logic · `backend/ml.py`
- [DB layer](https://github.com/agrimgarg08/drishti/blob/main/backend/db.py): persistence · Database connectivity and session setup · `backend/db.py`
- [Auth layer](https://github.com/agrimgarg08/drishti/blob/main/backend/auth.py): auth · Authentication integration and protected access behavior · `backend/auth.py`
- [Data models](https://github.com/agrimgarg08/drishti/blob/main/backend/models.py): schema · Shared application models and domain objects · `backend/models.py`

### Data

Schema, local database, and Supabase access

- [Supabase client](https://github.com/agrimgarg08/drishti/blob/main/supabase_client.py): client · Direct application access to Supabase services · `supabase_client.py`
- [Initial schema](https://github.com/agrimgarg08/drishti/blob/main/migrations/initial.sql): sql · Baseline database schema and tables · `migrations/initial.sql`
- [Dev database](https://github.com/agrimgarg08/drishti/blob/main/dev.db): local db · Local development database artifact · `dev.db`

### Ops

Deployment, CI, and bootstrap tooling

- [Init DB](https://github.com/agrimgarg08/drishti/blob/main/scripts/init_db.py): bootstrap · Local database initialization script · `scripts/init_db.py`
- [Migrations](https://github.com/agrimgarg08/drishti/blob/main/scripts/apply_migrations.py): bootstrap · Applies schema migrations to the database · `scripts/apply_migrations.py`
- [Seed data](https://github.com/agrimgarg08/drishti/blob/main/scripts/generate_data.py): fixture · Generates sample sensor and operational data · `scripts/generate_data.py`
- [API tests](https://github.com/agrimgarg08/drishti/blob/main/scripts/test_api.py): test script · Exercises backend endpoints and service flows · `scripts/test_api.py`
- [ML tests](https://github.com/agrimgarg08/drishti/blob/main/scripts/test_ml.py): test script · Exercises anomaly and prediction behavior · `scripts/test_ml.py`
- [Procfile](https://github.com/agrimgarg08/drishti/tree/main/Procfile): deploy · Process definition for platform deployment · `Procfile`
- [CI workflow](https://github.com/agrimgarg08/drishti/blob/main/.github/workflows/ci.yml): ci · Continuous integration pipeline · `.github/workflows/ci.yml`
- [Dev container](https://github.com/agrimgarg08/drishti/blob/main/.devcontainer/devcontainer.json): dev env · Reproducible development environment definition · `.devcontainer/devcontainer.json`

## Connections

- Streamlit app → Dashboard UI: loads UI · Top-level app launches the dashboard UI
- Dashboard UI → Supabase client: reads/writes · Frontend may directly access Supabase-backed data paths
- Dashboard UI → API service: preferred API path · Intended UI-to-backend flow for operational actions
- API service → Data models: uses · API layer depends on shared domain models
- API service → DB layer: persists via · API uses database connectivity/session management
- API service → Auth layer: protects with · API gates protected workflows through auth
- API service → ML engine: invokes · API delegates anomaly detection and prediction to ML layer
- ML engine → Data models: consumes · ML operates on shared reading and alert-shaped data
- DB layer → Initial schema: schema source · Database layer is backed by the base schema definition
- DB layer → Dev database: local store · Development runs can use a local database artifact
- Auth layer → Supabase client: integrates with · Authentication relies on Supabase services
- Supabase client → Dev database: backs data path · Application data path can terminate in local or hosted storage
- Init DB → Initial schema: bootstraps · Initialization script applies the base schema
- Migrations → Initial schema: applies · Migration script manages schema evolution from baseline SQL
- Seed data → Dev database: seeds · Sample data generation populates the development database
- API tests → API service: tests · API test script exercises backend endpoints
- ML tests → ML engine: tests · ML test script exercises anomaly and simulation behavior
- Procfile → API service: runs · Deployment process can start the backend service
- CI workflow → API tests: runs · CI validates backend behavior through API tests
- CI workflow → ML tests: runs · CI validates ML behavior through ML tests
- Dev container → Init DB: supports · Development container supports local setup workflows
