# kiruiian/urban_liquor architecture

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

- Interactive diagram: https://gitdiagram.com/kiruiian/urban_liquor
- Repository: https://github.com/kiruiian/urban_liquor

## Overview

Urban Liquor POS is a staff-facing liquor-store point-of-sale system. Staff sign in, browse the catalog, and complete checkout with server-calculated prices and cash, M-Pesa, or split tenders; the API records sales and stock movements transactionally. Admins also manage products, stock, and staff, while staff can review sale history and summaries. The graph reflects the sampled API wiring and the README’s documented capabilities; unsampled frontend actions and reporting implementation are represented only at subsystem level.

Main entry points: [`frontend/src/App.tsx`](https://github.com/kiruiian/urban_liquor/blob/main/frontend/src/App.tsx) (POS interface), [`app/modules/auth/router.py`](https://github.com/kiruiian/urban_liquor/blob/main/app/modules/auth/router.py) (Staff authentication), [`app/core/database.py`](https://github.com/kiruiian/urban_liquor/blob/main/app/core/database.py) (Database sessions), [`app/modules/sales/router.py`](https://github.com/kiruiian/urban_liquor/blob/main/app/modules/sales/router.py) (Checkout and sales)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["POS client"]
  node_webpos["POS interface<br/>[App.tsx]"]
end

subgraph group_api["API and access"]
  node_apiapp["API application<br/>[main.py]"]
  node_auth["Staff authentication<br/>[router.py]"]
  node_authguard["Token and role checks<br/>[dependencies.py]"]
  node_security["Credential and tokens<br/>[security.py]"]
  node_dbsession["Database sessions<br/>[database.py]"]
  node_settings["Application settings<br/>[config.py]"]
end

subgraph group_operations["Store operations"]
  node_inventory["Product catalog<br/>[router.py]"]
  node_stock["Stock adjustments<br/>[router.py]"]
  node_checkout["Checkout and sales<br/>[router.py]"]
  node_history["Sale history<br/>[router.py]"]
  node_reporting["Sales summaries<br/>[router.py]"]
end

subgraph group_state["Persistent state"]
  node_staffrecords[("Staff records<br/>[models.py]")]
  node_products[("Products and movements<br/>[models.py]")]
  node_salesrecords[("Sales and payments<br/>[models.py]")]
end

node_staff(("Staff user"))

node_staff -->|"uses"| node_webpos
node_webpos -->|"signs in"| node_auth
node_webpos -->|"manages catalog"| node_inventory
node_webpos -->|"checks out"| node_checkout
node_webpos -->|"reviews sales"| node_history
node_webpos -->|"views summaries"| node_reporting
node_webpos -->|"adjusts stock"| node_stock
node_webpos -->|"manages staff"| node_auth
node_apiapp -->|"registers route"| node_auth
node_apiapp -->|"registers route"| node_inventory
node_apiapp -->|"registers route"| node_checkout
node_auth -->|"checks access"| node_authguard
node_auth -->|"verifies and issues"| node_security
node_auth -->|"queries staff"| node_dbsession
node_authguard -->|"decodes token"| node_security
node_authguard -->|"loads staff"| node_dbsession
node_auth -->|"reads and writes"| node_staffrecords
node_inventory -->|"requires staff role"| node_authguard
node_inventory -->|"queries catalog"| node_dbsession
node_inventory -->|"reads and writes"| node_products
node_stock -->|"records movement"| node_products
node_checkout -->|"requires staff"| node_authguard
node_checkout -->|"persists checkout"| node_dbsession
node_checkout -->|"locks and updates stock"| node_products
node_checkout -->|"records sale and tenders"| node_salesrecords
node_history -->|"queries sales"| node_dbsession
node_history -->|"reads transactions"| node_salesrecords
node_reporting -->|"aggregates sales"| node_dbsession
node_reporting -->|"reads payment totals"| node_salesrecords
node_dbsession -->|"loads database URL"| node_settings

click node_webpos "https://github.com/kiruiian/urban_liquor/blob/main/frontend/src/App.tsx"
click node_apiapp "https://github.com/kiruiian/urban_liquor/blob/main/app/main.py"
click node_auth "https://github.com/kiruiian/urban_liquor/blob/main/app/modules/auth/router.py"
click node_authguard "https://github.com/kiruiian/urban_liquor/blob/main/app/modules/auth/dependencies.py"
click node_security "https://github.com/kiruiian/urban_liquor/blob/main/app/core/security.py"
click node_inventory "https://github.com/kiruiian/urban_liquor/blob/main/app/modules/inventory/router.py"
click node_stock "https://github.com/kiruiian/urban_liquor/blob/main/app/modules/inventory/router.py"
click node_checkout "https://github.com/kiruiian/urban_liquor/blob/main/app/modules/sales/router.py"
click node_history "https://github.com/kiruiian/urban_liquor/blob/main/app/modules/sales/router.py"
click node_reporting "https://github.com/kiruiian/urban_liquor/blob/main/app/modules/sales/router.py"
click node_staffrecords "https://github.com/kiruiian/urban_liquor/blob/main/app/modules/auth/models.py"
click node_products "https://github.com/kiruiian/urban_liquor/blob/main/app/modules/inventory/models.py"
click node_salesrecords "https://github.com/kiruiian/urban_liquor/blob/main/app/modules/sales/models.py"
click node_dbsession "https://github.com/kiruiian/urban_liquor/blob/main/app/core/database.py"
click node_settings "https://github.com/kiruiian/urban_liquor/blob/main/app/core/config.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_webpos,node_staff toneBlue
class node_apiapp,node_auth,node_authguard,node_security,node_dbsession,node_settings toneAmber
class node_inventory,node_stock,node_checkout,node_history,node_reporting toneMint
class node_staffrecords,node_products,node_salesrecords toneRose
```

## Components

### POS client

- [POS interface](https://github.com/kiruiian/urban_liquor/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### API and access

- [API application](https://github.com/kiruiian/urban_liquor/blob/main/app/main.py): `app/main.py`
- [Staff authentication](https://github.com/kiruiian/urban_liquor/blob/main/app/modules/auth/router.py): `app/modules/auth/router.py`
- [Token and role checks](https://github.com/kiruiian/urban_liquor/blob/main/app/modules/auth/dependencies.py): `app/modules/auth/dependencies.py`
- [Credential and tokens](https://github.com/kiruiian/urban_liquor/blob/main/app/core/security.py): `app/core/security.py`
- [Database sessions](https://github.com/kiruiian/urban_liquor/blob/main/app/core/database.py): `app/core/database.py`
- [Application settings](https://github.com/kiruiian/urban_liquor/blob/main/app/core/config.py): `app/core/config.py`

### Store operations

- [Product catalog](https://github.com/kiruiian/urban_liquor/blob/main/app/modules/inventory/router.py): `app/modules/inventory/router.py`
- [Stock adjustments](https://github.com/kiruiian/urban_liquor/blob/main/app/modules/inventory/router.py): `app/modules/inventory/router.py`
- [Checkout and sales](https://github.com/kiruiian/urban_liquor/blob/main/app/modules/sales/router.py): `app/modules/sales/router.py`
- [Sale history](https://github.com/kiruiian/urban_liquor/blob/main/app/modules/sales/router.py): `app/modules/sales/router.py`
- [Sales summaries](https://github.com/kiruiian/urban_liquor/blob/main/app/modules/sales/router.py): `app/modules/sales/router.py`

### Persistent state

- [Staff records](https://github.com/kiruiian/urban_liquor/blob/main/app/modules/auth/models.py): `app/modules/auth/models.py`
- [Products and movements](https://github.com/kiruiian/urban_liquor/blob/main/app/modules/inventory/models.py): `app/modules/inventory/models.py`
- [Sales and payments](https://github.com/kiruiian/urban_liquor/blob/main/app/modules/sales/models.py): `app/modules/sales/models.py`

### Other components

- **Staff user**

## Connections

- Staff user → POS interface: uses (evidence: `README.md`)
- POS interface → Staff authentication: signs in (evidence: `frontend/src/App.tsx`)
- POS interface → Product catalog: manages catalog (evidence: `README.md`)
- POS interface → Checkout and sales: checks out (evidence: `README.md`)
- POS interface → Sale history: reviews sales (evidence: `README.md`)
- POS interface → Sales summaries: views summaries (evidence: `README.md`)
- POS interface → Stock adjustments: adjusts stock (evidence: `README.md`)
- POS interface → Staff authentication: manages staff (evidence: `README.md`)
- API application → Staff authentication: registers route (evidence: `app/main.py`)
- API application → Product catalog: registers route (evidence: `app/main.py`)
- API application → Checkout and sales: registers route (evidence: `app/main.py`)
- Staff authentication → Token and role checks: checks access (evidence: `app/modules/auth/router.py`)
- Staff authentication → Credential and tokens: verifies and issues (evidence: `app/modules/auth/router.py`)
- Staff authentication → Database sessions: queries staff (evidence: `app/modules/auth/router.py`)
- Token and role checks → Credential and tokens: decodes token (evidence: `app/modules/auth/dependencies.py`)
- Token and role checks → Database sessions: loads staff (evidence: `app/modules/auth/dependencies.py`)
- Staff authentication → Staff records: reads and writes (evidence: `app/modules/auth/router.py`)
- Product catalog → Token and role checks: requires staff role (evidence: `app/modules/inventory/router.py`)
- Product catalog → Database sessions: queries catalog (evidence: `app/modules/inventory/router.py`)
- Product catalog → Products and movements: reads and writes (evidence: `app/modules/inventory/router.py`)
- Stock adjustments → Products and movements: records movement (evidence: `app/modules/inventory/router.py`)
- Checkout and sales → Token and role checks: requires staff (evidence: `app/modules/sales/router.py`)
- Checkout and sales → Database sessions: persists checkout (evidence: `app/modules/sales/router.py`)
- Checkout and sales → Products and movements: locks and updates stock (evidence: `app/modules/sales/router.py`)
- Checkout and sales → Sales and payments: records sale and tenders (evidence: `app/modules/sales/router.py`)
- Sale history → Database sessions: queries sales (evidence: `app/modules/sales/router.py`)
- Sale history → Sales and payments: reads transactions (evidence: `app/modules/sales/router.py`)
- Sales summaries → Database sessions: aggregates sales (evidence: `app/modules/sales/router.py`)
- Sales summaries → Sales and payments: reads payment totals (evidence: `app/modules/sales/router.py`)
- Database sessions → Application settings: loads database URL (evidence: `app/core/database.py`)