# angx7/stockcito architecture

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

- Interactive diagram: https://gitdiagram.com/angx7/stockcito
- Repository: https://github.com/angx7/stockcito

## Overview

Abasto is a local CLI for turning pasted text or WhatsApp-exported TXT into inventory entries, warehouse exits, and pending purchase requests, then reviewing stock and generating reports. The main workflow parses messages into typed items, optionally filters noisy missing-item messages with OpenAI, and records the results through inventory and catalog services. README-documented capabilities also include low-stock purchase suggestions and operational dashboards. Some service implementations were not excerpted, so those links are included only where the README or source index supports them.

Main entry points: [`app.py`](https://github.com/angx7/stockcito/blob/master/app.py) (CLI commands), [`abasto/services/inventory_service.py`](https://github.com/angx7/stockcito/blob/master/abasto/services/inventory_service.py) (Inventory service), [`abasto/parsers/whatsapp_parser.py`](https://github.com/angx7/stockcito/blob/master/abasto/parsers/whatsapp_parser.py) (WhatsApp export parser), [`abasto/services/catalog_service.py`](https://github.com/angx7/stockcito/blob/master/abasto/services/catalog_service.py) (Product catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_cli["CLI commands<br/>[app.py]"]
end

subgraph group_parsing["Message parsing"]
  node_whatsapp["WhatsApp export parser<br/>[whatsapp_parser.py]"]
  node_entry_parser["Entry parser"]
  node_exit_parser["Exit parser<br/>[exits_parser.py]"]
  node_missing_parser["Missing parser<br/>[missing_parser.py]"]
  node_quantity_parser["Quantity parser<br/>[base.py]"]
  node_parsed_schema["Parsed item schema<br/>[schemas.py]"]
  node_text_utils["Text normalization<br/>[text.py]"]
end

subgraph group_operations["Inventory operations"]
  node_ai_filter["AI missing filter<br/>[openai_service.py]"]
  node_inventory_service["Inventory service"]
  node_catalog_service["Product catalog<br/>[catalog_service.py]"]
  node_reconciliation["Reconciliation"]
  node_report_service["Dashboard reporting<br/>[report_service.py]"]
end

subgraph group_data["Data and reporting"]
  node_db[("SQLite session and schema<br/>[db.py]")]
  node_product["Products and aliases<br/>[product.py]"]
  node_alias["Product aliases<br/>[alias.py]"]
  node_movement["Stock movements<br/>[movement.py]"]
  node_purchase["Purchase requests"]
  node_supplier["Suppliers<br/>[supplier.py]"]
  node_category["Categories<br/>[category.py]"]
end

node_operator(("Restaurant operator"))
node_openai["OpenAI API"]

node_operator -->|"runs commands"| node_cli
node_cli -->|"parses imports"| node_whatsapp
node_cli -->|"filters missing text"| node_ai_filter
node_cli -->|"records parsed items"| node_inventory_service
node_cli -->|"builds dashboard"| node_report_service
node_cli -->|"requests AI report"| node_ai_filter
node_cli -->|"requests stock views"| node_inventory_service
node_whatsapp -->|"dispatches entries"| node_entry_parser
node_whatsapp -->|"dispatches exits"| node_exit_parser
node_whatsapp -->|"dispatches missing"| node_missing_parser
node_entry_parser -->|"parses quantities"| node_quantity_parser
node_exit_parser -->|"parses quantities"| node_quantity_parser
node_missing_parser -->|"parses candidates"| node_quantity_parser
node_missing_parser -->|"cleans names"| node_text_utils
node_quantity_parser -->|"normalizes values"| node_text_utils
node_entry_parser -.->|"returns parsed items"| node_parsed_schema
node_exit_parser -->|"returns parsed items"| node_parsed_schema
node_missing_parser -->|"returns parsed items"| node_parsed_schema
node_whatsapp -->|"returns parsed items"| node_parsed_schema
node_ai_filter -->|"returns parsed items"| node_parsed_schema
node_ai_filter -->|"calls Responses API"| node_openai
node_inventory_service -->|"resolves products"| node_catalog_service
node_inventory_service -->|"records movements"| node_movement
node_inventory_service -->|"records requests"| node_purchase
node_catalog_service -->|"matches products"| node_product
node_catalog_service -->|"reads and adds aliases"| node_alias
node_catalog_service -->|"creates suppliers"| node_supplier
node_catalog_service -->|"creates categories"| node_category
node_reconciliation -->|"uses inventory"| node_inventory_service
node_report_service -->|"reads inventory"| node_inventory_service
node_report_service -.->|"reads requests"| node_purchase
node_cli -->|"suggests low stock"| node_inventory_service
node_cli -->|"shows dashboard"| node_report_service
node_cli -->|"generates AI report"| node_ai_filter
node_db -->|"maps models"| node_product
node_db -->|"maps models"| node_movement
node_db -->|"maps models"| node_purchase

click node_cli "https://github.com/angx7/stockcito/blob/master/app.py"
click node_whatsapp "https://github.com/angx7/stockcito/blob/master/abasto/parsers/whatsapp_parser.py"
click node_entry_parser "https://github.com/angx7/stockcito/blob/master/abasto/parsers/inventory_parser.py"
click node_exit_parser "https://github.com/angx7/stockcito/blob/master/abasto/parsers/exits_parser.py"
click node_missing_parser "https://github.com/angx7/stockcito/blob/master/abasto/parsers/missing_parser.py"
click node_quantity_parser "https://github.com/angx7/stockcito/blob/master/abasto/parsers/base.py"
click node_parsed_schema "https://github.com/angx7/stockcito/blob/master/abasto/parsers/schemas.py"
click node_text_utils "https://github.com/angx7/stockcito/blob/master/abasto/parsers/text.py"
click node_ai_filter "https://github.com/angx7/stockcito/blob/master/abasto/services/openai_service.py"
click node_inventory_service "https://github.com/angx7/stockcito/blob/master/abasto/services/inventory_service.py"
click node_catalog_service "https://github.com/angx7/stockcito/blob/master/abasto/services/catalog_service.py"
click node_reconciliation "https://github.com/angx7/stockcito/blob/master/abasto/services/reconciliation_service.py"
click node_report_service "https://github.com/angx7/stockcito/blob/master/abasto/services/report_service.py"
click node_db "https://github.com/angx7/stockcito/blob/master/abasto/database/db.py"
click node_product "https://github.com/angx7/stockcito/blob/master/abasto/models/product.py"
click node_alias "https://github.com/angx7/stockcito/blob/master/abasto/models/alias.py"
click node_movement "https://github.com/angx7/stockcito/blob/master/abasto/models/movement.py"
click node_purchase "https://github.com/angx7/stockcito/blob/master/abasto/models/purchase_request.py"
click node_supplier "https://github.com/angx7/stockcito/blob/master/abasto/models/supplier.py"
click node_category "https://github.com/angx7/stockcito/blob/master/abasto/models/category.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_cli toneBlue
class node_whatsapp,node_entry_parser,node_exit_parser,node_missing_parser,node_quantity_parser,node_parsed_schema,node_text_utils toneAmber
class node_ai_filter,node_inventory_service,node_catalog_service,node_reconciliation,node_report_service,node_openai toneMint
class node_db,node_product,node_alias,node_movement,node_purchase,node_supplier,node_category toneRose
class node_operator toneIndigo
```

## Components

### CLI workflows

- [CLI commands](https://github.com/angx7/stockcito/blob/master/app.py): `app.py`

### Message parsing

- [WhatsApp export parser](https://github.com/angx7/stockcito/blob/master/abasto/parsers/whatsapp_parser.py): `abasto/parsers/whatsapp_parser.py`
- [Entry parser](https://github.com/angx7/stockcito/blob/master/abasto/parsers/inventory_parser.py): `abasto/parsers/inventory_parser.py`
- [Exit parser](https://github.com/angx7/stockcito/blob/master/abasto/parsers/exits_parser.py): `abasto/parsers/exits_parser.py`
- [Missing parser](https://github.com/angx7/stockcito/blob/master/abasto/parsers/missing_parser.py): `abasto/parsers/missing_parser.py`
- [Quantity parser](https://github.com/angx7/stockcito/blob/master/abasto/parsers/base.py): `abasto/parsers/base.py`
- [Parsed item schema](https://github.com/angx7/stockcito/blob/master/abasto/parsers/schemas.py): `abasto/parsers/schemas.py`
- [Text normalization](https://github.com/angx7/stockcito/blob/master/abasto/parsers/text.py): `abasto/parsers/text.py`

### Inventory operations

- [AI missing filter](https://github.com/angx7/stockcito/blob/master/abasto/services/openai_service.py): `abasto/services/openai_service.py`
- [Inventory service](https://github.com/angx7/stockcito/blob/master/abasto/services/inventory_service.py): `abasto/services/inventory_service.py`
- [Product catalog](https://github.com/angx7/stockcito/blob/master/abasto/services/catalog_service.py): `abasto/services/catalog_service.py`
- [Reconciliation](https://github.com/angx7/stockcito/blob/master/abasto/services/reconciliation_service.py): `abasto/services/reconciliation_service.py`
- [Dashboard reporting](https://github.com/angx7/stockcito/blob/master/abasto/services/report_service.py): `abasto/services/report_service.py`

### Data and reporting

- [SQLite session and schema](https://github.com/angx7/stockcito/blob/master/abasto/database/db.py): `abasto/database/db.py`
- [Products and aliases](https://github.com/angx7/stockcito/blob/master/abasto/models/product.py): `abasto/models/product.py`
- [Product aliases](https://github.com/angx7/stockcito/blob/master/abasto/models/alias.py): `abasto/models/alias.py`
- [Stock movements](https://github.com/angx7/stockcito/blob/master/abasto/models/movement.py): `abasto/models/movement.py`
- [Purchase requests](https://github.com/angx7/stockcito/blob/master/abasto/models/purchase_request.py): `abasto/models/purchase_request.py`
- [Suppliers](https://github.com/angx7/stockcito/blob/master/abasto/models/supplier.py): `abasto/models/supplier.py`
- [Categories](https://github.com/angx7/stockcito/blob/master/abasto/models/category.py): `abasto/models/category.py`

### Other components

- **Restaurant operator**
- **OpenAI API**

## Connections

- Restaurant operator → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → WhatsApp export parser: parses imports (evidence: `app.py`)
- CLI commands → AI missing filter: filters missing text (evidence: `app.py`)
- CLI commands → Inventory service: records parsed items (evidence: `app.py`)
- CLI commands → Dashboard reporting: builds dashboard (evidence: `app.py`)
- CLI commands → AI missing filter: requests AI report (evidence: `app.py`)
- CLI commands → Inventory service: requests stock views (evidence: `app.py`)
- WhatsApp export parser → Entry parser: dispatches entries (evidence: `abasto/parsers/whatsapp_parser.py`)
- WhatsApp export parser → Exit parser: dispatches exits (evidence: `abasto/parsers/whatsapp_parser.py`)
- WhatsApp export parser → Missing parser: dispatches missing (evidence: `abasto/parsers/whatsapp_parser.py`)
- Entry parser → Quantity parser: parses quantities (evidence: `abasto/parsers/inventory_parser.py`)
- Exit parser → Quantity parser: parses quantities (evidence: `abasto/parsers/exits_parser.py`)
- Missing parser → Quantity parser: parses candidates (evidence: `abasto/parsers/missing_parser.py`)
- Missing parser → Text normalization: cleans names (evidence: `abasto/parsers/missing_parser.py`)
- Quantity parser → Text normalization: normalizes values (evidence: `abasto/parsers/base.py`)
- Entry parser → Parsed item schema: returns parsed items (evidence: `abasto/parsers/inventory_parser.py`)
- Exit parser → Parsed item schema: returns parsed items (evidence: `abasto/parsers/exits_parser.py`)
- Missing parser → Parsed item schema: returns parsed items (evidence: `abasto/parsers/missing_parser.py`)
- WhatsApp export parser → Parsed item schema: returns parsed items (evidence: `abasto/parsers/whatsapp_parser.py`)
- AI missing filter → Parsed item schema: returns parsed items (evidence: `abasto/services/openai_service.py`)
- AI missing filter → OpenAI API: calls Responses API (evidence: `abasto/services/openai_service.py`)
- Inventory service → Product catalog: resolves products (evidence: `abasto/services/inventory_service.py`)
- Inventory service → Stock movements: records movements (evidence: `abasto/services/inventory_service.py`)
- Inventory service → Purchase requests: records requests (evidence: `abasto/services/inventory_service.py`)
- Product catalog → Products and aliases: matches products (evidence: `abasto/services/catalog_service.py`)
- Product catalog → Product aliases: reads and adds aliases (evidence: `abasto/services/catalog_service.py`)
- Product catalog → Suppliers: creates suppliers (evidence: `abasto/services/catalog_service.py`)
- Product catalog → Categories: creates categories (evidence: `abasto/services/catalog_service.py`)
- Reconciliation → Inventory service: uses inventory (evidence: `abasto/services/reconciliation_service.py`)
- Dashboard reporting → Inventory service: reads inventory (evidence: `abasto/services/report_service.py`)
- Dashboard reporting → Purchase requests: reads requests
- CLI commands → Inventory service: suggests low stock (evidence: `README.md`)
- CLI commands → Dashboard reporting: shows dashboard (evidence: `README.md`)
- CLI commands → AI missing filter: generates AI report (evidence: `app.py`)
- SQLite session and schema → Products and aliases: maps models (evidence: `abasto/database/db.py`)
- SQLite session and schema → Stock movements: maps models (evidence: `abasto/database/db.py`)
- SQLite session and schema → Purchase requests: maps models (evidence: `abasto/database/db.py`)
