# andreaunali/whatsorder-ai architecture

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

- Interactive diagram: https://gitdiagram.com/andreaunali/whatsorder-ai
- Repository: https://github.com/andreaunali/whatsorder-ai

## Overview

WhatsOrder AI converts customer WhatsApp messages into reviewed, structured daily orders and a kitchen prep PDF. The main flow is WhatsApp intake, Python message processing (including deterministic checks, recurring-order handling and AI parsing), catalog validation, SQLite persistence, and dashboard review or PDF output. Customer profiles and standing orders support both daily automatic orders and “usual” references. The README documents file-based handoffs; sampled source confirms several internal calls, but not every processing branch, so undocumented relationships are omitted.

Main entry points: [`processor.py`](https://github.com/andreaunali/whatsorder-ai/blob/main/processor.py) (Message processor), [`app.py`](https://github.com/andreaunali/whatsorder-ai/blob/main/app.py) (Order dashboard), [`whatsapp-listener.js`](https://github.com/andreaunali/whatsorder-ai/blob/main/whatsapp-listener.js) (WhatsApp listener), [`db.py`](https://github.com/andreaunali/whatsorder-ai/blob/main/db.py) (Orders database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["WhatsApp intake"]
  node_listener["WhatsApp listener"]
  node_inbox["Message inbox"]
  node_commands["Listener commands"]
end

subgraph group_processing["Order processing"]
  node_processor["Message processor<br/>[processor.py]"]
  node_whisper["Local transcription<br/>[processor.py]"]
  node_normalizer["Alias normalization<br/>[normalize.py]"]
  node_sanity["Order plausibility<br/>[sanity.py]"]
  node_orderparse["Order parsing<br/>[processor.py]"]
  node_recurring["Recurring orders<br/>[processor.py]"]
  node_validation["Catalog validation<br/>[processor.py]"]
end

subgraph group_operations["Order operations"]
  node_sqlite[("Orders database<br/>[db.py]")]
  node_customers["Customer profiles<br/>[db.py]"]
  node_standing["Standing orders<br/>[db.py]"]
end

subgraph group_presentation["Review and output"]
  node_dashboard["Order dashboard<br/>[app.py]"]
  node_review["Review queue<br/>[app.py]"]
  node_pdf["Kitchen prep PDF<br/>[pdf_generator.py]"]
end

node_customer(("Customer"))
node_groq{{"Groq LLM"}}
node_whatsapp{{"WhatsApp service"}}

node_customer -->|"sends message"| node_whatsapp
node_whatsapp -->|"delivers text, voice, photo"| node_listener
node_listener -->|"writes message files"| node_inbox
node_inbox -->|"reads messages"| node_processor
node_processor -->|"transcribes audio"| node_whisper
node_processor -->|"normalizes text"| node_normalizer
node_processor -->|"checks plausibility"| node_sanity
node_processor -->|"handles references"| node_recurring
node_processor -->|"parses messages"| node_orderparse
node_orderparse -->|"requests parse"| node_groq
node_processor -->|"validates parsed items"| node_validation
node_recurring -->|"loads base orders"| node_sqlite
node_validation -->|"saves validated orders"| node_sqlite
node_processor -->|"looks up customer"| node_sqlite
node_dashboard -->|"reads and updates orders"| node_sqlite
node_dashboard -->|"presents ambiguous orders"| node_review
node_dashboard -->|"creates today's orders"| node_standing
node_dashboard -->|"manages profiles"| node_customers
node_dashboard -->|"generates prep sheet"| node_pdf
node_dashboard -->|"writes broadcast or disconnect"| node_commands
node_commands -->|"polls commands"| node_listener
node_listener -->|"sends broadcast"| node_whatsapp

click node_listener "https://github.com/andreaunali/whatsorder-ai/blob/main/whatsapp-listener.js"
click node_processor "https://github.com/andreaunali/whatsorder-ai/blob/main/processor.py"
click node_whisper "https://github.com/andreaunali/whatsorder-ai/blob/main/processor.py"
click node_normalizer "https://github.com/andreaunali/whatsorder-ai/blob/main/normalize.py"
click node_sanity "https://github.com/andreaunali/whatsorder-ai/blob/main/sanity.py"
click node_orderparse "https://github.com/andreaunali/whatsorder-ai/blob/main/processor.py"
click node_recurring "https://github.com/andreaunali/whatsorder-ai/blob/main/processor.py"
click node_validation "https://github.com/andreaunali/whatsorder-ai/blob/main/processor.py"
click node_sqlite "https://github.com/andreaunali/whatsorder-ai/blob/main/db.py"
click node_customers "https://github.com/andreaunali/whatsorder-ai/blob/main/db.py"
click node_standing "https://github.com/andreaunali/whatsorder-ai/blob/main/db.py"
click node_dashboard "https://github.com/andreaunali/whatsorder-ai/blob/main/app.py"
click node_review "https://github.com/andreaunali/whatsorder-ai/blob/main/app.py"
click node_pdf "https://github.com/andreaunali/whatsorder-ai/blob/main/pdf_generator.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_listener,node_inbox,node_commands toneBlue
class node_processor,node_whisper,node_normalizer,node_sanity,node_orderparse,node_recurring,node_validation toneAmber
class node_sqlite,node_customers,node_standing toneMint
class node_dashboard,node_review,node_pdf toneRose
class node_customer,node_groq,node_whatsapp toneIndigo
```

## Components

### WhatsApp intake

- [WhatsApp listener](https://github.com/andreaunali/whatsorder-ai/blob/main/whatsapp-listener.js): `whatsapp-listener.js`
- **Message inbox**
- **Listener commands**

### Order processing

- [Message processor](https://github.com/andreaunali/whatsorder-ai/blob/main/processor.py): `processor.py`
- [Local transcription](https://github.com/andreaunali/whatsorder-ai/blob/main/processor.py): `processor.py`
- [Alias normalization](https://github.com/andreaunali/whatsorder-ai/blob/main/normalize.py): `normalize.py`
- [Order plausibility](https://github.com/andreaunali/whatsorder-ai/blob/main/sanity.py): `sanity.py`
- [Order parsing](https://github.com/andreaunali/whatsorder-ai/blob/main/processor.py): `processor.py`
- [Recurring orders](https://github.com/andreaunali/whatsorder-ai/blob/main/processor.py): `processor.py`
- [Catalog validation](https://github.com/andreaunali/whatsorder-ai/blob/main/processor.py): `processor.py`

### Order operations

- [Orders database](https://github.com/andreaunali/whatsorder-ai/blob/main/db.py): `db.py`
- [Customer profiles](https://github.com/andreaunali/whatsorder-ai/blob/main/db.py): `db.py`
- [Standing orders](https://github.com/andreaunali/whatsorder-ai/blob/main/db.py): `db.py`

### Review and output

- [Order dashboard](https://github.com/andreaunali/whatsorder-ai/blob/main/app.py): `app.py`
- [Review queue](https://github.com/andreaunali/whatsorder-ai/blob/main/app.py): `app.py`
- [Kitchen prep PDF](https://github.com/andreaunali/whatsorder-ai/blob/main/pdf_generator.py): `pdf_generator.py`

### Other components

- **Customer**
- **Groq LLM**
- **WhatsApp service**

## Connections

- Customer → WhatsApp service: sends message (evidence: `README.md`)
- WhatsApp service → WhatsApp listener: delivers text, voice, photo (evidence: `README.md`)
- WhatsApp listener → Message inbox: writes message files (evidence: `README.md`)
- Message inbox → Message processor: reads messages (evidence: `README.md`)
- Message processor → Local transcription: transcribes audio (evidence: `README.md`)
- Message processor → Alias normalization: normalizes text (evidence: `processor.py`)
- Message processor → Order plausibility: checks plausibility (evidence: `processor.py`)
- Message processor → Recurring orders: handles references (evidence: `README.md`)
- Message processor → Order parsing: parses messages (evidence: `README.md`)
- Order parsing → Groq LLM: requests parse (evidence: `processor.py`)
- Message processor → Catalog validation: validates parsed items (evidence: `processor.py`)
- Recurring orders → Orders database: loads base orders (evidence: `README.md`)
- Catalog validation → Orders database: saves validated orders (evidence: `README.md`)
- Message processor → Orders database: looks up customer (evidence: `processor.py`)
- Order dashboard → Orders database: reads and updates orders (evidence: `app.py`)
- Order dashboard → Review queue: presents ambiguous orders (evidence: `README.md`)
- Order dashboard → Standing orders: creates today's orders (evidence: `app.py`)
- Order dashboard → Customer profiles: manages profiles (evidence: `app.py`)
- Order dashboard → Kitchen prep PDF: generates prep sheet (evidence: `app.py`)
- Order dashboard → Listener commands: writes broadcast or disconnect (evidence: `README.md`)
- Listener commands → WhatsApp listener: polls commands (evidence: `README.md`)
- WhatsApp listener → WhatsApp service: sends broadcast (evidence: `whatsapp-listener.js`)
