# kurmamadhav/automated-whatsapp-stationary-store architecture

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

- Interactive diagram: https://gitdiagram.com/kurmamadhav/automated-whatsapp-stationary-store
- Repository: https://github.com/kurmamadhav/automated-whatsapp-stationary-store

## Overview

This is a deterministic WhatsApp storefront for browsing stationery, maintaining a cart, and placing an order. The main path receives a Meta webhook, normalizes text or interactive replies, routes them through the finite-state engine, and returns WhatsApp payloads. The engine coordinates session state, catalog and order operations, message templates, and the WhatsApp client; checkout validates and deducts stock while creating a pending-payment order. The README also documents Redis-backed sessions and simulation interfaces. Some implementation excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`app/main.py`](https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/main.py) (FastAPI Webhook & API), [`app/engine.py`](https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/engine.py) (State Router), [`app/database.py`](https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/database.py) (Database Access), [`app/models.py`](https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/models.py) (Product & Order Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Ingress & Simulation"]
  node_main["FastAPI Webhook &amp; API<br/>[main.py]"]
  node_schemas["Message Schemas<br/>[schemas.py]"]
  node_cli["Terminal Simulator<br/>[simulate_cli.py]"]
end

subgraph group_commerce["Shopping Workflow"]
  node_engine["State Router<br/>[engine.py]"]
  node_catalog["Catalog &amp; Orders<br/>[catalog.py]"]
end

subgraph group_messaging["WhatsApp Messaging"]
  node_templates["Payload Builders"]
  node_client["WhatsApp Client<br/>[whatsapp_client.py]"]
end

subgraph group_persistence["State &amp; Persistence"]
  node_sessions["Session Manager<br/>[session.py]"]
  node_database["Database Access<br/>[database.py]"]
  node_models["Product &amp; Order Models<br/>[models.py]"]
  node_store[("Product &amp; Order Store")]
  node_seed["Catalog Seed Data<br/>[seed_data.py]"]
end

node_shopper(("Shopper"))
node_meta["Meta WhatsApp"]
node_sim_user(("Simulator User"))
node_redis[("Redis Session Store")]

node_shopper -->|"sends messages"| node_meta
node_meta -->|"posts webhook"| node_main
node_main -->|"normalizes messages"| node_schemas
node_main -->|"dispatches inbound"| node_engine
node_main -->|"gets DB session"| node_database
node_main -->|"queries products/orders"| node_models
node_main -->|"simulates message"| node_engine
node_sim_user -->|"uses simulation API"| node_main
node_sim_user -->|"chats in terminal"| node_cli
node_cli -->|"submits inbound"| node_engine
node_cli -->|"opens DB session"| node_database
node_cli -->|"seeds catalog"| node_seed
node_engine -->|"loads and saves state"| node_sessions
node_engine -->|"queries and places orders"| node_catalog
node_engine -->|"builds responses"| node_templates
node_engine -->|"sends payloads"| node_client
node_catalog -->|"queries and updates"| node_models
node_database -->|"creates tables"| node_models
node_database -->|"connects"| node_store
node_models -->|"persists products and orders"| node_store
node_seed -->|"initializes database"| node_database
node_seed -->|"inserts products"| node_models
node_sessions -.->|"persists sessions"| node_redis
node_client -->|"sends WhatsApp payloads"| node_meta

click node_main "https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/main.py"
click node_schemas "https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/schemas.py"
click node_cli "https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/simulate_cli.py"
click node_engine "https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/engine.py"
click node_catalog "https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/catalog.py"
click node_templates "https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/whatsapp_templates.py"
click node_client "https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/whatsapp_client.py"
click node_sessions "https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/session.py"
click node_database "https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/database.py"
click node_models "https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/models.py"
click node_seed "https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/seed_data.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_main,node_schemas,node_cli,node_sim_user toneBlue
class node_engine,node_catalog,node_redis toneAmber
class node_templates,node_client toneMint
class node_sessions,node_database,node_models,node_store,node_seed toneRose
class node_shopper,node_meta toneIndigo
```

## Components

### Ingress & Simulation

- [FastAPI Webhook & API](https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/main.py): `app/main.py`
- [Message Schemas](https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/schemas.py): `app/schemas.py`
- [Terminal Simulator](https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/simulate_cli.py): `simulate_cli.py`

### Shopping Workflow

- [State Router](https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/engine.py): `app/engine.py`
- [Catalog & Orders](https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/catalog.py): `app/catalog.py`

### WhatsApp Messaging

- [Payload Builders](https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/whatsapp_templates.py): `app/whatsapp_templates.py`
- [WhatsApp Client](https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/whatsapp_client.py): `app/whatsapp_client.py`

### State & Persistence

- [Session Manager](https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/session.py): `app/session.py`
- [Database Access](https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/database.py): `app/database.py`
- [Product & Order Models](https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/models.py): `app/models.py`
- **Product & Order Store**
- [Catalog Seed Data](https://github.com/kurmamadhav/automated-whatsapp-stationary-store/blob/main/app/seed_data.py): `app/seed_data.py`

### Other components

- **Shopper**
- **Meta WhatsApp**
- **Simulator User**
- **Redis Session Store**

## Connections

- Shopper → Meta WhatsApp: sends messages
- Meta WhatsApp → FastAPI Webhook & API: posts webhook
- FastAPI Webhook & API → Message Schemas: normalizes messages
- FastAPI Webhook & API → State Router: dispatches inbound
- FastAPI Webhook & API → Database Access: gets DB session
- FastAPI Webhook & API → Product & Order Models: queries products/orders
- FastAPI Webhook & API → State Router: simulates message
- Simulator User → FastAPI Webhook & API: uses simulation API
- Simulator User → Terminal Simulator: chats in terminal
- Terminal Simulator → State Router: submits inbound
- Terminal Simulator → Database Access: opens DB session
- Terminal Simulator → Catalog Seed Data: seeds catalog
- State Router → Session Manager: loads and saves state
- State Router → Catalog & Orders: queries and places orders
- State Router → Payload Builders: builds responses
- State Router → WhatsApp Client: sends payloads
- Catalog & Orders → Product & Order Models: queries and updates
- Database Access → Product & Order Models: creates tables
- Database Access → Product & Order Store: connects
- Product & Order Models → Product & Order Store: persists products and orders
- Catalog Seed Data → Database Access: initializes database
- Catalog Seed Data → Product & Order Models: inserts products
- Session Manager → Redis Session Store: persists sessions
- WhatsApp Client → Meta WhatsApp: sends WhatsApp payloads