# agastya-nath123/csl559_csd_group_project architecture

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

- Interactive diagram: https://gitdiagram.com/agastya-nath123/csl559_csd_group_project
- Repository: https://github.com/agastya-nath123/csl559_csd_group_project

## Overview

Dark Store Prototype is a single FastAPI modular monolith for quick-commerce micro-warehousing. Customers locate a serving store, view availability, and place an all-or-nothing timed stock hold; payment leads to picking, scanning, packing, and rider handoff. Store operations also receive inbound stock, manage inventory and replenishment, and use forecasts, dashboards, and network planning. The README documents these capabilities; unsampled implementations are represented at their exact service paths, while edges are limited to documented workflows or source-index references.

Main entry points: [`app/modules/inventory/service.py`](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/inventory/service.py) (Inventory service), [`app/main.py`](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/main.py) (FastAPI app), [`app/modules/pickpack/service.py`](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/pickpack/service.py) (Pick and pack), [`app/modules/fulfilment/service.py`](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/fulfilment/service.py) (Order fulfilment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and access"]
  node_web["Demo screens<br/>[app.js]"]
  node_app["FastAPI app<br/>[main.py]"]
  node_auth["Staff access<br/>[auth.py]"]
  node_db[("Database sessions<br/>[db.py]")]
  node_models["Domain records<br/>[models.py]"]
end

subgraph group_commerce["Commerce and fulfilment"]
  node_serviceability["Store serviceability<br/>[service.py]"]
  node_assortment["Store assortment<br/>[service.py]"]
  node_inventory_api["Inventory API<br/>[router.py]"]
  node_inventory["Inventory service<br/>[service.py]"]
  node_fulfilment["Order fulfilment<br/>[service.py]"]
  node_pickpack["Pick and pack<br/>[service.py]"]
  node_riders["Rider handoff<br/>[riders.py]"]
end

subgraph group_stock["Stock and supply"]
  node_inbound["Inbound receiving<br/>[service.py]"]
  node_replenishment["Replenishment<br/>[service.py]"]
end

subgraph group_planning["Planning and operations"]
  node_forecasting["Demand forecasting<br/>[service.py]"]
  node_slotting["Bin slotting<br/>[service.py]"]
  node_network["Network planning<br/>[service.py]"]
  node_dashboard["Ops dashboard<br/>[service.py]"]
  node_events["Live event feed<br/>[events.py]"]
  node_background["Timed jobs<br/>[background.py]"]
end

node_customer(("Customer"))
node_staff(("Store staff"))

node_customer -->|"uses"| node_web
node_staff -->|"uses"| node_web
node_web -->|"calls API"| node_app
node_app -->|"routes login"| node_auth
node_app -->|"mounts routes"| node_inventory_api
node_app -->|"initializes"| node_db
node_inventory_api -->|"calls"| node_inventory
node_customer -->|"requests store"| node_serviceability
node_customer -->|"browses items"| node_assortment
node_customer -->|"requests availability"| node_inventory_api
node_customer -->|"holds cart"| node_inventory_api
node_inventory -->|"updates stock records"| node_models
node_inventory -->|"publishes stock events"| node_events
node_fulfilment -->|"uses stock operations"| node_inventory
node_fulfilment -->|"creates pick tasks"| node_pickpack
node_pickpack -->|"uses stock operations"| node_inventory
node_pickpack -->|"calls"| node_fulfilment
node_pickpack -->|"hands off crate"| node_riders
node_inbound -->|"puts away stock"| node_inventory
node_inbound -->|"requests bin placement"| node_slotting
node_replenishment -->|"reads forecasts"| node_forecasting
node_replenishment -->|"uses stock operations"| node_inventory
node_slotting -->|"uses forecast data"| node_forecasting
node_slotting -->|"uses stock operations"| node_inventory
node_network -->|"uses service areas"| node_serviceability
node_dashboard -->|"reads stock data"| node_inventory
node_dashboard -->|"reads service data"| node_serviceability
node_dashboard -->|"reads event feed"| node_events
node_background -->|"sweeps stock"| node_inventory
node_background -->|"runs reordering"| node_replenishment
node_background -->|"checks job state"| node_fulfilment

click node_web "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/web/app.js"
click node_app "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/main.py"
click node_auth "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/auth.py"
click node_db "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/db.py"
click node_models "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/models.py"
click node_serviceability "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/serviceability/service.py"
click node_assortment "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/assortment/service.py"
click node_inventory_api "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/inventory/router.py"
click node_inventory "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/inventory/service.py"
click node_fulfilment "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/fulfilment/service.py"
click node_pickpack "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/pickpack/service.py"
click node_riders "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/fulfilment/riders.py"
click node_inbound "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/inbound/service.py"
click node_replenishment "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/replenishment/service.py"
click node_forecasting "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/forecasting/service.py"
click node_slotting "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/slotting/service.py"
click node_network "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/network_planning/service.py"
click node_dashboard "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/dashboard/service.py"
click node_events "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/events.py"
click node_background "https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/background.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_web,node_app,node_auth,node_db,node_models toneBlue
class node_serviceability,node_assortment,node_inventory_api,node_inventory,node_fulfilment,node_pickpack,node_riders toneAmber
class node_inbound,node_replenishment toneMint
class node_forecasting,node_slotting,node_network,node_dashboard,node_events,node_background toneRose
class node_customer,node_staff toneIndigo
```

## Components

### Entry and access

- [Demo screens](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/web/app.js): `web/app.js`
- [FastAPI app](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/main.py): `app/main.py`
- [Staff access](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/auth.py): `app/auth.py`
- [Database sessions](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/db.py): `app/db.py`
- [Domain records](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/models.py): `app/models.py`

### Commerce and fulfilment

- [Store serviceability](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/serviceability/service.py): `app/modules/serviceability/service.py`
- [Store assortment](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/assortment/service.py): `app/modules/assortment/service.py`
- [Inventory API](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/inventory/router.py): `app/modules/inventory/router.py`
- [Inventory service](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/inventory/service.py): `app/modules/inventory/service.py`
- [Order fulfilment](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/fulfilment/service.py): `app/modules/fulfilment/service.py`
- [Pick and pack](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/pickpack/service.py): `app/modules/pickpack/service.py`
- [Rider handoff](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/fulfilment/riders.py): `app/modules/fulfilment/riders.py`

### Stock and supply

- [Inbound receiving](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/inbound/service.py): `app/modules/inbound/service.py`
- [Replenishment](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/replenishment/service.py): `app/modules/replenishment/service.py`

### Planning and operations

- [Demand forecasting](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/forecasting/service.py): `app/modules/forecasting/service.py`
- [Bin slotting](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/slotting/service.py): `app/modules/slotting/service.py`
- [Network planning](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/network_planning/service.py): `app/modules/network_planning/service.py`
- [Ops dashboard](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/modules/dashboard/service.py): `app/modules/dashboard/service.py`
- [Live event feed](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/events.py): `app/events.py`
- [Timed jobs](https://github.com/agastya-nath123/csl559_csd_group_project/blob/main/app/background.py): `app/background.py`

### Other components

- **Customer**
- **Store staff**

## Connections

- Customer → Demo screens: uses (evidence: `README.md`)
- Store staff → Demo screens: uses (evidence: `README.md`)
- Demo screens → FastAPI app: calls API (evidence: `README.md`)
- FastAPI app → Staff access: routes login (evidence: `app/main.py`)
- FastAPI app → Inventory API: mounts routes (evidence: `app/main.py`)
- FastAPI app → Database sessions: initializes (evidence: `app/main.py`)
- Inventory API → Inventory service: calls (evidence: `app/modules/inventory/router.py`)
- Customer → Store serviceability: requests store (evidence: `README.md`)
- Customer → Store assortment: browses items (evidence: `README.md`)
- Customer → Inventory API: requests availability (evidence: `README.md`)
- Customer → Inventory API: holds cart (evidence: `README.md`)
- Inventory service → Domain records: updates stock records (evidence: `app/modules/inventory/service.py`)
- Inventory service → Live event feed: publishes stock events (evidence: `app/modules/inventory/service.py`)
- Order fulfilment → Inventory service: uses stock operations (evidence: `app/modules/fulfilment/service.py`)
- Order fulfilment → Pick and pack: creates pick tasks (evidence: `README.md`)
- Pick and pack → Inventory service: uses stock operations (evidence: `app/modules/pickpack/service.py`)
- Pick and pack → Order fulfilment: calls (evidence: `app/modules/pickpack/service.py`)
- Pick and pack → Rider handoff: hands off crate (evidence: `README.md`)
- Inbound receiving → Inventory service: puts away stock (evidence: `app/modules/inbound/service.py`)
- Inbound receiving → Bin slotting: requests bin placement (evidence: `app/modules/inbound/service.py`)
- Replenishment → Demand forecasting: reads forecasts (evidence: `app/modules/replenishment/service.py`)
- Replenishment → Inventory service: uses stock operations (evidence: `app/modules/replenishment/service.py`)
- Bin slotting → Demand forecasting: uses forecast data (evidence: `app/modules/slotting/service.py`)
- Bin slotting → Inventory service: uses stock operations (evidence: `app/modules/slotting/service.py`)
- Network planning → Store serviceability: uses service areas (evidence: `app/modules/network_planning/service.py`)
- Ops dashboard → Inventory service: reads stock data (evidence: `app/modules/dashboard/service.py`)
- Ops dashboard → Store serviceability: reads service data (evidence: `app/modules/dashboard/service.py`)
- Ops dashboard → Live event feed: reads event feed (evidence: `app/modules/dashboard/service.py`)
- Timed jobs → Inventory service: sweeps stock (evidence: `app/background.py`)
- Timed jobs → Replenishment: runs reordering (evidence: `app/background.py`)
- Timed jobs → Order fulfilment: checks job state (evidence: `app/background.py`)
