# enhancedjax/bagels architecture

> Architecture diagram of the GitHub repository enhancedjax/bagels, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/enhancedjax/bagels
- Repository: https://github.com/enhancedjax/bagels

## Overview

##### Project Type and Purpose
- Bagels is a single‐process, full‐stack TUI application built in Python using the Textual framework.
- It provides an interactive terminal UI (presentation layer), business logic (application layer), and local persistence (data layer via SQLite).

##### File Structure and Architectural Patterns
- Top‐Level Modules:
– src/bagels/__main__.py: CLI entry point
– src/bagels/app.py: bootstraps the Textual App (UI event loop, screens)
– src/bagels/components, forms, modals, styles, themes: UI building blocks
– src/bagels/managers: controllers handling business operations (CRUD, balances, samples)
– src/bagels/models: domain entities and database abstractions
– src/bagels/models/database: low‐level DB connection & ORM layer
– src/bagels/provider.py & config.py: global context, configuration, dependency injection
- Architectural Pattern: MVC‐style layering
– View: Textual components, styles, modals
– Controller/Service: Managers, App orchestration
– Model/DAO: Models, database (SQLite via db.py), migrations

##### Key README Insights
- Built with Textual for TUI
- Local data storage; no external network services
- YAML‐based static templates and default categories
- Uses UV installer but that’s orthogonal to runtime architecture

##### Main Components & Their Relationships
a. CLI Layer
- “bagels” command → __main__.py → invokes App
b. Presentation Layer (Textual UI)
- App (app.py) initializes screens and themes
- Components (automplete, datatable, barchart, tplot, etc.)
- Forms and Modals for user input
c. Application/Business Layer
- Provider: holds config, paths, DB session
- Managers: account, category, record, template, split, person → implement CRUD and business rules
- Home/Jump/Navigation modules orchestrate flows
d. Domain Model Layer
- Models: account, category, record, split, person, record_template
- Constants, validation, formatting utilities
e. Persistence Layer
- Database module (db.py, app.py) using SQLite
- Migrations scripts (migrate_actualbudget.py)
- Static YAML defaults and samples in /static
- Config files under user home or custom path

##### Architectural Patterns & Design Principles
- Separation of concerns (UI vs. business vs. persistence)
- Dependency injection via Provider
- MVC/MVP‐ish flow (UI events → controller → model → persistence → UI update)
- Modular UI components for reusability

