# ridwantaufk/flash-sale-inventory architecture

> Architecture diagram of the GitHub repository ridwantaufk/flash-sale-inventory, 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/ridwantaufk/flash-sale-inventory
- Repository: https://github.com/ridwantaufk/flash-sale-inventory

## Overview

Flash Sale Inventory Reservation lets a user inspect stock, place a temporary hold, and confirm it before expiry; otherwise expired units return to availability. The React dashboard tracks local reservation state and countdowns while the Go API owns validation and reservation operations backed by PostgreSQL. A background reaper sweeps expired holds. The principal backend wiring and frontend calls are excerpted; the README documents the database schema/seed and API capabilities, but migration internals were not sampled.

Main entry points: [`backend/cmd/server/main.go`](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/cmd/server/main.go) (Server lifecycle), [`frontend/src/App.tsx`](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/App.tsx) (Dashboard state), [`frontend/src/components/ReservationList.tsx`](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/components/ReservationList.tsx) (Reservation list), [`backend/internal/server/server.go`](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/server/server.go) (HTTP router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Stock dashboard"]
  node_app["Dashboard state<br/>[App.tsx]"]
  node_stockpanel["Stock panel<br/>[StockPanel.tsx]"]
  node_reserveform["Reserve form<br/>[ReserveForm.tsx]"]
  node_reservationlist["Reservation list"]
  node_alerts["Error display<br/>[Alert.tsx]"]
  node_clock["Countdown clock<br/>[useNow.ts]"]
  node_localstorage[("Browser reservation cache<br/>[storage.ts]")]
  node_client["Inventory API client<br/>[client.ts]"]
end

subgraph group_api["Inventory API"]
  node_http["HTTP router<br/>[server.go]"]
  node_handler["Inventory handlers<br/>[handler.go]"]
  node_httpx["HTTP support<br/>[httpx.go]"]
end

subgraph group_domain["Reservation domain"]
  node_service["Reservation service<br/>[service.go]"]
  node_model["Inventory model<br/>[inventory.go]"]
  node_reaper["Expiry reaper<br/>[reaper.go]"]
end

subgraph group_runtime["Runtime infrastructure"]
  node_entry["Server lifecycle<br/>[main.go]"]
  node_config["Environment config<br/>[config.go]"]
  node_pool["Database pool<br/>[pg.go]"]
end

subgraph group_persistence["Persistence"]
  node_repository["Inventory repository<br/>[repository.go]"]
  node_postgres[("PostgreSQL")]
end

node_user(("Dashboard user"))
node_browser(("Browser fetch"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_stockpanel
node_app -->|"renders"| node_reserveform
node_app -->|"renders"| node_reservationlist
node_app -->|"loads and saves"| node_localstorage
node_app -->|"updates time"| node_clock
node_stockpanel -->|"fetches stock"| node_client
node_reserveform -->|"requests hold"| node_client
node_reservationlist -->|"confirms hold"| node_client
node_stockpanel -->|"renders errors"| node_alerts
node_reserveform -->|"renders errors"| node_alerts
node_reservationlist -->|"renders errors"| node_alerts
node_reservationlist -->|"computes countdown"| node_clock
node_client -->|"fetches"| node_browser
node_browser -->|"sends API requests"| node_http
node_entry -->|"loads settings"| node_config
node_entry -->|"opens pool"| node_pool
node_entry -->|"constructs"| node_repository
node_entry -->|"constructs"| node_service
node_entry -->|"runs"| node_reaper
node_entry -->|"serves"| node_http
node_entry -->|"constructs"| node_handler
node_entry -->|"configures readiness"| node_httpx
node_http -.->|"routes inventory"| node_handler
node_handler -.->|"delegates operations"| node_service
node_service -.->|"executes operations"| node_repository
node_repository -.->|"reads and writes"| node_postgres
node_reaper -.->|"sweeps expired holds"| node_service
node_http -.->|"uses support"| node_httpx
node_pool -.->|"connects"| node_postgres

click node_app "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/App.tsx"
click node_stockpanel "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/components/StockPanel.tsx"
click node_reserveform "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/components/ReserveForm.tsx"
click node_reservationlist "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/components/ReservationList.tsx"
click node_alerts "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/components/Alert.tsx"
click node_clock "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/hooks/useNow.ts"
click node_localstorage "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/storage.ts"
click node_client "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/api/client.ts"
click node_http "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/server/server.go"
click node_handler "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/inventory/handler.go"
click node_service "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/inventory/service.go"
click node_model "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/inventory/inventory.go"
click node_repository "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/inventory/repository.go"
click node_postgres "https://github.com/ridwantaufk/flash-sale-inventory/tree/main/db/migrations"
click node_reaper "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/inventory/reaper.go"
click node_entry "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/cmd/server/main.go"
click node_config "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/config/config.go"
click node_pool "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/platform/pg/pg.go"
click node_httpx "https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/transport/httpx/httpx.go"

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_stockpanel,node_reserveform,node_reservationlist,node_alerts,node_clock,node_localstorage,node_client,node_user,node_browser toneBlue
class node_http,node_handler,node_httpx toneAmber
class node_service,node_model,node_reaper toneMint
class node_entry,node_config,node_pool toneRose
class node_repository,node_postgres toneIndigo
```

## Components

### Stock dashboard

- [Dashboard state](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Stock panel](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/components/StockPanel.tsx): `frontend/src/components/StockPanel.tsx`
- [Reserve form](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/components/ReserveForm.tsx): `frontend/src/components/ReserveForm.tsx`
- [Reservation list](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/components/ReservationList.tsx): `frontend/src/components/ReservationList.tsx`
- [Error display](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/components/Alert.tsx): `frontend/src/components/Alert.tsx`
- [Countdown clock](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/hooks/useNow.ts): `frontend/src/hooks/useNow.ts`
- [Browser reservation cache](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/storage.ts): `frontend/src/storage.ts`
- [Inventory API client](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Inventory API

- [HTTP router](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/server/server.go): `backend/internal/server/server.go`
- [Inventory handlers](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/inventory/handler.go): `backend/internal/inventory/handler.go`
- [HTTP support](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/transport/httpx/httpx.go): `backend/internal/transport/httpx/httpx.go`

### Reservation domain

- [Reservation service](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/inventory/service.go): `backend/internal/inventory/service.go`
- [Inventory model](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/inventory/inventory.go): `backend/internal/inventory/inventory.go`
- [Expiry reaper](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/inventory/reaper.go): `backend/internal/inventory/reaper.go`

### Runtime infrastructure

- [Server lifecycle](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/cmd/server/main.go): `backend/cmd/server/main.go`
- [Environment config](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/config/config.go): `backend/internal/config/config.go`
- [Database pool](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/platform/pg/pg.go): `backend/internal/platform/pg/pg.go`

### Persistence

- [Inventory repository](https://github.com/ridwantaufk/flash-sale-inventory/blob/main/backend/internal/inventory/repository.go): `backend/internal/inventory/repository.go`
- [PostgreSQL](https://github.com/ridwantaufk/flash-sale-inventory/tree/main/db/migrations): `db/migrations`

### Other components

- **Dashboard user**
- **Browser fetch**

## Connections

- Dashboard user → Dashboard state: uses (evidence: `README.md`)
- Dashboard state → Stock panel: renders (evidence: `frontend/src/App.tsx`)
- Dashboard state → Reserve form: renders (evidence: `frontend/src/App.tsx`)
- Dashboard state → Reservation list: renders (evidence: `frontend/src/App.tsx`)
- Dashboard state → Browser reservation cache: loads and saves (evidence: `frontend/src/App.tsx`)
- Dashboard state → Countdown clock: updates time (evidence: `frontend/src/App.tsx`)
- Stock panel → Inventory API client: fetches stock (evidence: `frontend/src/components/StockPanel.tsx`)
- Reserve form → Inventory API client: requests hold (evidence: `frontend/src/components/ReserveForm.tsx`)
- Reservation list → Inventory API client: confirms hold (evidence: `frontend/src/components/ReservationList.tsx`)
- Stock panel → Error display: renders errors (evidence: `frontend/src/components/StockPanel.tsx`)
- Reserve form → Error display: renders errors (evidence: `frontend/src/components/ReserveForm.tsx`)
- Reservation list → Error display: renders errors (evidence: `frontend/src/components/ReservationList.tsx`)
- Reservation list → Countdown clock: computes countdown (evidence: `frontend/src/components/ReservationList.tsx`)
- Inventory API client → Browser fetch: fetches (evidence: `frontend/src/api/client.ts`)
- Browser fetch → HTTP router: sends API requests (evidence: `README.md`)
- Server lifecycle → Environment config: loads settings (evidence: `backend/cmd/server/main.go`)
- Server lifecycle → Database pool: opens pool (evidence: `backend/cmd/server/main.go`)
- Server lifecycle → Inventory repository: constructs (evidence: `backend/cmd/server/main.go`)
- Server lifecycle → Reservation service: constructs (evidence: `backend/cmd/server/main.go`)
- Server lifecycle → Expiry reaper: runs (evidence: `backend/cmd/server/main.go`)
- Server lifecycle → HTTP router: serves (evidence: `backend/cmd/server/main.go`)
- Server lifecycle → Inventory handlers: constructs (evidence: `backend/cmd/server/main.go`)
- Server lifecycle → HTTP support: configures readiness (evidence: `backend/cmd/server/main.go`)
- HTTP router → Inventory handlers: routes inventory
- Inventory handlers → Reservation service: delegates operations
- Reservation service → Inventory repository: executes operations
- Inventory repository → PostgreSQL: reads and writes
- Expiry reaper → Reservation service: sweeps expired holds
- HTTP router → HTTP support: uses support
- Database pool → PostgreSQL: connects
