metavalai/calculator

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.