##### Detail Level Advice
- Config loading (config.py → provider)
- Don’t omit the CLI entry point – it’s the user’s gateway

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    CLI["__main__.py"]:::cli
    click CLI "https://github.com/enhancedjax/bagels/blob/main/src/bagels/__main__.py"

    %% Presentation Layer
    subgraph "Presentation Layer"
        APP["app.py"]:::presentation
        click APP "https://github.com/enhancedjax/bagels/blob/main/src/bagels/app.py"
        Runner["textualrun.py"]:::presentation
        click Runner "https://github.com/enhancedjax/bagels/blob/main/src/bagels/textualrun.py"
        subgraph "UI Components"
            Components["components/"]:::ui
            click Components "https://github.com/enhancedjax/bagels/tree/main/src/bagels/components/"
            Forms["forms/"]:::ui
            click Forms "https://github.com/enhancedjax/bagels/tree/main/src/bagels/forms/"
            Modals["modals/"]:::ui
            click Modals "https://github.com/enhancedjax/bagels/tree/main/src/bagels/modals/"
            Styles["styles/"]:::ui
            click Styles "https://github.com/enhancedjax/bagels/tree/main/src/bagels/styles/"
            Themes["themes.py"]:::ui
            click Themes "https://github.com/enhancedjax/bagels/blob/main/src/bagels/themes.py"
        end
        Home["home.py"]:::presentation
        click Home "https://github.com/enhancedjax/bagels/blob/main/src/bagels/home.py"
        Locations["locations.py"]:::presentation
        click Locations "https://github.com/enhancedjax/bagels/blob/main/src/bagels/locations.py"
        JumpOverlay["components/jump_overlay.py"]:::presentation
        click JumpOverlay "https://github.com/enhancedjax/bagels/blob/main/src/bagels/components/jump_overlay.py"
        Jumper["components/jumper.py"]:::presentation
        click Jumper "https://github.com/enhancedjax/bagels/blob/main/src/bagels/components/jumper.py"
    end

    %% Application Layer
    subgraph "Application Layer"
        Provider["provider.py"]:::logic
        click Provider "https://github.com/enhancedjax/bagels/blob/main/src/bagels/provider.py"
        Config["config.py"]:::logic
        click Config "https://github.com/enhancedjax/bagels/blob/main/src/bagels/config.py"
        subgraph "Managers"
            BaseMgr["manager.py"]:::logic
            click BaseMgr "https://github.com/enhancedjax/bagels/blob/main/src/bagels/manager.py"
            Accounts["managers/accounts.py"]:::logic
            click Accounts "https://github.com/enhancedjax/bagels/blob/main/src/bagels/managers/accounts.py"
            Categories["managers/categories.py"]:::logic
            click Categories "https://github.com/enhancedjax/bagels/blob/main/src/bagels/managers/categories.py"
            Persons["managers/persons.py"]:::logic
            click Persons "https://github.com/enhancedjax/bagels/blob/main/src/bagels/managers/persons.py"
            TemplatesMgr["managers/record_templates.py"]:::logic
            click TemplatesMgr "https://github.com/enhancedjax/bagels/blob/main/src/bagels/managers/record_templates.py"
            RecordsMgr["managers/records.py"]:::logic
            click RecordsMgr "https://github.com/enhancedjax/bagels/blob/main/src/bagels/managers/records.py"
            Splits["managers/splits.py"]:::logic
            click Splits "https://github.com/enhancedjax/bagels/blob/main/src/bagels/managers/splits.py"
            Samples["managers/samples.py"]:::logic
            click Samples "https://github.com/enhancedjax/bagels/blob/main/src/bagels/managers/samples.py"
            UtilsMgr["managers/utils.py"]:::logic
            click UtilsMgr "https://github.com/enhancedjax/bagels/blob/main/src/bagels/managers/utils.py"
        end
        Versioning["versioning.py"]:::logic
        click Versioning "https://github.com/enhancedjax/bagels/blob/main/src/bagels/versioning.py"
    end

    %% Domain Model Layer
    subgraph "Domain Model Layer"
        AccountModel["models/account.py"]:::domain
        click AccountModel "https://github.com/enhancedjax/bagels/blob/main/src/bagels/models/account.py"
        CategoryModel["models/category.py"]:::domain
        click CategoryModel "https://github.com/enhancedjax/bagels/blob/main/src/bagels/models/category.py"
        PersonModel["models/person.py"]:::domain
        click PersonModel "https://github.com/enhancedjax/bagels/blob/main/src/bagels/models/person.py"
        RecordModel["models/record.py"]:::domain
        click RecordModel "https://github.com/enhancedjax/bagels/blob/main/src/bagels/models/record.py"
        TemplateModel["models/record_template.py"]:::domain
        click TemplateModel "https://github.com/enhancedjax/bagels/blob/main/src/bagels/models/record_template.py"
        SplitModel["models/split.py"]:::domain
        click SplitModel "https://github.com/enhancedjax/bagels/blob/main/src/bagels/models/split.py"
        subgraph "DB Layer"
            DBApp["models/database/app.py"]:::domain
            click DBApp "https://github.com/enhancedjax/bagels/blob/main/src/bagels/models/database/app.py"
            DBCore["models/database/db.py"]:::domain
            click DBCore "https://github.com/enhancedjax/bagels/blob/main/src/bagels/models/database/db.py"
        end
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        Migrations["migrate_actualbudget.py"]:::persistence
        click Migrations "https://github.com/enhancedjax/bagels/blob/main/src/bagels/migrations/migrate_actualbudget.py"
        DefaultCats["default_categories.yaml"]:::static
        click DefaultCats "https://github.com/enhancedjax/bagels/blob/main/src/bagels/static/default_categories.yaml"
        SamplesStatic["sample_entries.yaml"]:::static
        click SamplesStatic "https://github.com/enhancedjax/bagels/blob/main/src/bagels/static/sample_entries.yaml"
        WelcomeStatic["welcome.md"]:::static
        click WelcomeStatic "https://github.com/enhancedjax/bagels/blob/main/src/bagels/static/welcome.md"
        SQLiteDB["SQLite DB File"]:::db
    end

    %% Utilities / Helpers
    subgraph "Utilities / Helpers"
        Format["utils/format.py"]:::logic
        click Format "https://github.com/enhancedjax/bagels/blob/main/src/bagels/utils/format.py"
        UserHost["utils/user_host.py"]:::logic
        click UserHost "https://github.com/enhancedjax/bagels/blob/main/src/bagels/utils/user_host.py"
        Validation["utils/validation.py"]:::logic
        click Validation "https://github.com/enhancedjax/bagels/blob/main/src/bagels/utils/validation.py"
    end

    %% Connections
    CLI -->|"invokes"| APP
    CLI -->|uses| Runner

    APP -->|"renders UI"| Components
    APP -->|"renders UI"| Forms
    APP -->|"renders UI"| Modals
    APP -->|"applies styles"| Styles
    APP -->|"loads themes"| Themes
    APP -->|"navigates"| Home
    APP -->|"uses navigation"| Locations
    APP -->|"uses overlay"| JumpOverlay
    APP -->|"uses overlay"| Jumper

    APP -->|"initialize"| Provider
    APP -->|"loads config"| Config

    Provider -->|"injects into"| BaseMgr
    Provider -->|"injects into"| Accounts
    Provider -->|"injects into"| Categories
    Provider -->|"injects into"| Persons
    Provider -->|"injects into"| TemplatesMgr
    Provider -->|"injects into"| RecordsMgr
    Provider -->|"injects into"| Splits
    Provider -->|"injects into"| Samples
    Provider -->|"provides version"| Versioning

    Accounts -->|"operates on"| AccountModel
    Categories -->|"operates on"| CategoryModel
    Persons -->|"operates on"| PersonModel
    RecordsMgr -->|"operates on"| RecordModel
    TemplatesMgr -->|"operates on"| TemplateModel
    Splits -->|"operates on"| SplitModel

    AccountModel -->|"stores in"| DBCore
    CategoryModel -->|"stores in"| DBCore
    PersonModel -->|"stores in"| DBCore
    RecordModel -->|"stores in"| DBCore
    TemplateModel -->|"stores in"| DBCore
    SplitModel -->|"stores in"| DBCore

    DBCore -->|"opens"| SQLiteDB
    DBApp -->|"configures"| DBCore

    Migrations -.->|"updates schema"| SQLiteDB
    DefaultCats -.->|"load defaults"| Provider
    SamplesStatic -.->|"load samples"| Provider
    WelcomeStatic -.->|"load docs"| APP

    Format -->|"used by"| BaseMgr
    Validation -->|"used by"| BaseMgr
    UserHost -->|"used by"| Provider

    %% Styles
    classDef cli fill:#dddddd,stroke:#999;
    classDef presentation fill:#ccffcc,stroke:#2f6627;
    classDef ui fill:#ccffcc,stroke:#2f6627;
    classDef logic fill:#cce5ff,stroke:#004085;
    classDef domain fill:#fff3cd,stroke:#856404;
    classDef persistence fill:#e2e3e5,stroke:#6c757d;
    classDef db fill:#e2e3e5,stroke:#6c757d,stroke-width:2px,shape:cylinder
```
