# krrish0704/dropforge architecture

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

- Interactive diagram: https://gitdiagram.com/krrish0704/dropforge
- Repository: https://github.com/krrish0704/dropforge

## Overview

DropForge combines a live-drop storefront and admin UI with a reservation engine for tenant-scoped sales. The backend workflow is sale creation and browsing, queue entry and turn assignment, stock reservation, then asynchronous payment and order persistence, with inventory rollback on failure. The frontend also has its own sales and queue APIs backed by a separate database layer; the excerpts do not establish how its storefront connects to those APIs or to the Python engine, so those links are omitted.

Main entry points: [`backend/src/api/routes.py`](https://github.com/krrish0704/dropforge/blob/main/backend/src/api/routes.py) (Sale and Queue Routes), [`backend/src/worker/tasks.py`](https://github.com/krrish0704/dropforge/blob/main/backend/src/worker/tasks.py) (Turn and Payment Tasks), [`frontend/app/admin/page.tsx`](https://github.com/krrish0704/dropforge/blob/main/frontend/app/admin/page.tsx) (Sales Admin), [`frontend/app/api/sales/route.ts`](https://github.com/krrish0704/dropforge/blob/main/frontend/app/api/sales/route.ts) (Sales API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Storefront and Admin"]
  node_admin_ui["Sales Admin<br/>[page.tsx]"]
  node_storefront["Storefront"]
  node_queue_page["Queue Confirmation<br/>[page.tsx]"]
end

subgraph group_frontend_api["Frontend APIs"]
  node_sales_api["Sales API<br/>[route.ts]"]
  node_queue_api["Queue API<br/>[route.ts]"]
  node_frontend_db[("Frontend Sales Store<br/>[db.ts]")]
end

subgraph group_reservation["Reservation Engine"]
  node_api_app["FastAPI App<br/>[main.py]"]
  node_routes["Sale and Queue Routes<br/>[routes.py]"]
  node_redis_core[("Redis State<br/>[redis.py]")]
  node_db_core["Tenant Database Access<br/>[db.py]"]
end

subgraph group_worker["Async Processing"]
  node_celery_config["Celery Configuration<br/>[celery_app.py]"]
  node_tasks["Turn and Payment Tasks<br/>[tasks.py]"]
end

node_seller(("Seller"))
node_buyer(("Buyer"))
node_postgres[("PostgreSQL")]

node_seller -.->|"manages drops"| node_admin_ui
node_admin_ui -->|"loads and creates"| node_sales_api
node_sales_api -->|"reads and writes"| node_frontend_db
node_queue_api -->|"looks up sales"| node_frontend_db
node_buyer -.->|"browses drops"| node_storefront
node_api_app -->|"mounts routes"| node_routes
node_seller -.->|"creates sales"| node_routes
node_buyer -.->|"joins and reserves"| node_routes
node_routes -->|"checks and updates"| node_redis_core
node_routes -->|"queries sales"| node_db_core
node_routes -->|"dispatches payment"| node_tasks
node_tasks -->|"uses task app"| node_celery_config
node_tasks -->|"advances turns; rolls back stock"| node_redis_core
node_db_core -.->|"opens sessions"| node_postgres
node_tasks -->|"persists completed orders"| node_postgres

click node_admin_ui "https://github.com/krrish0704/dropforge/blob/main/frontend/app/admin/page.tsx"
click node_storefront "https://github.com/krrish0704/dropforge/blob/main/frontend/components/dropforge-storefront.tsx"
click node_queue_page "https://github.com/krrish0704/dropforge/blob/main/frontend/app/queue/page.tsx"
click node_sales_api "https://github.com/krrish0704/dropforge/blob/main/frontend/app/api/sales/route.ts"
click node_queue_api "https://github.com/krrish0704/dropforge/blob/main/frontend/app/api/queue/route.ts"
click node_frontend_db "https://github.com/krrish0704/dropforge/blob/main/frontend/lib/db.ts"
click node_api_app "https://github.com/krrish0704/dropforge/blob/main/backend/src/main.py"
click node_routes "https://github.com/krrish0704/dropforge/blob/main/backend/src/api/routes.py"
click node_redis_core "https://github.com/krrish0704/dropforge/blob/main/backend/src/core/redis.py"
click node_db_core "https://github.com/krrish0704/dropforge/blob/main/backend/src/core/db.py"
click node_celery_config "https://github.com/krrish0704/dropforge/blob/main/backend/src/worker/celery_app.py"
click node_tasks "https://github.com/krrish0704/dropforge/blob/main/backend/src/worker/tasks.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_admin_ui,node_storefront,node_queue_page toneBlue
class node_sales_api,node_queue_api,node_frontend_db,node_postgres toneAmber
class node_api_app,node_routes,node_redis_core,node_db_core toneMint
class node_celery_config,node_tasks toneRose
class node_seller,node_buyer toneIndigo
```

## Components

### Storefront and Admin

- [Sales Admin](https://github.com/krrish0704/dropforge/blob/main/frontend/app/admin/page.tsx): `frontend/app/admin/page.tsx`
- [Storefront](https://github.com/krrish0704/dropforge/blob/main/frontend/components/dropforge-storefront.tsx): `frontend/components/dropforge-storefront.tsx`
- [Queue Confirmation](https://github.com/krrish0704/dropforge/blob/main/frontend/app/queue/page.tsx): `frontend/app/queue/page.tsx`

### Frontend APIs

- [Sales API](https://github.com/krrish0704/dropforge/blob/main/frontend/app/api/sales/route.ts): `frontend/app/api/sales/route.ts`
- [Queue API](https://github.com/krrish0704/dropforge/blob/main/frontend/app/api/queue/route.ts): `frontend/app/api/queue/route.ts`
- [Frontend Sales Store](https://github.com/krrish0704/dropforge/blob/main/frontend/lib/db.ts): `frontend/lib/db.ts`

### Reservation Engine

- [FastAPI App](https://github.com/krrish0704/dropforge/blob/main/backend/src/main.py): `backend/src/main.py`
- [Sale and Queue Routes](https://github.com/krrish0704/dropforge/blob/main/backend/src/api/routes.py): `backend/src/api/routes.py`
- [Redis State](https://github.com/krrish0704/dropforge/blob/main/backend/src/core/redis.py): `backend/src/core/redis.py`
- [Tenant Database Access](https://github.com/krrish0704/dropforge/blob/main/backend/src/core/db.py): `backend/src/core/db.py`

### Async Processing

- [Celery Configuration](https://github.com/krrish0704/dropforge/blob/main/backend/src/worker/celery_app.py): `backend/src/worker/celery_app.py`
- [Turn and Payment Tasks](https://github.com/krrish0704/dropforge/blob/main/backend/src/worker/tasks.py): `backend/src/worker/tasks.py`

### Other components

- **Seller**
- **Buyer**
- **PostgreSQL**

## Connections

- Seller → Sales Admin: manages drops
- Sales Admin → Sales API: loads and creates (evidence: `frontend/app/admin/page.tsx`)
- Sales API → Frontend Sales Store: reads and writes (evidence: `frontend/app/api/sales/route.ts`)
- Queue API → Frontend Sales Store: looks up sales (evidence: `frontend/app/api/queue/route.ts`)
- Buyer → Storefront: browses drops
- FastAPI App → Sale and Queue Routes: mounts routes (evidence: `backend/src/main.py`)
- Seller → Sale and Queue Routes: creates sales
- Buyer → Sale and Queue Routes: joins and reserves
- Sale and Queue Routes → Redis State: checks and updates (evidence: `backend/src/api/routes.py`)
- Sale and Queue Routes → Tenant Database Access: queries sales (evidence: `backend/src/api/routes.py`)
- Sale and Queue Routes → Turn and Payment Tasks: dispatches payment (evidence: `backend/src/api/routes.py`)
- Turn and Payment Tasks → Celery Configuration: uses task app (evidence: `backend/src/worker/tasks.py`)
- Turn and Payment Tasks → Redis State: advances turns; rolls back stock (evidence: `backend/src/worker/tasks.py`)
- Tenant Database Access → PostgreSQL: opens sessions
- Turn and Payment Tasks → PostgreSQL: persists completed orders (evidence: `backend/src/worker/tasks.py`)
