# chlorinexxe/billing_app architecture

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

- Interactive diagram: https://gitdiagram.com/chlorinexxe/billing_app
- Repository: https://github.com/chlorinexxe/billing_app

## Overview

#### Purpose and entry point
This is a Python business-management application centered on products, suppliers, customers, billing, and dashboard statistics. `app.py` is the likely application bootstrap; domain persistence is defined in `models.py` and database setup in `database.py`.

#### Application composition
The codebase is organized as a layered desktop-style UI and service application rather than a web service:
- Application bootstrap: `app.py`
- Persistence/domain models: `models.py`, `database.py`
- Business calculations and statistics: `calculations.py`, `services/stats_service.py`
- UI screens and reusable components: `ui/dashboard.py`, `ui/products.py`, `ui/components/card.py`

#### Persistence and schema evolution
`database.py` provides the database boundary used by the rest of the application, while `models.py` represents persistent business entities. Alembic manages schema evolution:
- `alembic/env.py`
- `alembic/versions/39f2eefc5ca6_added_state_in_the_supplier_and_customer.py`

The migration indicates supplier and customer records include a persisted state field. UI and services should access storage through the shared database/model layer rather than embedding schema-specific logic.

#### Product and party management
Product management is exposed through `ui/products.py`, with product creation/editing likely handled by `ui/add_product_dialogue.py`. Domain-oriented UI asset modules separate representations or access patterns for core records:
- `ui/assets/products.py`
- `ui/assets/customers.py`
- `ui/assets/suppliers.py`

These areas form the input side of billing: maintain catalog items and the customer/supplier identities used by invoices.

#### Bill-generation workflow
Invoice generation is a distinct feature module under `ui/generate_bill/`. `ui/generate_bill/page.py` likely orchestrates the workflow, composing independently focused sections:
- Supplier selection/details: `ui/generate_bill/supplier_section.py`
- Customer selection/details: `ui/generate_bill/customer_section.py`
- Line-item entry: `ui/generate_bill/product_table.py`
- Amount summary: `ui/generate_bill/totals_section.py`

`ui/generate_bill/bill_service.py` is the important boundary between UI state and bill persistence/business actions. It should own bill creation/finalization rather than allowing individual sections to write directly to storage.

#### Calculation and dashboard flow
Line-item and aggregate financial logic is centralized in `calculations.py`; the bill totals UI should consume this logic instead of reimplementing arithmetic. Dashboard-facing aggregation is separated into `services/stats_service.py`, which supplies data to `ui/dashboard.py`. The primary flow is therefore: persisted products/parties → bill form and line items → calculations and bill service → persisted bill data → statistics service → dashboard cards.

#### Runtime and external dependencies
The repository is Python-based, with dependencies declared in `requirements.txt`. Database migrations use Alembic (`alembic.ini`, `alembic/`). No external network service, API integration, deployment platform, or web-server boundary is evident from the supplied tree.

