How enhancedjax/bagels works
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