# surya-4034/kaam architecture

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

- Interactive diagram: https://gitdiagram.com/surya-4034/kaam
- Repository: https://github.com/surya-4034/kaam

## Overview

Kaam is a multi-portal home-services marketplace: clients discover providers and book work, partners onboard and respond to job requests, and administrators oversee the platform. The backend exposes REST APIs for identity, workers, jobs, dues, administration, maps, and proximity search. The README documents search ranking, request status notifications, and dual MongoDB/SQLite persistence; unsampled implementations are represented only where paths are supported. The graph shows documented HTTP/API and explicitly evidenced internal calls; it does not assume unshown client request wiring.

Main entry points: [`server/src/app.js`](https://github.com/surya-4034/kaam/blob/main/server/src/app.js) (REST API server), [`worker-app/src/App.jsx`](https://github.com/surya-4034/kaam/blob/main/worker-app/src/App.jsx) (Partner portal), [`client-app/src/App.jsx`](https://github.com/surya-4034/kaam/blob/main/client-app/src/App.jsx) (Client portal), [`server/src/controllers/authController.js`](https://github.com/surya-4034/kaam/blob/main/server/src/controllers/authController.js) (Identity and signup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portals["Marketplace portals"]
  node_client["Client portal<br/>[App.jsx]"]
  node_client_auth["Client authentication<br/>[AuthPage.jsx]"]
  node_checkout["Booking checkout<br/>[CheckoutPage.jsx]"]
  node_address_slot["Address and slots"]
  node_client_onboarding["Client onboarding"]
  node_worker_profile["Provider service detail"]
  node_client_admin["Client admin view<br/>[AdminDashboard.jsx]"]
  node_worker["Partner portal<br/>[App.jsx]"]
  node_worker_auth["Partner authentication<br/>[AuthPage.jsx]"]
  node_worker_landing["Partner workspace"]
  node_worker_onboarding["Partner onboarding"]
  node_categories["Service categories"]
  node_worker_admin["Partner admin view<br/>[AdminDashboard.jsx]"]
  node_admin["Master admin portal<br/>[App.jsx]"]
end

subgraph group_api["Backend API"]
  node_api_server["REST API server<br/>[app.js]"]
  node_auth_routes["Identity routes<br/>[authRoutes.js]"]
  node_auth_controller["Identity and signup<br/>[authController.js]"]
  node_worker_routes["Partner routes<br/>[workerRoutes.js]"]
  node_worker_controller["Partner profiles"]
  node_job_routes["Job routes<br/>[jobRoutes.js]"]
  node_job_controller["Job lifecycle<br/>[jobController.js]"]
  node_dues_routes["Dues routes<br/>[duesRoutes.js]"]
  node_dues_controller["Commission dues<br/>[duesController.js]"]
  node_admin_routes["Admin routes<br/>[adminRoutes.js]"]
  node_admin_controller["Admin operations<br/>[adminController.js]"]
end

subgraph group_discovery["Discovery and location"]
  node_maps_routes["Address lookup<br/>[mapsRoutes.js]"]
  node_spatial_routes["Proximity endpoints<br/>[spatialRoutes.js]"]
  node_spatial_service["Location operations"]
  node_redis_spatial["Spatial search cache"]
  node_location_client["Client geolocation<br/>[locationService.js]"]
  node_partner_location["Partner location client"]
end

subgraph group_persistence["Persistence and messaging"]
  node_sqlite[("SQLite fallback<br/>[database.js]")]
  node_mongo[("MongoDB connections<br/>[mongoose.js]")]
  node_partner_model["Partner model<br/>[PartnerModel.js]"]
end

node_client -->|"renders"| node_client_auth
node_client -->|"renders"| node_client_onboarding
node_client -->|"renders"| node_worker_profile
node_client -->|"calls"| node_location_client
node_checkout -->|"uses"| node_address_slot
node_worker -->|"renders"| node_worker_auth
node_worker -->|"renders"| node_worker_landing
node_worker -->|"renders"| node_worker_onboarding
node_worker -->|"uses"| node_categories
node_worker_onboarding -->|"uses"| node_categories
node_worker -->|"calls"| node_partner_location
node_client -->|"HTTP REST"| node_api_server
node_worker -->|"HTTP REST"| node_api_server
node_admin -->|"HTTP REST"| node_api_server
node_api_server -->|"mounts"| node_auth_routes
node_api_server -->|"mounts"| node_worker_routes
node_api_server -->|"mounts"| node_job_routes
node_api_server -->|"mounts"| node_dues_routes
node_api_server -->|"mounts"| node_admin_routes
node_api_server -->|"mounts"| node_maps_routes
node_api_server -->|"mounts"| node_spatial_routes
node_auth_routes -->|"routes to"| node_auth_controller
node_worker_routes -->|"routes to"| node_worker_controller
node_job_routes -->|"routes to"| node_job_controller
node_dues_routes -->|"routes to"| node_dues_controller
node_admin_routes -->|"routes to"| node_admin_controller
node_worker_controller -->|"filters distance"| node_spatial_service
node_worker_controller -->|"searches nearby"| node_redis_spatial
node_spatial_routes -->|"calls"| node_spatial_service
node_spatial_service -->|"uses"| node_redis_spatial
node_spatial_routes -->|"queries"| node_mongo
node_spatial_routes -->|"fallback reads"| node_sqlite
node_auth_controller -->|"writes accounts"| node_sqlite
node_auth_controller -->|"generates partner ID"| node_partner_model
node_auth_controller -->|"checks connection"| node_mongo
node_partner_model -->|"uses connection"| node_mongo
node_sqlite -.->|"dual-store support"| node_mongo
node_api_server -.->|"Google Places fallback"| node_maps_routes
node_api_server -.->|"admin capabilities"| node_worker_admin
node_api_server -.->|"admin capabilities"| node_client_admin

click node_client "https://github.com/surya-4034/kaam/blob/main/client-app/src/App.jsx"
click node_client_auth "https://github.com/surya-4034/kaam/blob/main/client-app/src/components/auth/AuthPage.jsx"
click node_checkout "https://github.com/surya-4034/kaam/blob/main/client-app/src/components/checkout/CheckoutPage.jsx"
click node_address_slot "https://github.com/surya-4034/kaam/blob/main/client-app/src/components/checkout/AddressAndSlotWorkflow.jsx"
click node_client_onboarding "https://github.com/surya-4034/kaam/blob/main/client-app/src/components/onboarding/ClientOnboardingWizard.jsx"
click node_worker_profile "https://github.com/surya-4034/kaam/blob/main/client-app/src/components/profile/WorkerProfileDetail.jsx"
click node_client_admin "https://github.com/surya-4034/kaam/blob/main/client-app/src/components/admin/AdminDashboard.jsx"
click node_worker "https://github.com/surya-4034/kaam/blob/main/worker-app/src/App.jsx"
click node_worker_auth "https://github.com/surya-4034/kaam/blob/main/worker-app/src/components/auth/AuthPage.jsx"
click node_worker_landing "https://github.com/surya-4034/kaam/blob/main/worker-app/src/components/landing/WorkerLandingPage.jsx"
click node_worker_onboarding "https://github.com/surya-4034/kaam/blob/main/worker-app/src/components/onboarding/WorkerOnboardingWizard.jsx"
click node_categories "https://github.com/surya-4034/kaam/blob/main/worker-app/src/data/serviceCategories.js"
click node_worker_admin "https://github.com/surya-4034/kaam/blob/main/worker-app/src/components/admin/AdminDashboard.jsx"
click node_admin "https://github.com/surya-4034/kaam/blob/main/admin-app/src/App.jsx"
click node_api_server "https://github.com/surya-4034/kaam/blob/main/server/src/app.js"
click node_auth_routes "https://github.com/surya-4034/kaam/blob/main/server/src/routes/authRoutes.js"
click node_auth_controller "https://github.com/surya-4034/kaam/blob/main/server/src/controllers/authController.js"
click node_worker_routes "https://github.com/surya-4034/kaam/blob/main/server/src/routes/workerRoutes.js"
click node_worker_controller "https://github.com/surya-4034/kaam/blob/main/server/src/controllers/workerController.js"
click node_job_routes "https://github.com/surya-4034/kaam/blob/main/server/src/routes/jobRoutes.js"
click node_job_controller "https://github.com/surya-4034/kaam/blob/main/server/src/controllers/jobController.js"
click node_dues_routes "https://github.com/surya-4034/kaam/blob/main/server/src/routes/duesRoutes.js"
click node_dues_controller "https://github.com/surya-4034/kaam/blob/main/server/src/controllers/duesController.js"
click node_admin_routes "https://github.com/surya-4034/kaam/blob/main/server/src/routes/adminRoutes.js"
click node_admin_controller "https://github.com/surya-4034/kaam/blob/main/server/src/controllers/adminController.js"
click node_maps_routes "https://github.com/surya-4034/kaam/blob/main/server/src/routes/mapsRoutes.js"
click node_spatial_routes "https://github.com/surya-4034/kaam/blob/main/server/src/routes/spatialRoutes.js"
click node_spatial_service "https://github.com/surya-4034/kaam/blob/main/server/src/services/spatialLocationService.js"
click node_redis_spatial "https://github.com/surya-4034/kaam/blob/main/server/src/services/redisSpatialService.js"
click node_location_client "https://github.com/surya-4034/kaam/blob/main/client-app/src/services/locationService.js"
click node_partner_location "https://github.com/surya-4034/kaam/blob/main/worker-app/src/services/partnerLocationService.js"
click node_sqlite "https://github.com/surya-4034/kaam/blob/main/server/src/config/database.js"
click node_mongo "https://github.com/surya-4034/kaam/blob/main/server/src/config/mongoose.js"
click node_partner_model "https://github.com/surya-4034/kaam/blob/main/server/src/models/PartnerModel.js"

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_client,node_client_auth,node_checkout,node_address_slot,node_client_onboarding,node_worker_profile,node_client_admin,node_worker,node_worker_auth,node_worker_landing,node_worker_onboarding,node_categories,node_worker_admin,node_admin toneBlue
class node_api_server,node_auth_routes,node_auth_controller,node_worker_routes,node_worker_controller,node_job_routes,node_job_controller,node_dues_routes,node_dues_controller,node_admin_routes,node_admin_controller toneAmber
class node_maps_routes,node_spatial_routes,node_spatial_service,node_redis_spatial,node_location_client,node_partner_location toneMint
class node_sqlite,node_mongo,node_partner_model toneRose
```

## Components

### Marketplace portals

- [Client portal](https://github.com/surya-4034/kaam/blob/main/client-app/src/App.jsx): `client-app/src/App.jsx`
- [Client authentication](https://github.com/surya-4034/kaam/blob/main/client-app/src/components/auth/AuthPage.jsx): `client-app/src/components/auth/AuthPage.jsx`
- [Booking checkout](https://github.com/surya-4034/kaam/blob/main/client-app/src/components/checkout/CheckoutPage.jsx): `client-app/src/components/checkout/CheckoutPage.jsx`
- [Address and slots](https://github.com/surya-4034/kaam/blob/main/client-app/src/components/checkout/AddressAndSlotWorkflow.jsx): `client-app/src/components/checkout/AddressAndSlotWorkflow.jsx`
- [Client onboarding](https://github.com/surya-4034/kaam/blob/main/client-app/src/components/onboarding/ClientOnboardingWizard.jsx): `client-app/src/components/onboarding/ClientOnboardingWizard.jsx`
- [Provider service detail](https://github.com/surya-4034/kaam/blob/main/client-app/src/components/profile/WorkerProfileDetail.jsx): `client-app/src/components/profile/WorkerProfileDetail.jsx`
- [Client admin view](https://github.com/surya-4034/kaam/blob/main/client-app/src/components/admin/AdminDashboard.jsx): `client-app/src/components/admin/AdminDashboard.jsx`
- [Partner portal](https://github.com/surya-4034/kaam/blob/main/worker-app/src/App.jsx): `worker-app/src/App.jsx`
- [Partner authentication](https://github.com/surya-4034/kaam/blob/main/worker-app/src/components/auth/AuthPage.jsx): `worker-app/src/components/auth/AuthPage.jsx`
- [Partner workspace](https://github.com/surya-4034/kaam/blob/main/worker-app/src/components/landing/WorkerLandingPage.jsx): `worker-app/src/components/landing/WorkerLandingPage.jsx`
- [Partner onboarding](https://github.com/surya-4034/kaam/blob/main/worker-app/src/components/onboarding/WorkerOnboardingWizard.jsx): `worker-app/src/components/onboarding/WorkerOnboardingWizard.jsx`
- [Service categories](https://github.com/surya-4034/kaam/blob/main/worker-app/src/data/serviceCategories.js): `worker-app/src/data/serviceCategories.js`
- [Partner admin view](https://github.com/surya-4034/kaam/blob/main/worker-app/src/components/admin/AdminDashboard.jsx): `worker-app/src/components/admin/AdminDashboard.jsx`
- [Master admin portal](https://github.com/surya-4034/kaam/blob/main/admin-app/src/App.jsx): `admin-app/src/App.jsx`

### Backend API

- [REST API server](https://github.com/surya-4034/kaam/blob/main/server/src/app.js): `server/src/app.js`
- [Identity routes](https://github.com/surya-4034/kaam/blob/main/server/src/routes/authRoutes.js): `server/src/routes/authRoutes.js`
- [Identity and signup](https://github.com/surya-4034/kaam/blob/main/server/src/controllers/authController.js): `server/src/controllers/authController.js`
- [Partner routes](https://github.com/surya-4034/kaam/blob/main/server/src/routes/workerRoutes.js): `server/src/routes/workerRoutes.js`
- [Partner profiles](https://github.com/surya-4034/kaam/blob/main/server/src/controllers/workerController.js): `server/src/controllers/workerController.js`
- [Job routes](https://github.com/surya-4034/kaam/blob/main/server/src/routes/jobRoutes.js): `server/src/routes/jobRoutes.js`
- [Job lifecycle](https://github.com/surya-4034/kaam/blob/main/server/src/controllers/jobController.js): `server/src/controllers/jobController.js`
- [Dues routes](https://github.com/surya-4034/kaam/blob/main/server/src/routes/duesRoutes.js): `server/src/routes/duesRoutes.js`
- [Commission dues](https://github.com/surya-4034/kaam/blob/main/server/src/controllers/duesController.js): `server/src/controllers/duesController.js`
- [Admin routes](https://github.com/surya-4034/kaam/blob/main/server/src/routes/adminRoutes.js): `server/src/routes/adminRoutes.js`
- [Admin operations](https://github.com/surya-4034/kaam/blob/main/server/src/controllers/adminController.js): `server/src/controllers/adminController.js`

### Discovery and location

- [Address lookup](https://github.com/surya-4034/kaam/blob/main/server/src/routes/mapsRoutes.js): `server/src/routes/mapsRoutes.js`
- [Proximity endpoints](https://github.com/surya-4034/kaam/blob/main/server/src/routes/spatialRoutes.js): `server/src/routes/spatialRoutes.js`
- [Location operations](https://github.com/surya-4034/kaam/blob/main/server/src/services/spatialLocationService.js): `server/src/services/spatialLocationService.js`
- [Spatial search cache](https://github.com/surya-4034/kaam/blob/main/server/src/services/redisSpatialService.js): `server/src/services/redisSpatialService.js`
- [Client geolocation](https://github.com/surya-4034/kaam/blob/main/client-app/src/services/locationService.js): `client-app/src/services/locationService.js`
- [Partner location client](https://github.com/surya-4034/kaam/blob/main/worker-app/src/services/partnerLocationService.js): `worker-app/src/services/partnerLocationService.js`

### Persistence and messaging

- [SQLite fallback](https://github.com/surya-4034/kaam/blob/main/server/src/config/database.js): `server/src/config/database.js`
- [MongoDB connections](https://github.com/surya-4034/kaam/blob/main/server/src/config/mongoose.js): `server/src/config/mongoose.js`
- [Partner model](https://github.com/surya-4034/kaam/blob/main/server/src/models/PartnerModel.js): `server/src/models/PartnerModel.js`

## Connections

- Client portal → Client authentication: renders (evidence: `client-app/src/App.jsx`)
- Client portal → Client onboarding: renders (evidence: `client-app/src/App.jsx`)
- Client portal → Provider service detail: renders (evidence: `client-app/src/App.jsx`)
- Client portal → Client geolocation: calls (evidence: `client-app/src/App.jsx`)
- Booking checkout → Address and slots: uses (evidence: `client-app/src/components/checkout/CheckoutPage.jsx`)
- Partner portal → Partner authentication: renders (evidence: `worker-app/src/App.jsx`)
- Partner portal → Partner workspace: renders (evidence: `worker-app/src/App.jsx`)
- Partner portal → Partner onboarding: renders (evidence: `worker-app/src/App.jsx`)
- Partner portal → Service categories: uses (evidence: `worker-app/src/App.jsx`)
- Partner onboarding → Service categories: uses (evidence: `worker-app/src/components/onboarding/WorkerOnboardingWizard.jsx`)
- Partner portal → Partner location client: calls (evidence: `worker-app/src/App.jsx`)
- Client portal → REST API server: HTTP REST (evidence: `README.md`)
- Partner portal → REST API server: HTTP REST (evidence: `README.md`)
- Master admin portal → REST API server: HTTP REST (evidence: `README.md`)
- REST API server → Identity routes: mounts (evidence: `server/src/app.js`)
- REST API server → Partner routes: mounts (evidence: `server/src/app.js`)
- REST API server → Job routes: mounts (evidence: `server/src/app.js`)
- REST API server → Dues routes: mounts (evidence: `server/src/app.js`)
- REST API server → Admin routes: mounts (evidence: `server/src/app.js`)
- REST API server → Address lookup: mounts (evidence: `server/src/app.js`)
- REST API server → Proximity endpoints: mounts (evidence: `server/src/app.js`)
- Identity routes → Identity and signup: routes to (evidence: `server/src/routes/authRoutes.js`)
- Partner routes → Partner profiles: routes to (evidence: `server/src/routes/workerRoutes.js`)
- Job routes → Job lifecycle: routes to (evidence: `server/src/routes/jobRoutes.js`)
- Dues routes → Commission dues: routes to (evidence: `server/src/routes/duesRoutes.js`)
- Admin routes → Admin operations: routes to (evidence: `server/src/routes/adminRoutes.js`)
- Partner profiles → Location operations: filters distance (evidence: `server/src/controllers/workerController.js`)
- Partner profiles → Spatial search cache: searches nearby (evidence: `server/src/controllers/workerController.js`)
- Proximity endpoints → Location operations: calls (evidence: `server/src/routes/spatialRoutes.js`)
- Location operations → Spatial search cache: uses (evidence: `server/src/services/spatialLocationService.js`)
- Proximity endpoints → MongoDB connections: queries (evidence: `server/src/routes/spatialRoutes.js`)
- Proximity endpoints → SQLite fallback: fallback reads (evidence: `server/src/routes/spatialRoutes.js`)
- Identity and signup → SQLite fallback: writes accounts (evidence: `server/src/controllers/authController.js`)
- Identity and signup → Partner model: generates partner ID (evidence: `server/src/controllers/authController.js`)
- Identity and signup → MongoDB connections: checks connection (evidence: `server/src/controllers/authController.js`)
- Partner model → MongoDB connections: uses connection (evidence: `server/src/models/PartnerModel.js`)
- SQLite fallback → MongoDB connections: dual-store support (evidence: `README.md`)
- REST API server → Address lookup: Google Places fallback (evidence: `server/src/routes/mapsRoutes.js`)
- REST API server → Partner admin view: admin capabilities (evidence: `README.md`)
- REST API server → Client admin view: admin capabilities (evidence: `README.md`)