# sudeepn1104/jalsetu-lite architecture

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

- Interactive diagram: https://gitdiagram.com/sudeepn1104/jalsetu-lite
- Repository: https://github.com/sudeepn1104/jalsetu-lite

## Overview

JalSetu Lite is a water-tanker marketplace connecting citizens, operators, drivers, and municipal rate benchmarks. The principal workflow is citizen search and order selection, operator dispatch, then driver delivery verification; cancellation and dispute handling are alternate lifecycle outcomes. Authentication, staff administration, account history, and public operator scorecards support that workflow. The backend excerpt shows the API and SQLite access but omits most endpoint implementations; lifecycle relationships therefore follow documented behavior, while unsupported internal call wiring is left unspecified.

Main entry points: [`frontend/citizen.html`](https://github.com/sudeepn1104/jalsetu-lite/blob/main/frontend/citizen.html) (Citizen portal), [`backend/jalsetu.db`](https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/jalsetu.db) (SQLite records), [`frontend/auth.js`](https://github.com/sudeepn1104/jalsetu-lite/blob/main/frontend/auth.js) (Sign-in and history), [`backend/main.py`](https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py) (Offer search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_market["Marketplace"]
  node_citizen_ui["Citizen portal<br/>[citizen.html]"]
  node_operator_ui["Operator dashboard<br/>[operator.html]"]
  node_search["Offer search<br/>[main.py]"]
  node_ratecard["Operator and rate data<br/>[operators.json]"]
  node_order["Order selection<br/>[main.py]"]
end

subgraph group_delivery["Delivery lifecycle"]
  node_driver_ui["Driver dashboard<br/>[driver.html]"]
  node_delivery_state["Dispatch and delivery<br/>[main.py]"]
  node_verification["OTP and meter check<br/>[main.py]"]
  node_cancellation["Pre-dispatch cancellation<br/>[main.py]"]
  node_dispute["Dispute lock<br/>[main.py]"]
end

subgraph group_identity["Identity and records"]
  node_auth_ui["Sign-in and history<br/>[auth.js]"]
  node_api["JalSetu API<br/>[main.py]"]
  node_database[("SQLite records<br/>[jalsetu.db]")]
  node_staff_admin["Staff administration<br/>[main.py]"]
end

subgraph group_trust["Transparency and payment"]
  node_scorecard["Operator scorecards<br/>[scores.html]"]
  node_upi_qr["Demo UPI QR<br/>[route.ts]"]
  node_backend_qr["UPI QR rendering<br/>[main.py]"]
end

node_citizen(("Citizen"))
node_operator(("Operator"))
node_driver(("Driver"))
node_admin(("Administrator"))

node_citizen -->|"uses"| node_citizen_ui
node_citizen_ui -->|"searches offers"| node_search
node_search -->|"reads operators"| node_ratecard
node_search -->|"returns offers"| node_citizen_ui
node_citizen_ui -->|"selects offer"| node_order
node_order -->|"records order"| node_database
node_operator -->|"uses"| node_operator_ui
node_operator_ui -->|"dispatches order"| node_delivery_state
node_driver -->|"uses"| node_driver_ui
node_driver_ui -->|"updates delivery"| node_delivery_state
node_delivery_state -->|"requests verification"| node_verification
node_verification -->|"records outcome"| node_database
node_verification -->|"locks on failure"| node_dispute
node_dispute -->|"records dispute"| node_database
node_citizen_ui -->|"cancels pre-dispatch"| node_cancellation
node_cancellation -->|"updates order history"| node_database
node_auth_ui -->|"authenticates"| node_api
node_api -->|"reads and writes"| node_database
node_auth_ui -->|"loads account history"| node_api
node_admin -->|"manages staff"| node_auth_ui
node_auth_ui -->|"creates or resets"| node_staff_admin
node_staff_admin -->|"stores accounts"| node_database
node_citizen -->|"compares operators"| node_scorecard
node_citizen_ui -.->|"requests demo QR"| node_upi_qr
node_citizen_ui -.->|"requests demo QR"| node_backend_qr

click node_citizen_ui "https://github.com/sudeepn1104/jalsetu-lite/blob/main/frontend/citizen.html"
click node_operator_ui "https://github.com/sudeepn1104/jalsetu-lite/blob/main/frontend/operator.html"
click node_search "https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py"
click node_ratecard "https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/seed/operators.json"
click node_order "https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py"
click node_driver_ui "https://github.com/sudeepn1104/jalsetu-lite/blob/main/frontend/driver.html"
click node_delivery_state "https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py"
click node_verification "https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py"
click node_cancellation "https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py"
click node_dispute "https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py"
click node_auth_ui "https://github.com/sudeepn1104/jalsetu-lite/blob/main/frontend/auth.js"
click node_api "https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py"
click node_database "https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/jalsetu.db"
click node_staff_admin "https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py"
click node_scorecard "https://github.com/sudeepn1104/jalsetu-lite/blob/main/frontend/score/public/scores.html"
click node_upi_qr "https://github.com/sudeepn1104/jalsetu-lite/blob/main/frontend/score/app/api/upi-qr/route.ts"
click node_backend_qr "https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py"

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_citizen_ui,node_operator_ui,node_search,node_ratecard,node_order toneBlue
class node_driver_ui,node_delivery_state,node_verification,node_cancellation,node_dispute toneAmber
class node_auth_ui,node_api,node_database,node_staff_admin toneMint
class node_scorecard,node_upi_qr,node_backend_qr toneRose
class node_citizen,node_operator,node_driver,node_admin toneIndigo
```

## Components

### Marketplace

- [Citizen portal](https://github.com/sudeepn1104/jalsetu-lite/blob/main/frontend/citizen.html): `frontend/citizen.html`
- [Operator dashboard](https://github.com/sudeepn1104/jalsetu-lite/blob/main/frontend/operator.html): `frontend/operator.html`
- [Offer search](https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py): `backend/main.py`
- [Operator and rate data](https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/seed/operators.json): `backend/seed/operators.json`
- [Order selection](https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py): `backend/main.py`

### Delivery lifecycle

- [Driver dashboard](https://github.com/sudeepn1104/jalsetu-lite/blob/main/frontend/driver.html): `frontend/driver.html`
- [Dispatch and delivery](https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py): `backend/main.py`
- [OTP and meter check](https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py): `backend/main.py`
- [Pre-dispatch cancellation](https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py): `backend/main.py`
- [Dispute lock](https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py): `backend/main.py`

### Identity and records

- [Sign-in and history](https://github.com/sudeepn1104/jalsetu-lite/blob/main/frontend/auth.js): `frontend/auth.js`
- [JalSetu API](https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py): `backend/main.py`
- [SQLite records](https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/jalsetu.db): `backend/jalsetu.db`
- [Staff administration](https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py): `backend/main.py`

### Transparency and payment

- [Operator scorecards](https://github.com/sudeepn1104/jalsetu-lite/blob/main/frontend/score/public/scores.html): `frontend/score/public/scores.html`
- [Demo UPI QR](https://github.com/sudeepn1104/jalsetu-lite/blob/main/frontend/score/app/api/upi-qr/route.ts): `frontend/score/app/api/upi-qr/route.ts`
- [UPI QR rendering](https://github.com/sudeepn1104/jalsetu-lite/blob/main/backend/main.py): `backend/main.py`

### Other components

- **Citizen**
- **Operator**
- **Driver**
- **Administrator**

## Connections

- Citizen → Citizen portal: uses
- Citizen portal → Offer search: searches offers
- Offer search → Operator and rate data: reads operators
- Offer search → Citizen portal: returns offers
- Citizen portal → Order selection: selects offer
- Order selection → SQLite records: records order
- Operator → Operator dashboard: uses
- Operator dashboard → Dispatch and delivery: dispatches order
- Driver → Driver dashboard: uses
- Driver dashboard → Dispatch and delivery: updates delivery
- Dispatch and delivery → OTP and meter check: requests verification
- OTP and meter check → SQLite records: records outcome
- OTP and meter check → Dispute lock: locks on failure
- Dispute lock → SQLite records: records dispute
- Citizen portal → Pre-dispatch cancellation: cancels pre-dispatch
- Pre-dispatch cancellation → SQLite records: updates order history
- Sign-in and history → JalSetu API: authenticates
- JalSetu API → SQLite records: reads and writes
- Sign-in and history → JalSetu API: loads account history
- Administrator → Sign-in and history: manages staff
- Sign-in and history → Staff administration: creates or resets
- Staff administration → SQLite records: stores accounts
- Citizen → Operator scorecards: compares operators
- Citizen portal → Demo UPI QR: requests demo QR
- Citizen portal → UPI QR rendering: requests demo QR