# mrzues/wings-theory architecture

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

- Interactive diagram: https://gitdiagram.com/mrzues/wings-theory
- Repository: https://github.com/mrzues/wings-theory

## Overview

Wings Theory is a restaurant inventory and POS backend. A cashier submits an order through the HTTP API; recipe expansion calculates ingredient needs, reservation holds stock, and kitchen start commits deductions to the ledger. The backend also supports receiving and expiry-aware stock, unlimited-dining sessions and reconciliation, verification queues, forecasting, anomaly detection, and association analysis. The README documents spreadsheet normalization and seeding as the route to initialize the operational data. The graph emphasizes documented flows and indexed module references; unsampled route details are not inferred.

Main entry points: [`backend/wt/api.py`](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/api.py) (HTTP API), [`backend/wt/reservation.py`](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/reservation.py) (Order Reservation), [`backend/wt/seed.py`](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/seed.py) (Spreadsheet Seeding), [`backend/wt/unli.py`](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/unli.py) (Unlimited Reconciliation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operations["POS Operations"]
  node_recipe["Recipe Expansion<br/>[resolver.py]"]
  node_reservation["Order Reservation<br/>[reservation.py]"]
  node_unli["Unlimited Reconciliation<br/>[unli.py]"]
  node_refills["Unlimited Refills<br/>[refills.py]"]
end

subgraph group_stock["Inventory Data"]
  node_units["Unit Conversion<br/>[units.py]"]
  node_mapping["Ingredient Mapping<br/>[mapping.py]"]
  node_gapfill["Recipe Gapfill<br/>[gapfill.py]"]
  node_seed["Spreadsheet Seeding<br/>[seed.py]"]
  node_rawimport["Raw CSV Import<br/>[raw_import.py]"]
end

subgraph group_insight["Analysis &amp; Controls"]
  node_verification["Verification Queue<br/>[verification.py]"]
  node_forecast["Forecasting<br/>[forecasting.py]"]
  node_anomaly["Anomaly Detection<br/>[anomaly.py]"]
  node_associations["Association Rules<br/>[associations.py]"]
end

subgraph group_platform["API &amp; Persistence"]
  node_http["HTTP API<br/>[api.py]"]
  node_database[("SQLite Database<br/>[db.py]")]
  node_auth["Role Authorization<br/>[auth.py]"]
end

node_cashier(("Cashier"))
node_kitchen(("Kitchen"))

node_cashier -->|"submits orders"| node_http
node_http -->|"resolves recipes"| node_recipe
node_http -->|"reserves stock"| node_reservation
node_kitchen -->|"starts orders"| node_http
node_http -->|"commits deductions"| node_reservation
node_http -->|"handles refills"| node_refills
node_http -->|"routes reconciliation"| node_unli
node_reservation -->|"expands needs"| node_recipe
node_reservation -->|"writes ledger"| node_database
node_refills -->|"uses stock logic"| node_reservation
node_unli -->|"corrects stock"| node_reservation
node_http -->|"checks capabilities"| node_auth
node_http -->|"serves verification"| node_verification
node_http -->|"exposes forecasts"| node_forecast
node_http -->|"exposes anomalies"| node_anomaly
node_http -->|"exposes analysis"| node_associations
node_seed -->|"loads data"| node_database
node_seed -->|"uses aliases"| node_mapping
node_seed -->|"fills recipe gaps"| node_gapfill
node_seed -->|"parses quantities"| node_units
node_rawimport -.->|"normalizes quantities"| node_units

click node_http "https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/api.py"
click node_recipe "https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/resolver.py"
click node_reservation "https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/reservation.py"
click node_unli "https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/unli.py"
click node_refills "https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/refills.py"
click node_database "https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/db.py"
click node_units "https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/units.py"
click node_mapping "https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/mapping.py"
click node_gapfill "https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/gapfill.py"
click node_seed "https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/seed.py"
click node_rawimport "https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/raw_import.py"
click node_verification "https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/verification.py"
click node_forecast "https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/forecasting.py"
click node_anomaly "https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/anomaly.py"
click node_associations "https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/associations.py"
click node_auth "https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/auth.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_recipe,node_reservation,node_unli,node_refills toneBlue
class node_units,node_mapping,node_gapfill,node_seed,node_rawimport toneAmber
class node_verification,node_forecast,node_anomaly,node_associations toneMint
class node_http,node_database,node_auth toneRose
class node_cashier,node_kitchen toneIndigo
```

## Components

### POS Operations

- [Recipe Expansion](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/resolver.py): `backend/wt/resolver.py`
- [Order Reservation](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/reservation.py): `backend/wt/reservation.py`
- [Unlimited Reconciliation](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/unli.py): `backend/wt/unli.py`
- [Unlimited Refills](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/refills.py): `backend/wt/refills.py`

### Inventory Data

- [Unit Conversion](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/units.py): `backend/wt/units.py`
- [Ingredient Mapping](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/mapping.py): `backend/wt/mapping.py`
- [Recipe Gapfill](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/gapfill.py): `backend/wt/gapfill.py`
- [Spreadsheet Seeding](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/seed.py): `backend/wt/seed.py`
- [Raw CSV Import](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/raw_import.py): `backend/wt/raw_import.py`

### Analysis & Controls

- [Verification Queue](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/verification.py): `backend/wt/verification.py`
- [Forecasting](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/forecasting.py): `backend/wt/forecasting.py`
- [Anomaly Detection](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/anomaly.py): `backend/wt/anomaly.py`
- [Association Rules](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/associations.py): `backend/wt/associations.py`

### API & Persistence

- [HTTP API](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/api.py): `backend/wt/api.py`
- [SQLite Database](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/db.py): `backend/wt/db.py`
- [Role Authorization](https://github.com/mrzues/wings-theory/blob/Wings-Theory/backend/wt/auth.py): `backend/wt/auth.py`

### Other components

- **Cashier**
- **Kitchen**

## Connections

- Cashier → HTTP API: submits orders (evidence: `README.md`)
- HTTP API → Recipe Expansion: resolves recipes (evidence: `backend/wt/api.py`)
- HTTP API → Order Reservation: reserves stock (evidence: `backend/wt/api.py`)
- Kitchen → HTTP API: starts orders (evidence: `backend/wt/api.py`)
- HTTP API → Order Reservation: commits deductions (evidence: `backend/wt/api.py`)
- HTTP API → Unlimited Refills: handles refills (evidence: `backend/wt/api.py`)
- HTTP API → Unlimited Reconciliation: routes reconciliation (evidence: `backend/wt/api.py`)
- Order Reservation → Recipe Expansion: expands needs (evidence: `backend/wt/reservation.py`)
- Order Reservation → SQLite Database: writes ledger (evidence: `README.md`)
- Unlimited Refills → Order Reservation: uses stock logic (evidence: `backend/wt/refills.py`)
- Unlimited Reconciliation → Order Reservation: corrects stock (evidence: `backend/wt/unli.py`)
- HTTP API → Role Authorization: checks capabilities (evidence: `backend/wt/api.py`)
- HTTP API → Verification Queue: serves verification (evidence: `backend/wt/api.py`)
- HTTP API → Forecasting: exposes forecasts (evidence: `backend/wt/api.py`)
- HTTP API → Anomaly Detection: exposes anomalies (evidence: `backend/wt/api.py`)
- HTTP API → Association Rules: exposes analysis (evidence: `backend/wt/api.py`)
- Spreadsheet Seeding → SQLite Database: loads data (evidence: `README.md`)
- Spreadsheet Seeding → Ingredient Mapping: uses aliases (evidence: `backend/wt/seed.py`)
- Spreadsheet Seeding → Recipe Gapfill: fills recipe gaps (evidence: `backend/wt/seed.py`)
- Spreadsheet Seeding → Unit Conversion: parses quantities (evidence: `backend/wt/seed.py`)
- Raw CSV Import → Unit Conversion: normalizes quantities