# metavalai/calculator architecture

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

- Interactive diagram: https://gitdiagram.com/metavalai/calculator
- Repository: https://github.com/metavalai/calculator

## Overview

1. **Overall shape**
   This is a single-process **Flask** application with a classic server-rendered MVC-style structure: HTTP routes in `app/routes.py`, persistence in `app/models.py`, business logic in `app/services.py`, Jinja templates in `app/templates/`, and browser behavior in `app/static/`.

2. **Application bootstrap**
   `run.py` is the runtime entrypoint. It likely starts the Flask app configured through `config.py` and the package initializer in `app/__init__.py`. That makes the app deployable as a local development server with SQLite-backed state.

3. **Request handling boundary**
   `app/routes.py` is the main web layer. It receives form submissions and page requests, delegates calculation/formula work to the service and utility modules, and returns rendered HTML pages such as home, calculator, formula CRUD, history, and unit conversion views.

4. **Domain and persistence**
   `app/models.py` is the data model layer, most likely using **SQLAlchemy** with **SQLite** as the backing store. Based on the README, this layer supports stored formulas, calculation history, and probably saved inputs/outputs needed for later listing and export.

5. **Business logic layer**
   `app/services.py` is where the app’s core workflow likely lives: creating/editing formulas, evaluating expressions from user input, storing calculation results, and preparing data for history and Excel export. This file is the main separation between web requests and reusable domain logic.

6. **Formula evaluation and special calculators**
   The `app/utils/` package contains formula-specific helpers, including `cv_formula.py`, which strongly suggests a dedicated implementation for the **Cv / flow coefficient** calculation path. This separates the generic formula engine from special engineering formulas that need their own variable semantics.

7. **Unit conversion subsystem**
   `app/unit_conversions.py` is a distinct subsystem for converting user-entered values across supported units such as flow rate, pressure, speed, and time. In the UI, this is paired with “common unit” selectors so the calculation flow can normalize inputs before evaluation.

8. **Presentation layer**
   The Jinja templates define the major screens:
   - `home.html` for dashboard/listing/history entry points
   - `calculate.html` for the active calculator
   - `create_formula.html`, `edit_formula.html`, `view_formula.html` for formula lifecycle
   - `history.html` for past calculations
   - `unit_conversions.html` for standalone conversion tools
   - `login.html` as a user-facing auth page, though no auth implementation is visible in the tree  
   `base.html` provides the shared layout/navigation shell.

9. **Client-side behavior**
   `app/static/app.js` likely handles dynamic form behavior: adding/removing variables, live updates, unit dropdown interactions, and possibly previewing results without full page reloads. `style.css` supplies presentation only and does not appear to contain architectural logic.

10. **Data flow at runtime**
    The main flow is: browser submits formula or input data → Flask route parses request → service layer validates and computes → unit conversion and formula utilities normalize/evaluate values → model layer persists results → response renders HTML and possibly updates history. This creates a clear split between UI, calculation engine, and storage.

11. **Excel export path**
    The README indicates exported calculation reports are written to an `.xlsx` file under `exports/`, using **Pandas** plus **OpenPyXL**. Architecturally, export is a post-processing/reporting concern separate from live calculation, likely invoked from the service layer after calculations are stored.

12. **Key boundaries to diagram**
    The important boundaries are:
    - **HTTP/UI boundary**: templates + static assets vs. Flask routes
    - **Domain boundary**: generic formula engine vs. Cv-specific calculation helpers
    - **Normalization boundary**: raw user units vs. converted canonical values
    - **Persistence/reporting boundary**: live calculation vs. stored history/exported workbook

13. **Likely external dependencies**
    The material runtime dependencies are **Flask** for web serving, **SQLAlchemy + SQLite** for persistence, and **Pandas/OpenPyXL** for Excel output. Those dependencies directly shape the architecture because they define the request lifecycle, storage model, and reporting/export capability.

14. **What is not yet explicit**
    There is a `login.html` template, but no obvious auth subsystem in the file tree, so authentication may be minimal, incomplete, or planned for later. Similarly, the README mentions future features like PDF export and validation, indicating the current architecture is centered on formulas, conversion, history, and Excel reporting rather than a broader platform.