Main entry points: [`models.py`](https://github.com/chlorinexxe/billing_app/blob/main/models.py) (Business Models), [`ui/generate_bill/page.py`](https://github.com/chlorinexxe/billing_app/blob/main/ui/generate_bill/page.py) (Generate Bill), [`app.py`](https://github.com/chlorinexxe/billing_app/blob/main/app.py) (Application Bootstrap), [`ui/dashboard.py`](https://github.com/chlorinexxe/billing_app/blob/main/ui/dashboard.py) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop UI"]
  node_dashboard["Dashboard<br/>UI screen<br/>[dashboard.py]"]
  node_products_ui["Product Management<br/>UI screen<br/>[products.py]"]
  node_add_product["Add Product Dialog<br/>UI dialog"]
  node_card["Dashboard Card<br/>UI component<br/>[card.py]"]
  node_product_assets["Product UI Assets<br/>UI data module<br/>[products.py]"]
  node_customer_assets["Customer UI Assets<br/>UI data module<br/>[customers.py]"]
  node_supplier_assets["Supplier UI Assets<br/>UI data module<br/>[suppliers.py]"]
end

subgraph group_billing["Billing Workflow"]
  node_bill_page["Generate Bill<br/>Workflow page<br/>[page.py]"]
  node_party_sections["Supplier &amp; Customer Sections<br/>Bill form sections"]
  node_product_table["Line Item Table<br/>Bill form section<br/>[product_table.py]"]
  node_totals_section["Totals Section<br/>Bill form section<br/>[totals_section.py]"]
  node_bill_service["Bill Service<br/>Business service<br/>[bill_service.py]"]
  node_calculations["Financial Calculations<br/>Calculation module<br/>[calculations.py]"]
end

subgraph group_domain["Domain &amp; Data"]
  node_models[("Business Models<br/>Persistence models<br/>[models.py]")]
  node_database[("Database Setup<br/>Database boundary<br/>[database.py]")]
end

subgraph group_analytics["Analytics"]
  node_stats_service["Statistics Service<br/>Analytics service<br/>[stats_service.py]"]
end

subgraph group_migrations["Schema Evolution"]
  node_alembic_env["Alembic Environment<br/>Migration runner<br/>[env.py]"]
  node_state_migration["Party State Migration<br/>Schema migration"]
end

node_app{{"Application Bootstrap<br/>Python entry point<br/>[app.py]"}}

node_app -->|"launches"| node_dashboard
node_app -->|"launches"| node_products_ui
node_app -->|"launches"| node_bill_page
node_products_ui -->|"opens"| node_add_product
node_products_ui -->|"uses"| node_product_assets
node_product_assets -->|"accesses"| node_models
node_customer_assets -->|"accesses"| node_models
node_supplier_assets -->|"accesses"| node_models
node_bill_page -->|"composes"| node_party_sections
node_bill_page -->|"composes"| node_product_table
node_bill_page -->|"composes"| node_totals_section
node_party_sections -->|"selects customers"| node_customer_assets
node_party_sections -->|"selects suppliers"| node_supplier_assets
node_product_table -->|"selects products"| node_product_assets
node_totals_section -->|"calculates totals"| node_calculations
node_bill_page -->|"submits bill"| node_bill_service
node_bill_service -->|"uses"| node_calculations
node_bill_service -->|"persists bills"| node_models
node_models -->|"stored through"| node_database
node_stats_service -->|"aggregates persisted data"| node_models
node_dashboard -->|"requests statistics"| node_stats_service
node_dashboard -->|"renders"| node_card
node_alembic_env -->|"runs"| node_state_migration
node_state_migration -.->|"evolves schema for"| node_models
node_alembic_env -->|"migrates"| node_database

click node_app "https://github.com/chlorinexxe/billing_app/blob/main/app.py"
click node_dashboard "https://github.com/chlorinexxe/billing_app/blob/main/ui/dashboard.py"
click node_products_ui "https://github.com/chlorinexxe/billing_app/blob/main/ui/products.py"
click node_add_product "https://github.com/chlorinexxe/billing_app/blob/main/ui/add_product_dialogue.py"
click node_card "https://github.com/chlorinexxe/billing_app/blob/main/ui/components/card.py"
click node_product_assets "https://github.com/chlorinexxe/billing_app/blob/main/ui/assets/products.py"
click node_customer_assets "https://github.com/chlorinexxe/billing_app/blob/main/ui/assets/customers.py"
click node_supplier_assets "https://github.com/chlorinexxe/billing_app/blob/main/ui/assets/suppliers.py"
click node_bill_page "https://github.com/chlorinexxe/billing_app/blob/main/ui/generate_bill/page.py"
click node_product_table "https://github.com/chlorinexxe/billing_app/blob/main/ui/generate_bill/product_table.py"
click node_totals_section "https://github.com/chlorinexxe/billing_app/blob/main/ui/generate_bill/totals_section.py"
click node_bill_service "https://github.com/chlorinexxe/billing_app/blob/main/ui/generate_bill/bill_service.py"
click node_calculations "https://github.com/chlorinexxe/billing_app/blob/main/calculations.py"
click node_models "https://github.com/chlorinexxe/billing_app/blob/main/models.py"
click node_database "https://github.com/chlorinexxe/billing_app/blob/main/database.py"
click node_stats_service "https://github.com/chlorinexxe/billing_app/blob/main/services/stats_service.py"
click node_alembic_env "https://github.com/chlorinexxe/billing_app/blob/main/alembic/env.py"
click node_state_migration "https://github.com/chlorinexxe/billing_app/blob/main/alembic/versions/39f2eefc5ca6_added_state_in_the_supplier_and_customer.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_dashboard,node_products_ui,node_add_product,node_card,node_product_assets,node_customer_assets,node_supplier_assets toneBlue
class node_bill_page,node_party_sections,node_product_table,node_totals_section,node_bill_service,node_calculations toneAmber
class node_models,node_database toneMint
class node_stats_service toneRose
class node_alembic_env,node_state_migration toneIndigo
class node_app toneNeutral
```

## Components

### Desktop UI

- [Dashboard](https://github.com/chlorinexxe/billing_app/blob/main/ui/dashboard.py): UI screen · `ui/dashboard.py`
- [Product Management](https://github.com/chlorinexxe/billing_app/blob/main/ui/products.py): UI screen · `ui/products.py`
- [Add Product Dialog](https://github.com/chlorinexxe/billing_app/blob/main/ui/add_product_dialogue.py): UI dialog · `ui/add_product_dialogue.py`
- [Dashboard Card](https://github.com/chlorinexxe/billing_app/blob/main/ui/components/card.py): UI component · `ui/components/card.py`
- [Product UI Assets](https://github.com/chlorinexxe/billing_app/blob/main/ui/assets/products.py): UI data module · `ui/assets/products.py`
- [Customer UI Assets](https://github.com/chlorinexxe/billing_app/blob/main/ui/assets/customers.py): UI data module · `ui/assets/customers.py`
- [Supplier UI Assets](https://github.com/chlorinexxe/billing_app/blob/main/ui/assets/suppliers.py): UI data module · `ui/assets/suppliers.py`

### Billing Workflow

- [Generate Bill](https://github.com/chlorinexxe/billing_app/blob/main/ui/generate_bill/page.py): Workflow page · `ui/generate_bill/page.py`
- **Supplier & Customer Sections**: Bill form sections
- [Line Item Table](https://github.com/chlorinexxe/billing_app/blob/main/ui/generate_bill/product_table.py): Bill form section · `ui/generate_bill/product_table.py`
- [Totals Section](https://github.com/chlorinexxe/billing_app/blob/main/ui/generate_bill/totals_section.py): Bill form section · `ui/generate_bill/totals_section.py`
- [Bill Service](https://github.com/chlorinexxe/billing_app/blob/main/ui/generate_bill/bill_service.py): Business service · Owns bill creation and finalization. · `ui/generate_bill/bill_service.py`
- [Financial Calculations](https://github.com/chlorinexxe/billing_app/blob/main/calculations.py): Calculation module · `calculations.py`

### Domain & Data

- [Business Models](https://github.com/chlorinexxe/billing_app/blob/main/models.py): Persistence models · Products, parties, and bill records. · `models.py`
- [Database Setup](https://github.com/chlorinexxe/billing_app/blob/main/database.py): Database boundary · `database.py`

### Analytics

- [Statistics Service](https://github.com/chlorinexxe/billing_app/blob/main/services/stats_service.py): Analytics service · `services/stats_service.py`

### Schema Evolution

- [Alembic Environment](https://github.com/chlorinexxe/billing_app/blob/main/alembic/env.py): Migration runner · `alembic/env.py`
- [Party State Migration](https://github.com/chlorinexxe/billing_app/blob/main/alembic/versions/39f2eefc5ca6_added_state_in_the_supplier_and_customer.py): Schema migration · Adds persisted state for suppliers and customers. · `alembic/versions/39f2eefc5ca6_added_state_in_the_supplier_and_customer.py`

### Other components

- [Application Bootstrap](https://github.com/chlorinexxe/billing_app/blob/main/app.py): Python entry point · `app.py`

## Connections

- Application Bootstrap → Dashboard: launches
- Application Bootstrap → Product Management: launches
- Application Bootstrap → Generate Bill: launches
- Product Management → Add Product Dialog: opens
- Product Management → Product UI Assets: uses
- Product UI Assets → Business Models: accesses
- Customer UI Assets → Business Models: accesses
- Supplier UI Assets → Business Models: accesses
- Generate Bill → Supplier & Customer Sections: composes
- Generate Bill → Line Item Table: composes
- Generate Bill → Totals Section: composes
- Supplier & Customer Sections → Customer UI Assets: selects customers
- Supplier & Customer Sections → Supplier UI Assets: selects suppliers
- Line Item Table → Product UI Assets: selects products
- Totals Section → Financial Calculations: calculates totals
- Generate Bill → Bill Service: submits bill
- Bill Service → Financial Calculations: uses
- Bill Service → Business Models: persists bills
- Business Models → Database Setup: stored through
- Statistics Service → Business Models: aggregates persisted data
- Dashboard → Statistics Service: requests statistics
- Dashboard → Dashboard Card: renders
- Alembic Environment → Party State Migration: runs
- Party State Migration → Business Models: evolves schema for
- Alembic Environment → Database Setup: migrates