# ugbodagadave/isabella architecture

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

- Interactive diagram: https://gitdiagram.com/ugbodagadave/isabella
- Repository: https://github.com/ugbodagadave/isabella

## Overview

Isabella is a Slack-based bookkeeping agent for accountants. Its main workflow accepts receipt images or PDFs in Slack, extracts and structures expense details, and appends them to Google Sheets; users can also ask natural-language questions and receive financial summaries in Slack. The graph separates intake/orchestration, extraction and AI, query analysis, and spreadsheet storage. The runner’s wiring and several component calls are visible in sampled source; Slack event handling and some controller behavior are represented only by README statements and the source index.

Main entry points: [`tools/controller.py`](https://github.com/ugbodagadave/isabella/blob/main/tools/controller.py) (Workflow Controller), [`tools/slack_socket_runner.py`](https://github.com/ugbodagadave/isabella/blob/main/tools/slack_socket_runner.py) (Socket Runner), [`tools/slack_interface.py`](https://github.com/ugbodagadave/isabella/blob/main/tools/slack_interface.py) (Slack Interface), [`models/granite_client.py`](https://github.com/ugbodagadave/isabella/blob/main/models/granite_client.py) (Granite Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Slack Intake"]
  node_runner["Socket Runner"]
  node_interface["Slack Interface<br/>[slack_interface.py]"]
  node_controller["Workflow Controller<br/>[controller.py]"]
  node_settings["Runtime Settings<br/>[settings.py]"]
end

subgraph group_processing["Receipt Processing"]
  node_extractor["Text Extractor<br/>[text_extractor.py]"]
  node_vision["Vision Client<br/>[vision_client.py]"]
  node_receipt["Receipt Processor"]
  node_granite["Granite Client<br/>[granite_client.py]"]
  node_receipt_schema["Receipt Schema"]
  node_prompts["AI Prompts<br/>[prompts.py]"]
end

subgraph group_analysis["Expense Analysis"]
  node_analyzer["Query Analyzer<br/>[query_analyzer.py]"]
end

subgraph group_storage["Financial Records"]
  node_sheets_manager["Sheets Manager<br/>[sheets_manager.py]"]
  node_sheets_client["Google Sheets Client"]
  node_sheets[("Expense Spreadsheet")]
end

node_accountant(("Accountant"))
node_slack["Slack"]
node_watsonx["IBM watsonx"]

node_accountant -->|"uploads or asks"| node_slack
node_slack -->|"delivers events"| node_interface
node_interface -.->|"routes requests"| node_controller
node_controller -->|"extracts text"| node_extractor
node_extractor -->|"transcribes images"| node_vision
node_controller -->|"processes receipt"| node_receipt
node_receipt -->|"generates structured data"| node_granite
node_receipt -->|"validates against"| node_receipt_schema
node_controller -->|"stores expenses"| node_sheets_manager
node_sheets_manager -->|"appends and queries"| node_sheets_client
node_sheets_client -->|"reads and writes"| node_sheets
node_controller -->|"plans queries"| node_analyzer
node_analyzer -.->|"uses model"| node_granite
node_controller -->|"fetches expense rows"| node_sheets_manager
node_controller -->|"returns reports"| node_interface
node_interface -->|"posts results"| node_slack
node_runner -->|"wires components"| node_controller
node_runner -->|"starts interface"| node_interface
node_runner -->|"loads configuration"| node_settings
node_runner -->|"connects client"| node_sheets_client
node_runner -->|"creates client"| node_granite
node_watsonx -->|"serves text generation"| node_granite
node_watsonx -->|"serves vision inference"| node_vision

click node_runner "https://github.com/ugbodagadave/isabella/blob/main/tools/slack_socket_runner.py"
click node_interface "https://github.com/ugbodagadave/isabella/blob/main/tools/slack_interface.py"
click node_controller "https://github.com/ugbodagadave/isabella/blob/main/tools/controller.py"
click node_extractor "https://github.com/ugbodagadave/isabella/blob/main/tools/text_extractor.py"
click node_vision "https://github.com/ugbodagadave/isabella/blob/main/models/vision_client.py"
click node_receipt "https://github.com/ugbodagadave/isabella/blob/main/tools/receipt_processor.py"
click node_granite "https://github.com/ugbodagadave/isabella/blob/main/models/granite_client.py"
click node_receipt_schema "https://github.com/ugbodagadave/isabella/blob/main/data/schemas/receipt_schema.json"
click node_prompts "https://github.com/ugbodagadave/isabella/blob/main/config/prompts.py"
click node_analyzer "https://github.com/ugbodagadave/isabella/blob/main/tools/query_analyzer.py"
click node_sheets_manager "https://github.com/ugbodagadave/isabella/blob/main/tools/sheets_manager.py"
click node_sheets_client "https://github.com/ugbodagadave/isabella/blob/main/integrations/google_sheets_api.py"
click node_settings "https://github.com/ugbodagadave/isabella/blob/main/config/settings.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_runner,node_interface,node_controller,node_settings toneBlue
class node_extractor,node_vision,node_receipt,node_granite,node_receipt_schema,node_prompts toneAmber
class node_analyzer toneMint
class node_sheets_manager,node_sheets_client,node_sheets toneRose
class node_accountant,node_slack,node_watsonx toneIndigo
```

## Components

### Slack Intake

- [Socket Runner](https://github.com/ugbodagadave/isabella/blob/main/tools/slack_socket_runner.py): `tools/slack_socket_runner.py`
- [Slack Interface](https://github.com/ugbodagadave/isabella/blob/main/tools/slack_interface.py): `tools/slack_interface.py`
- [Workflow Controller](https://github.com/ugbodagadave/isabella/blob/main/tools/controller.py): `tools/controller.py`
- [Runtime Settings](https://github.com/ugbodagadave/isabella/blob/main/config/settings.py): `config/settings.py`

### Receipt Processing

- [Text Extractor](https://github.com/ugbodagadave/isabella/blob/main/tools/text_extractor.py): `tools/text_extractor.py`
- [Vision Client](https://github.com/ugbodagadave/isabella/blob/main/models/vision_client.py): `models/vision_client.py`
- [Receipt Processor](https://github.com/ugbodagadave/isabella/blob/main/tools/receipt_processor.py): `tools/receipt_processor.py`
- [Granite Client](https://github.com/ugbodagadave/isabella/blob/main/models/granite_client.py): `models/granite_client.py`
- [Receipt Schema](https://github.com/ugbodagadave/isabella/blob/main/data/schemas/receipt_schema.json): `data/schemas/receipt_schema.json`
- [AI Prompts](https://github.com/ugbodagadave/isabella/blob/main/config/prompts.py): `config/prompts.py`

### Expense Analysis

- [Query Analyzer](https://github.com/ugbodagadave/isabella/blob/main/tools/query_analyzer.py): `tools/query_analyzer.py`

### Financial Records

- [Sheets Manager](https://github.com/ugbodagadave/isabella/blob/main/tools/sheets_manager.py): `tools/sheets_manager.py`
- [Google Sheets Client](https://github.com/ugbodagadave/isabella/blob/main/integrations/google_sheets_api.py): `integrations/google_sheets_api.py`
- **Expense Spreadsheet**

### Other components

- **Accountant**
- **Slack**
- **IBM watsonx**

## Connections

- Accountant → Slack: uploads or asks (evidence: `README.md`)
- Slack → Slack Interface: delivers events (evidence: `README.md`)
- Slack Interface → Workflow Controller: routes requests
- Workflow Controller → Text Extractor: extracts text (evidence: `tools/controller.py`)
- Text Extractor → Vision Client: transcribes images (evidence: `tools/text_extractor.py`)
- Workflow Controller → Receipt Processor: processes receipt (evidence: `tools/controller.py`)
- Receipt Processor → Granite Client: generates structured data (evidence: `tools/receipt_processor.py`)
- Receipt Processor → Receipt Schema: validates against (evidence: `tools/receipt_processor.py`)
- Workflow Controller → Sheets Manager: stores expenses (evidence: `tools/controller.py`)
- Sheets Manager → Google Sheets Client: appends and queries (evidence: `tools/sheets_manager.py`)
- Google Sheets Client → Expense Spreadsheet: reads and writes (evidence: `integrations/google_sheets_api.py`)
- Workflow Controller → Query Analyzer: plans queries (evidence: `tools/controller.py`)
- Query Analyzer → Granite Client: uses model
- Workflow Controller → Sheets Manager: fetches expense rows (evidence: `tools/controller.py`)
- Workflow Controller → Slack Interface: returns reports (evidence: `README.md`)
- Slack Interface → Slack: posts results (evidence: `README.md`)
- Socket Runner → Workflow Controller: wires components (evidence: `tools/slack_socket_runner.py`)
- Socket Runner → Slack Interface: starts interface (evidence: `tools/slack_socket_runner.py`)
- Socket Runner → Runtime Settings: loads configuration (evidence: `tools/slack_socket_runner.py`)
- Socket Runner → Google Sheets Client: connects client (evidence: `tools/slack_socket_runner.py`)
- Socket Runner → Granite Client: creates client (evidence: `tools/slack_socket_runner.py`)
- IBM watsonx → Granite Client: serves text generation (evidence: `models/granite_client.py`)
- IBM watsonx → Vision Client: serves vision inference (evidence: `models/vision_client.py`)