Main entry points: [`app/routes.py`](https://github.com/metavalai/calculator/blob/main/app/routes.py) (Routes), [`app/services.py`](https://github.com/metavalai/calculator/blob/main/app/services.py) (Services), [`app/__init__.py`](https://github.com/metavalai/calculator/blob/main/app/__init__.py) (App init), [`app/models.py`](https://github.com/metavalai/calculator/blob/main/app/models.py) (Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_run_py(("run.py<br/>entrypoint<br/>[run.py]"))
  node_config_py["config.py<br/>[config.py]"]
  node_app_init["App init<br/>flask package<br/>[__init__.py]"]
end

subgraph group_web["Web Layer"]
  node_routes["Routes<br/>HTTP handlers<br/>[routes.py]"]
end

subgraph group_domain["Domain Logic"]
  node_services["Services<br/>workflow layer<br/>[services.py]"]
  node_unit_conversions["Units<br/>conversion subsystem"]
  node_utils_pkg["Utils<br/>helpers package<br/>[__init__.py]"]
  node_cv_formula["Cv formula<br/>special calculator<br/>[cv_formula.py]"]
  node_utils_py["Utils core<br/>helper module<br/>[utils.py]"]
end

subgraph group_data["Data Layer"]
  node_models[("Models<br/>[models.py]")]
end

subgraph group_presentation["Presentation"]
  node_base_tpl["Base shell<br/>jinja layout<br/>[base.html]"]
  node_home_tpl["Home<br/>jinja page<br/>[home.html]"]
  node_calc_tpl["Calculate<br/>jinja page<br/>[calculate.html]"]
  node_formula_tpls["Formula pages<br/>jinja pages"]
  node_history_tpl["History<br/>jinja page<br/>[history.html]"]
  node_units_tpl["Unit tools<br/>jinja page"]
  node_login_tpl["Login<br/>jinja page<br/>[login.html]"]
  node_app_js["app.js<br/>client script<br/>[app.js]"]
  node_style_css["style.css<br/>stylesheet<br/>[style.css]"]
end

node_run_py -->|"starts"| node_app_init
node_app_init -->|"loads"| node_config_py
node_app_init -->|"registers"| node_routes
node_routes -->|"delegates"| node_services
node_routes -->|"reads/writes"| node_models
node_routes -->|"normalizes"| node_unit_conversions
node_routes -->|"uses"| node_utils_py
node_services -->|"persists"| node_models
node_services -->|"converts"| node_unit_conversions
node_services -->|"calls"| node_utils_pkg
node_utils_pkg -->|"includes"| node_cv_formula
node_routes -->|"renders"| node_base_tpl
node_routes -->|"renders"| node_home_tpl
node_routes -->|"renders"| node_calc_tpl
node_routes -->|"renders"| node_formula_tpls
node_routes -->|"renders"| node_history_tpl
node_routes -->|"renders"| node_units_tpl
node_routes -->|"renders"| node_login_tpl
node_routes -->|"serves"| node_app_js
node_routes -->|"serves"| node_style_css
node_services -.->|"exports"| node_models

click node_run_py "https://github.com/metavalai/calculator/blob/main/run.py"
click node_config_py "https://github.com/metavalai/calculator/blob/main/config.py"
click node_app_init "https://github.com/metavalai/calculator/blob/main/app/__init__.py"
click node_routes "https://github.com/metavalai/calculator/blob/main/app/routes.py"
click node_services "https://github.com/metavalai/calculator/blob/main/app/services.py"
click node_models "https://github.com/metavalai/calculator/blob/main/app/models.py"
click node_unit_conversions "https://github.com/metavalai/calculator/blob/main/app/unit_conversions.py"
click node_utils_pkg "https://github.com/metavalai/calculator/blob/main/app/utils/__init__.py"
click node_cv_formula "https://github.com/metavalai/calculator/blob/main/app/utils/cv_formula.py"
click node_utils_py "https://github.com/metavalai/calculator/blob/main/app/utils.py"
click node_base_tpl "https://github.com/metavalai/calculator/blob/main/app/templates/base.html"
click node_home_tpl "https://github.com/metavalai/calculator/blob/main/app/templates/home.html"
click node_calc_tpl "https://github.com/metavalai/calculator/blob/main/app/templates/calculate.html"
click node_history_tpl "https://github.com/metavalai/calculator/blob/main/app/templates/history.html"
click node_units_tpl "https://github.com/metavalai/calculator/blob/main/app/templates/unit_conversions.html"
click node_login_tpl "https://github.com/metavalai/calculator/blob/main/app/templates/login.html"
click node_app_js "https://github.com/metavalai/calculator/blob/main/app/static/app.js"
click node_style_css "https://github.com/metavalai/calculator/blob/main/app/static/style.css"

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_run_py,node_config_py,node_app_init toneBlue
class node_routes toneAmber
class node_services,node_unit_conversions,node_utils_pkg,node_cv_formula,node_utils_py toneMint
class node_models toneRose
class node_base_tpl,node_home_tpl,node_calc_tpl,node_formula_tpls,node_history_tpl,node_units_tpl,node_login_tpl,node_app_js,node_style_css toneIndigo
```

## Components

### Runtime

Application entry and configuration

- [run.py](https://github.com/metavalai/calculator/blob/main/run.py): entrypoint · Flask startup script · `run.py`
- [config.py](https://github.com/metavalai/calculator/blob/main/config.py): config · Application configuration · `config.py`
- [App init](https://github.com/metavalai/calculator/blob/main/app/__init__.py): flask package · Flask application setup · `app/__init__.py`

### Web Layer

Routes and request handling

- [Routes](https://github.com/metavalai/calculator/blob/main/app/routes.py): HTTP handlers · Main request and page handlers · `app/routes.py`

### Domain Logic

Calculation, conversion, and formula behavior

- [Services](https://github.com/metavalai/calculator/blob/main/app/services.py): workflow layer · Core calculation and CRUD workflows · `app/services.py`
- [Units](https://github.com/metavalai/calculator/blob/main/app/unit_conversions.py): conversion subsystem · Normalization across supported units · `app/unit_conversions.py`
- [Utils](https://github.com/metavalai/calculator/blob/main/app/utils/__init__.py): helpers package · Shared formula helper package · `app/utils/__init__.py`
- [Cv formula](https://github.com/metavalai/calculator/blob/main/app/utils/cv_formula.py): special calculator · Cv and flow coefficient logic · `app/utils/cv_formula.py`
- [Utils core](https://github.com/metavalai/calculator/blob/main/app/utils.py): helper module · General utility helpers · `app/utils.py`

### Data Layer

Persistence and export

- [Models](https://github.com/metavalai/calculator/blob/main/app/models.py): persistence models · Stored formulas and history records · `app/models.py`

### Presentation

Templates and browser assets

- [Base shell](https://github.com/metavalai/calculator/blob/main/app/templates/base.html): jinja layout · Shared page layout and navigation · `app/templates/base.html`
- [Home](https://github.com/metavalai/calculator/blob/main/app/templates/home.html): jinja page · Landing and summary page · `app/templates/home.html`
- [Calculate](https://github.com/metavalai/calculator/blob/main/app/templates/calculate.html): jinja page · Interactive calculator view · `app/templates/calculate.html`
- **Formula pages**: jinja pages · Create, edit, and view formula screens
- [History](https://github.com/metavalai/calculator/blob/main/app/templates/history.html): jinja page · Past calculations view · `app/templates/history.html`
- [Unit tools](https://github.com/metavalai/calculator/blob/main/app/templates/unit_conversions.html): jinja page · Standalone unit conversion screen · `app/templates/unit_conversions.html`
- [Login](https://github.com/metavalai/calculator/blob/main/app/templates/login.html): jinja page · User-facing auth page · `app/templates/login.html`
- [app.js](https://github.com/metavalai/calculator/blob/main/app/static/app.js): client script · Dynamic form and UI behavior · `app/static/app.js`
- [style.css](https://github.com/metavalai/calculator/blob/main/app/static/style.css): stylesheet · Visual styling only · `app/static/style.css`

## Connections

- run.py → App init: starts · Entrypoint creates and runs the Flask app
- App init → config.py: loads · Configuration is applied during app setup
- App init → Routes: registers · Routes are attached to the Flask application
- Routes → Services: delegates · HTTP handlers call workflow logic
- Routes → Models: reads/writes · Handlers interact with persisted records
- Routes → Units: normalizes · Request values are converted before evaluation
- Routes → Utils core: uses · Shared helper functions support request handling
- Services → Models: persists · Services store formulas and calculation history
- Services → Units: converts · Services normalize user-entered units
- Services → Utils: calls · Service workflows use formula helper package
- Utils → Cv formula: includes · Specialized Cv logic lives in the utils package
- Routes → Base shell: renders · Most pages extend the shared layout
- Routes → Home: renders · Landing and summary view
- Routes → Calculate: renders · Main calculator page
- Routes → Formula pages: renders · Formula lifecycle pages
- Routes → History: renders · History listing page
- Routes → Unit tools: renders · Unit conversion page
- Routes → Login: renders · Login page template
- Routes → app.js: serves · Interactive browser behavior supports forms and updates
- Routes → style.css: serves · Styles are delivered with the app
- Services → Models: exports · Calculation results can be prepared for workbook output