SPB Git

Repository Public MIT

overview.md 5.1 KB 111 lines markdown

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
Files main
Menu

Theme