# asadityasharma190907-afk/samarth-coop architecture

> Architecture diagram of the GitHub repository asadityasharma190907-afk/samarth-coop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asadityasharma190907-afk/samarth-coop
- Repository: https://github.com/asadityasharma190907-afk/samarth-coop

## Overview

Samarth is a cooperative gig-services platform: citizens request work, the system ranks workers with an income-fairness-weighted dispatch score, and workers receive offers and manage jobs. Its broader product includes worker registration and verification, booking and pricing, federation and enterprise workflows, wallet and welfare features, notifications, and analytics/admin views. The graph reflects documented and indexed relationships; several feature routes and pages were not sampled, so their internal connections are left unverified rather than inferred.

Main entry points: [`backend/app/main.py`](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/main.py) (FastAPI entry), [`backend/app/routers/bookings.py`](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/routers/bookings.py) (Booking routes), [`frontend/src/App.tsx`](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/frontend/src/App.tsx) (Client routes), [`backend/app/routers/auth.py`](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/routers/auth.py) (Auth routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Client routes<br/>[App.tsx]"]
  node_booking_ui["Booking views"]
  node_worker_ui["Worker views"]
  node_cooperative_ui["Cooperative views"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["Platform API"]
  node_api_entry["FastAPI entry<br/>[main.py]"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_booking_routes["Booking routes<br/>[bookings.py]"]
  node_worker_routes["Worker routes<br/>[workers.py]"]
  node_feature_routes["Feature routes"]
end

subgraph group_domain["Work and fairness"]
  node_auth_service["Identity service<br/>[auth.py]"]
  node_booking_service["Booking service<br/>[booking.py]"]
  node_dispatch["Fair dispatch<br/>[dispatch.py]"]
  node_adaptive_dispatch["Adaptive ranking<br/>[dispatch_v2.py]"]
  node_pricing["Fair-surge pricing<br/>[pricing.py]"]
  node_federation_service["Federation service<br/>[federation.py]"]
end

subgraph group_operations["Cooperative services"]
  node_database["Database session<br/>[database.py]"]
  node_identity_data[("Users and profiles<br/>[user.py]")]
  node_booking_data[("Bookings and offers<br/>[booking.py]")]
  node_worker_data[("Worker profiles<br/>[worker_profile.py]")]
  node_analytics["Analytics service<br/>[analytics.py]"]
  node_admin["Admin service<br/>[admin.py]"]
end

node_citizen(("Citizen"))
node_worker(("Worker"))

node_citizen -->|"uses"| node_app
node_worker -->|"uses"| node_app
node_app -->|"routes to"| node_booking_ui
node_app -->|"routes to"| node_worker_ui
node_app -->|"routes to"| node_cooperative_ui
node_api_client -->|"sends requests"| node_api_entry
node_api_entry -->|"registers"| node_auth_routes
node_api_entry -->|"registers"| node_booking_routes
node_api_entry -->|"registers"| node_worker_routes
node_api_entry -->|"registers"| node_feature_routes
node_auth_routes -->|"calls"| node_auth_service
node_booking_routes -->|"calls"| node_booking_service
node_booking_routes -->|"calls"| node_dispatch
node_booking_routes -->|"calls"| node_pricing
node_worker_routes -->|"calls"| node_adaptive_dispatch
node_booking_service -.->|"uses"| node_booking_data
node_dispatch -.->|"reads earnings"| node_booking_data
node_adaptive_dispatch -.->|"ranks workers"| node_worker_data
node_auth_service -->|"creates users"| node_identity_data
node_auth_routes -->|"gets session"| node_database
node_booking_routes -->|"gets session"| node_database
node_worker_routes -->|"gets session"| node_database
node_federation_service -.->|"uses"| node_booking_data
node_feature_routes -.->|"dispatches to"| node_analytics
node_feature_routes -.->|"dispatches to"| node_admin

click node_app "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/frontend/src/App.tsx"
click node_booking_ui "https://github.com/asadityasharma190907-afk/samarth-coop/tree/master/frontend/src/pages"
click node_worker_ui "https://github.com/asadityasharma190907-afk/samarth-coop/tree/master/frontend/src/pages"
click node_cooperative_ui "https://github.com/asadityasharma190907-afk/samarth-coop/tree/master/frontend/src/pages"
click node_api_client "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/frontend/src/lib/api.ts"
click node_api_entry "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/main.py"
click node_auth_routes "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/routers/auth.py"
click node_booking_routes "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/routers/bookings.py"
click node_worker_routes "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/routers/workers.py"
click node_feature_routes "https://github.com/asadityasharma190907-afk/samarth-coop/tree/master/backend/app/routers"
click node_auth_service "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/services/auth.py"
click node_booking_service "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/services/booking.py"
click node_dispatch "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/services/dispatch.py"
click node_adaptive_dispatch "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/services/dispatch_v2.py"
click node_pricing "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/services/pricing.py"
click node_federation_service "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/services/federation.py"
click node_database "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/database.py"
click node_identity_data "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/models/user.py"
click node_booking_data "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/models/booking.py"
click node_worker_data "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/models/worker_profile.py"
click node_analytics "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/services/analytics.py"
click node_admin "https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/services/admin.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_app,node_booking_ui,node_worker_ui,node_cooperative_ui,node_api_client toneBlue
class node_api_entry,node_auth_routes,node_booking_routes,node_worker_routes,node_feature_routes toneAmber
class node_auth_service,node_booking_service,node_dispatch,node_adaptive_dispatch,node_pricing,node_federation_service toneMint
class node_database,node_identity_data,node_booking_data,node_worker_data,node_analytics,node_admin,node_worker toneRose
class node_citizen toneIndigo
```

## Components

### Web client

- [Client routes](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Booking views](https://github.com/asadityasharma190907-afk/samarth-coop/tree/master/frontend/src/pages): `frontend/src/pages`
- [Worker views](https://github.com/asadityasharma190907-afk/samarth-coop/tree/master/frontend/src/pages): `frontend/src/pages`
- [Cooperative views](https://github.com/asadityasharma190907-afk/samarth-coop/tree/master/frontend/src/pages): `frontend/src/pages`
- [API client](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Platform API

- [FastAPI entry](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/main.py): `backend/app/main.py`
- [Auth routes](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Booking routes](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/routers/bookings.py): `backend/app/routers/bookings.py`
- [Worker routes](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/routers/workers.py): `backend/app/routers/workers.py`
- [Feature routes](https://github.com/asadityasharma190907-afk/samarth-coop/tree/master/backend/app/routers): `backend/app/routers`

### Work and fairness

- [Identity service](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/services/auth.py): `backend/app/services/auth.py`
- [Booking service](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/services/booking.py): `backend/app/services/booking.py`
- [Fair dispatch](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/services/dispatch.py): `backend/app/services/dispatch.py`
- [Adaptive ranking](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/services/dispatch_v2.py): `backend/app/services/dispatch_v2.py`
- [Fair-surge pricing](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/services/pricing.py): `backend/app/services/pricing.py`
- [Federation service](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/services/federation.py): `backend/app/services/federation.py`

### Cooperative services

- [Database session](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/database.py): `backend/app/database.py`
- [Users and profiles](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/models/user.py): `backend/app/models/user.py`
- [Bookings and offers](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/models/booking.py): `backend/app/models/booking.py`
- [Worker profiles](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/models/worker_profile.py): `backend/app/models/worker_profile.py`
- [Analytics service](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/services/analytics.py): `backend/app/services/analytics.py`
- [Admin service](https://github.com/asadityasharma190907-afk/samarth-coop/blob/master/backend/app/services/admin.py): `backend/app/services/admin.py`

### Other components

- **Citizen**
- **Worker**

## Connections

- Citizen → Client routes: uses (evidence: `README.md`)
- Worker → Client routes: uses (evidence: `README.md`)
- Client routes → Booking views: routes to (evidence: `frontend/src/App.tsx`)
- Client routes → Worker views: routes to (evidence: `frontend/src/App.tsx`)
- Client routes → Cooperative views: routes to (evidence: `frontend/src/App.tsx`)
- API client → FastAPI entry: sends requests (evidence: `frontend/src/lib/api.ts`)
- FastAPI entry → Auth routes: registers (evidence: `backend/app/main.py`)
- FastAPI entry → Booking routes: registers (evidence: `backend/app/main.py`)
- FastAPI entry → Worker routes: registers (evidence: `backend/app/main.py`)
- FastAPI entry → Feature routes: registers (evidence: `backend/app/main.py`)
- Auth routes → Identity service: calls (evidence: `backend/app/routers/auth.py`)
- Booking routes → Booking service: calls (evidence: `backend/app/routers/bookings.py`)
- Booking routes → Fair dispatch: calls (evidence: `backend/app/routers/bookings.py`)
- Booking routes → Fair-surge pricing: calls (evidence: `backend/app/routers/bookings.py`)
- Worker routes → Adaptive ranking: calls (evidence: `backend/app/routers/workers.py`)
- Booking service → Bookings and offers: uses
- Fair dispatch → Bookings and offers: reads earnings
- Adaptive ranking → Worker profiles: ranks workers
- Identity service → Users and profiles: creates users (evidence: `backend/app/services/auth.py`)
- Auth routes → Database session: gets session (evidence: `backend/app/routers/auth.py`)
- Booking routes → Database session: gets session (evidence: `backend/app/routers/bookings.py`)
- Worker routes → Database session: gets session (evidence: `backend/app/routers/workers.py`)
- Federation service → Bookings and offers: uses
- Feature routes → Analytics service: dispatches to (evidence: `backend/app/routers/analytics.py`)
- Feature routes → Admin service: dispatches to (evidence: `backend/app/routers/admin.py`)
