Architecture and design decisions

← Documentation home · How to use the app

Why this shape

EquaFlow separates fast, interactive modelling from formal constraint solving.

DSL text / canvas edits
        ↓
Next.js + TypeScript UI and local model store
        ↓
solver API route
        ↓
Python translator + Z3
        ↓
solution, validity details and ranges back to the UI

The browser needs immediate parsing, card layout, formula editing and project persistence. That is why the importer and visual model live in TypeScript. Z3's mature Python ecosystem handles the constraint translation and solve step. Rewriting the parser in Python would make import slower and duplicate a user-facing language implementation without removing the Python solver.

Main code locations

| Concern | Location | | --- | --- | | Screen and application navigation | src/app/page.tsx | | DSL parser and exporter | src/lib/dsl-parser.ts | | Built-in AI-value and variate examples | src/lib/dsl-examples.ts | | Client model state and Auto-Solve default | src/lib/store.ts | | Import UI | src/components/equaflow/import-dsl-dialog.tsx | | Python/Z3 solver | mini-services/solver/index.py |

Solving versus calculation

A formula calculates a value from known fields. An output ? has no value until solving. Constraints narrow what values are allowed. Z3 finds one satisfying model, which is a mathematical result—not an approval, forecast or guarantee.

For a trustworthy model, make units explicit in field names or comments, add bounds to unknowns, and test an expected scenario before making a decision.

Auto-Solve as opt-out

Spreadsheet users expect a changed input to refresh dependent results. EquaFlow therefore enables Auto-Solve by default. It remains a visible switch because large, unfinished or exploratory models sometimes need manual control. This is an opt-out policy: automatic re-solving is the normal path, not a hidden experimental setting.