# cancinoray/stockroom architecture

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

- Interactive diagram: https://gitdiagram.com/cancinoray/stockroom
- Repository: https://github.com/cancinoray/stockroom

## Overview

Stockroom is a distributor inventory and order-management application. Users inspect stock and its movement history, receive or adjust quantities, reserve all lines of an order atomically, then cancel or fulfil orders; the append-only ledger and invariant checks make stock changes auditable. The graph separates the React screens and API client, HTTP/API handling, domain rules, and persistence, while retaining telemetry and the documented on-call response capability. Some screen, domain, and operations implementation was not sampled, so uncertain links are omitted or marked unverified.

Main entry points: [`backend/api/stock.py`](https://github.com/cancinoray/stockroom/blob/main/backend/api/stock.py) (Stock endpoints), [`backend/main.py`](https://github.com/cancinoray/stockroom/blob/main/backend/main.py) (FastAPI application), [`backend/api/orders.py`](https://github.com/cancinoray/stockroom/blob/main/backend/api/orders.py) (Order endpoints), [`frontend/src/App.tsx`](https://github.com/cancinoray/stockroom/blob/main/frontend/src/App.tsx) (Screen navigation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_app["Screen navigation<br/>[App.tsx]"]
  node_inventory["Inventory screen"]
  node_place["Place-order screen"]
  node_orders_ui["Orders screen<br/>[OrdersScreen.tsx]"]
  node_hooks["API query hooks<br/>[hooks.ts]"]
  node_client["HTTP API client<br/>[client.ts]"]
end

subgraph group_api["HTTP API"]
  node_main["FastAPI application<br/>[main.py]"]
  node_stock_api["Stock endpoints<br/>[stock.py]"]
  node_orders_api["Order endpoints<br/>[orders.py]"]
  node_products_api["Product endpoints<br/>[products.py]"]
  node_contract["API schemas<br/>[schemas.py]"]
  node_openapi["OpenAPI contract<br/>[openapi.py]"]
  node_problems["Problem responses<br/>[problems.py]"]
end

subgraph group_domain["Inventory domain"]
  node_stock_domain["Stock rules<br/>[stock.py]"]
  node_movements["Movement ledger<br/>[movements.py]"]
  node_invariants["Ledger invariants<br/>[invariants.py]"]
end

subgraph group_data["Persistence and telemetry"]
  node_db_session["Database sessions<br/>[session.py]"]
  node_models["Database models<br/>[models.py]"]
  node_database[("PostgreSQL")]
  node_telemetry["Telemetry<br/>[telemetry.py]"]
end

subgraph group_ops["Operations response"]
  node_evidence["Evidence collection"]
  node_packet["Evidence packet<br/>[packet.py]"]
  node_responder["Responder agent<br/>[run_responder.py]"]
  node_policy["Response policy<br/>[policy.py]"]
end

node_staff(("Distributor staff"))
node_collector["OTel collector"]
node_alerts(("Alert source"))

node_staff -->|"uses"| node_app
node_app -->|"shows"| node_inventory
node_app -->|"shows"| node_place
node_app -->|"shows"| node_orders_ui
node_inventory -.->|"queries"| node_hooks
node_place -->|"queries"| node_hooks
node_orders_ui -->|"queries"| node_hooks
node_hooks -.->|"calls"| node_client
node_client -->|"HTTP requests"| node_main
node_main -->|"mounts"| node_stock_api
node_main -->|"mounts"| node_orders_api
node_main -->|"mounts"| node_products_api
node_main -->|"installs"| node_openapi
node_stock_api -->|"documents"| node_contract
node_orders_api -->|"documents"| node_contract
node_openapi -->|"uses schemas"| node_contract
node_stock_api -->|"builds errors"| node_problems
node_orders_api -->|"uses rules"| node_stock_domain
node_stock_api -->|"checks"| node_invariants
node_stock_domain -->|"uses ledger"| node_movements
node_stock_api -->|"opens sessions"| node_db_session
node_orders_api -->|"opens sessions"| node_db_session
node_products_api -->|"opens sessions"| node_db_session
node_db_session -->|"connects"| node_database
node_stock_api -->|"queries and writes"| node_models
node_orders_api -->|"queries and writes"| node_models
node_products_api -->|"queries"| node_models
node_stock_api -->|"locks and appends"| node_database
node_orders_api -->|"locks and reserves"| node_database
node_main -->|"starts and instruments"| node_telemetry
node_telemetry -->|"checks drift"| node_invariants
node_telemetry -.->|"exports OTLP"| node_collector
node_alerts -.->|"triggers"| node_evidence
node_evidence -->|"assembles"| node_packet
node_packet -.->|"informs"| node_responder
node_responder -->|"uses policy"| node_policy

click node_app "https://github.com/cancinoray/stockroom/blob/main/frontend/src/App.tsx"
click node_inventory "https://github.com/cancinoray/stockroom/blob/main/frontend/src/screens/InventoryScreen.tsx"
click node_place "https://github.com/cancinoray/stockroom/blob/main/frontend/src/screens/PlaceOrderScreen.tsx"
click node_orders_ui "https://github.com/cancinoray/stockroom/blob/main/frontend/src/screens/OrdersScreen.tsx"
click node_hooks "https://github.com/cancinoray/stockroom/blob/main/frontend/src/api/hooks.ts"
click node_client "https://github.com/cancinoray/stockroom/blob/main/frontend/src/api/client.ts"
click node_main "https://github.com/cancinoray/stockroom/blob/main/backend/main.py"
click node_stock_api "https://github.com/cancinoray/stockroom/blob/main/backend/api/stock.py"
click node_orders_api "https://github.com/cancinoray/stockroom/blob/main/backend/api/orders.py"
click node_products_api "https://github.com/cancinoray/stockroom/blob/main/backend/api/products.py"
click node_contract "https://github.com/cancinoray/stockroom/blob/main/backend/api/schemas.py"
click node_openapi "https://github.com/cancinoray/stockroom/blob/main/backend/api/openapi.py"
click node_problems "https://github.com/cancinoray/stockroom/blob/main/backend/api/problems.py"
click node_stock_domain "https://github.com/cancinoray/stockroom/blob/main/backend/domain/stock.py"
click node_movements "https://github.com/cancinoray/stockroom/blob/main/backend/domain/movements.py"
click node_invariants "https://github.com/cancinoray/stockroom/blob/main/backend/domain/invariants.py"
click node_db_session "https://github.com/cancinoray/stockroom/blob/main/backend/db/session.py"
click node_models "https://github.com/cancinoray/stockroom/blob/main/backend/db/models.py"
click node_telemetry "https://github.com/cancinoray/stockroom/blob/main/backend/telemetry.py"
click node_evidence "https://github.com/cancinoray/stockroom/blob/main/on-call-engineer/collect_evidence.py"
click node_packet "https://github.com/cancinoray/stockroom/blob/main/on-call-engineer/packet.py"
click node_responder "https://github.com/cancinoray/stockroom/blob/main/on-call-engineer/run_responder.py"
click node_policy "https://github.com/cancinoray/stockroom/blob/main/on-call-engineer/policy.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_inventory,node_place,node_orders_ui,node_hooks,node_client toneBlue
class node_main,node_stock_api,node_orders_api,node_products_api,node_contract,node_openapi,node_problems toneAmber
class node_stock_domain,node_movements,node_invariants toneMint
class node_db_session,node_models,node_database,node_telemetry toneRose
class node_evidence,node_packet,node_responder,node_policy,node_staff,node_collector,node_alerts toneIndigo
```

## Components

### User interface

- [Screen navigation](https://github.com/cancinoray/stockroom/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Inventory screen](https://github.com/cancinoray/stockroom/blob/main/frontend/src/screens/InventoryScreen.tsx): `frontend/src/screens/InventoryScreen.tsx`
- [Place-order screen](https://github.com/cancinoray/stockroom/blob/main/frontend/src/screens/PlaceOrderScreen.tsx): `frontend/src/screens/PlaceOrderScreen.tsx`
- [Orders screen](https://github.com/cancinoray/stockroom/blob/main/frontend/src/screens/OrdersScreen.tsx): `frontend/src/screens/OrdersScreen.tsx`
- [API query hooks](https://github.com/cancinoray/stockroom/blob/main/frontend/src/api/hooks.ts): `frontend/src/api/hooks.ts`
- [HTTP API client](https://github.com/cancinoray/stockroom/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### HTTP API

- [FastAPI application](https://github.com/cancinoray/stockroom/blob/main/backend/main.py): `backend/main.py`
- [Stock endpoints](https://github.com/cancinoray/stockroom/blob/main/backend/api/stock.py): `backend/api/stock.py`
- [Order endpoints](https://github.com/cancinoray/stockroom/blob/main/backend/api/orders.py): `backend/api/orders.py`
- [Product endpoints](https://github.com/cancinoray/stockroom/blob/main/backend/api/products.py): `backend/api/products.py`
- [API schemas](https://github.com/cancinoray/stockroom/blob/main/backend/api/schemas.py): `backend/api/schemas.py`
- [OpenAPI contract](https://github.com/cancinoray/stockroom/blob/main/backend/api/openapi.py): `backend/api/openapi.py`
- [Problem responses](https://github.com/cancinoray/stockroom/blob/main/backend/api/problems.py): `backend/api/problems.py`

### Inventory domain

- [Stock rules](https://github.com/cancinoray/stockroom/blob/main/backend/domain/stock.py): `backend/domain/stock.py`
- [Movement ledger](https://github.com/cancinoray/stockroom/blob/main/backend/domain/movements.py): `backend/domain/movements.py`
- [Ledger invariants](https://github.com/cancinoray/stockroom/blob/main/backend/domain/invariants.py): `backend/domain/invariants.py`

### Persistence and telemetry

- [Database sessions](https://github.com/cancinoray/stockroom/blob/main/backend/db/session.py): `backend/db/session.py`
- [Database models](https://github.com/cancinoray/stockroom/blob/main/backend/db/models.py): `backend/db/models.py`
- **PostgreSQL**
- [Telemetry](https://github.com/cancinoray/stockroom/blob/main/backend/telemetry.py): `backend/telemetry.py`

### Operations response

- [Evidence collection](https://github.com/cancinoray/stockroom/blob/main/on-call-engineer/collect_evidence.py): `on-call-engineer/collect_evidence.py`
- [Evidence packet](https://github.com/cancinoray/stockroom/blob/main/on-call-engineer/packet.py): `on-call-engineer/packet.py`
- [Responder agent](https://github.com/cancinoray/stockroom/blob/main/on-call-engineer/run_responder.py): `on-call-engineer/run_responder.py`
- [Response policy](https://github.com/cancinoray/stockroom/blob/main/on-call-engineer/policy.py): `on-call-engineer/policy.py`

### Other components

- **Distributor staff**
- **OTel collector**
- **Alert source**

## Connections

- Distributor staff → Screen navigation: uses (evidence: `README.md`)
- Screen navigation → Inventory screen: shows (evidence: `frontend/src/App.tsx`)
- Screen navigation → Place-order screen: shows (evidence: `frontend/src/App.tsx`)
- Screen navigation → Orders screen: shows (evidence: `frontend/src/App.tsx`)
- Inventory screen → API query hooks: queries
- Place-order screen → API query hooks: queries (evidence: `frontend/src/screens/PlaceOrderScreen.tsx`)
- Orders screen → API query hooks: queries (evidence: `frontend/src/screens/OrdersScreen.tsx`)
- API query hooks → HTTP API client: calls
- HTTP API client → FastAPI application: HTTP requests (evidence: `README.md`)
- FastAPI application → Stock endpoints: mounts (evidence: `backend/main.py`)
- FastAPI application → Order endpoints: mounts (evidence: `backend/main.py`)
- FastAPI application → Product endpoints: mounts (evidence: `backend/main.py`)
- FastAPI application → OpenAPI contract: installs (evidence: `backend/main.py`)
- Stock endpoints → API schemas: documents (evidence: `backend/api/stock.py`)
- Order endpoints → API schemas: documents (evidence: `backend/api/orders.py`)
- OpenAPI contract → API schemas: uses schemas (evidence: `backend/api/openapi.py`)
- Stock endpoints → Problem responses: builds errors (evidence: `backend/api/stock.py`)
- Order endpoints → Stock rules: uses rules (evidence: `backend/api/orders.py`)
- Stock endpoints → Ledger invariants: checks (evidence: `backend/api/stock.py`)
- Stock rules → Movement ledger: uses ledger (evidence: `backend/domain/stock.py`)
- Stock endpoints → Database sessions: opens sessions (evidence: `backend/api/stock.py`)
- Order endpoints → Database sessions: opens sessions (evidence: `backend/api/orders.py`)
- Product endpoints → Database sessions: opens sessions (evidence: `backend/api/products.py`)
- Database sessions → PostgreSQL: connects (evidence: `backend/db/session.py`)
- Stock endpoints → Database models: queries and writes (evidence: `backend/api/stock.py`)
- Order endpoints → Database models: queries and writes (evidence: `backend/api/orders.py`)
- Product endpoints → Database models: queries (evidence: `backend/api/products.py`)
- Stock endpoints → PostgreSQL: locks and appends (evidence: `README.md`)
- Order endpoints → PostgreSQL: locks and reserves (evidence: `README.md`)
- FastAPI application → Telemetry: starts and instruments (evidence: `backend/main.py`)
- Telemetry → Ledger invariants: checks drift (evidence: `backend/telemetry.py`)
- Telemetry → OTel collector: exports OTLP (evidence: `README.md`)
- Alert source → Evidence collection: triggers
- Evidence collection → Evidence packet: assembles (evidence: `on-call-engineer/collect_evidence.py`)
- Evidence packet → Responder agent: informs (evidence: `README.md`)
- Responder agent → Response policy: uses policy (evidence: `on-call-engineer/run_responder.py`)
