Repository Public MIT
1<!--2ORIX Calc3File: docs/architecture/overview.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Architecture overview89ORIX Calc is a thin SwiftUI app on top of local Swift packages. Calculation logic never imports SwiftUI; every engine is10tested from the command line without launching the app.1112```mermaid13flowchart TD14 subgraph App["App target (ORIXCalc)"]15 Shell["Adaptive shell · history · settings · intents · Math Camera"]16 end17 subgraph Features["Feature packages (SwiftUI)"]18 FCalc["ORIXFeatureCalculator<br/>Standard · Scientific"]19 FFin["ORIXFeatureFinancial"]20 FGraph["ORIXFeatureGraph"]21 FMath["ORIXFeatureMath"]22 FStat["ORIXFeatureStatistics"]23 FConv["ORIXFeatureConvert"]24 FWork["ORIXFeatureWorkspace"]25 end26 UI["ORIXUI<br/>design system · AppModel · SwiftData store"]27 subgraph Engines["Engine packages (no UI)"]28 Expr["ORIXExpression<br/>values · parser · evaluator · formatter · RPN"]29 Fin["ORIXFinancial"]30 Graph["ORIXGraph"]31 Sym["ORIXSymbolic"]32 Stat["ORIXStatistics"]33 Units["ORIXUnits"]34 Work["ORIXWorkspace"]35 Cam["ORIXMathCamera"]36 end37 Num["ORIXNumerics<br/>Explanation · VerificationReport · root finding · quadrature"]3839 Shell --> Features40 Features --> UI41 FCalc --> Expr42 FFin --> Fin43 FGraph --> Graph44 FMath --> Sym45 FStat --> Stat46 FConv --> Units47 FWork --> Work48 Shell --> Cam49 UI --> Expr50 UI --> Work51 Graph --> Expr52 Sym --> Expr53 Work --> Expr54 Cam --> Expr55 Expr --> Num56 Fin --> Num57 Stat --> Num58 Graph --> Num59 Sym --> Num60```6162## Module boundaries6364| Package | Responsibility | Depends on |65|---|---|---|66| `ORIXNumerics` | Shared result vocabulary (`Explanation`, `VerificationReport`) and scalar numerical methods (Brent, adaptive Gauss–Kronrod, tanh-sinh, Ridders) | Foundation |67| `ORIXExpression` | Typed values, exact arithmetic, parser, evaluator, compiled real functions, number formatting, expression printing (text / LaTeX), RPN machine | ORIXNumerics, BigInt, Swift Numerics, Accelerate |68| `ORIXFinancial` | TVM, cash flows, loans, bonds, investments, options, sensitivity | ORIXNumerics |69| `ORIXStatistics` | Special functions, descriptive statistics, distributions, inference, regression, simulation | ORIXNumerics |70| `ORIXUnits` | Unit catalogue, exact conversion, rate conventions, currency model | Foundation |71| `ORIXSymbolic` | Simplification, polynomials, calculus, solving, limits, series, optimisation, ODEs | ORIXExpression, ORIXNumerics |72| `ORIXGraph` | Sampling with discontinuity detection, analysis, implicit curves, 3D meshes | ORIXExpression, ORIXNumerics |73| `ORIXWorkspace` | Document model, dependency graph, incremental recalculation, exports, `.orixcalc` format | ORIXExpression, ORIXNumerics |74| `ORIXMathCamera` | Vision text recognition and normalisation into parseable input | ORIXExpression, Vision |75| `ORIXUI` | Design tokens and components; `AppModel` (shared session); SwiftData store | ORIXExpression, ORIXWorkspace, ORIXNumerics |76| `ORIXFeature*` | One SwiftUI package per environment | ORIXUI + its engine |7778Rules that keep this honest:7980- Engines return values **with** an `Explanation` and a `VerificationReport`. The UI never invents either.81- Feature packages do not depend on each other. Cross-environment actions go through `AppModel` mailboxes82 (`pendingGraphExpression`, `pendingConvertValue`, `pendingWorkspaceLine`, `pendingCalculatorText`) or through an83 environment seam (`graphPreview`, used by Workspace to embed a real plot).84- One session: `AppModel` owns one `CalculatorEngine` (variables, user functions, `ans`), one history and one store.8586## Local persistence8788```mermaid89flowchart LR90 AppModel -->|"SwiftData (ORIXSchemaV1)"| Store[("ORIXCalc.store<br/>Application Support")]91 Store --- H["HistoryRecord"]92 Store --- V["NamedValueRecord (canonical text)"]93 Store --- F["FunctionRecord (ASCII body)"]94 Store --- W["WorkspaceRecord (.orixcalc payload, SHA-256 checked)"]95 Store --- M["SavedModelRecord (JSON payload per screen / model)"]96 Settings["AppSettings"] -->|JSON| Defaults[("UserDefaults")]97 AppModel -->|"exportBackup()"| Backup["Backup JSON → Files"]98```99100- Values are persisted as canonical text (`NumberFormat.canonical`: exact fractions, 17-digit doubles) and re-parsed on load,101 so no precision is lost and no binary format has to be migrated.102- The schema is versioned (`ORIXSchemaV1` + `ORIXMigrationPlan`). If the store cannot be opened, its files are renamed103 `…damaged-<timestamp>` (never deleted), a fresh store is created, and the user is told.104- Workspaces carry a checksum; a damaged payload is detected and its readable content recovered.105106## Concurrency107108Swift 6 language mode with complete strict concurrency in every package. Engines are value types and `Sendable`.109Heavy work (committed evaluations, live previews, binomial trees, sweeps, sampling) runs off the main actor in detached110tasks with latest-wins or cancellation; the main actor only applies results.111