# advaetuc/augmentr architecture

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

- Interactive diagram: https://gitdiagram.com/advaetuc/augmentr
- Repository: https://github.com/advaetuc/augmentr

## Overview

Augmentr is an educational linear-system solver. The user enters a matrix and solver options in the Next.js workspace, requests analysis or a solve, and inspects the returned classification, diagnostics, derivation or iteration history, visualization, and report. The backend validates API contracts and delegates numerical work to a transport-independent Python core. The README documents four methods and exact-rational direct solving; sampled service code confirms the dispatch and analysis flow. Some UI wiring and core internals were not sampled, so uncertain links are omitted.

Main entry points: [`api_app/services.py`](https://github.com/advaetuc/augmentr/blob/main/api_app/services.py) (Analysis and solve service), [`components/solver/workspace.tsx`](https://github.com/advaetuc/augmentr/blob/main/components/solver/workspace.tsx) (Solver workspace), [`lib/api/client.ts`](https://github.com/advaetuc/augmentr/blob/main/lib/api/client.ts) (API client), [`components/solver/result-inspector.tsx`](https://github.com/advaetuc/augmentr/blob/main/components/solver/result-inspector.tsx) (Result inspection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_solve_page["Solve page<br/>[page.tsx]"]
  node_workspace["Solver workspace<br/>[workspace.tsx]"]
  node_configuration["Method configuration<br/>[configuration.tsx]"]
  node_matrix["Matrix editor<br/>[matrix-grid.tsx]"]
  node_draft["Session draft<br/>[storage.ts]"]
  node_api_client["API client<br/>[client.ts]"]
  node_learn["Method guide<br/>[page.tsx]"]
end

subgraph group_api["API boundary"]
  node_api_entry["ASGI entrypoint<br/>[index.py]"]
  node_app_factory["Application factory<br/>[__init__.py]"]
  node_request_models["Request contracts<br/>[requests.py]"]
  node_services["Analysis and solve service<br/>[services.py]"]
  node_response_models["Outcome contracts<br/>[responses.py]"]
end

subgraph group_core["Numerical core"]
  node_parsing["System parsing<br/>[parsing.py]"]
  node_classification["Classification and rank<br/>[classification.py]"]
  node_diagnostics["Condition diagnostics<br/>[diagnostics.py]"]
  node_gaussian["Gaussian elimination<br/>[gaussian.py]"]
  node_gauss_jordan["Gauss-Jordan<br/>[gauss_jordan.py]"]
  node_jacobi["Jacobi iteration<br/>[jacobi.py]"]
  node_seidel["Gauss-Seidel iteration<br/>[gauss_seidel.py]"]
  node_elimination["Row operations and trace<br/>[_elimination.py]"]
end

subgraph group_outputs["Result views"]
  node_result["Result inspection"]
  node_analysis_view["Analysis panel<br/>[analysis-panel.tsx]"]
  node_geometry["Geometry visualization<br/>[derive.ts]"]
  node_report["Report generation<br/>[render.ts]"]
  node_report_preview["Report preview<br/>[report-preview.tsx]"]
end

node_user(("Solver user"))

node_user -->|"opens solver"| node_solve_page
node_solve_page -->|"renders workspace"| node_workspace
node_workspace -->|"edits system"| node_matrix
node_workspace -->|"sets options"| node_configuration
node_workspace -->|"restores and saves"| node_draft
node_workspace -->|"requests analysis or solve"| node_api_client
node_api_client -->|"POSTs API request"| node_api_entry
node_api_entry -->|"creates app"| node_app_factory
node_app_factory -->|"dispatches requests"| node_services
node_services -->|"accepts validated payload"| node_request_models
node_services -->|"parses system"| node_parsing
node_services -->|"classifies system"| node_classification
node_services -->|"computes diagnostics"| node_diagnostics
node_services -->|"dispatches Gaussian solve"| node_gaussian
node_services -->|"dispatches Gauss-Jordan solve"| node_gauss_jordan
node_services -->|"dispatches Jacobi solve"| node_jacobi
node_services -->|"dispatches Seidel solve"| node_seidel
node_gaussian -->|"uses row reduction"| node_elimination
node_gauss_jordan -->|"uses row reduction"| node_elimination
node_services -->|"returns typed outcomes"| node_response_models
node_api_client -->|"supplies analysis outcome"| node_analysis_view
node_api_client -->|"supplies solve outcome"| node_result
node_result -->|"derives plot data"| node_geometry
node_result -->|"provides report input"| node_report
node_report -->|"renders report blocks"| node_report_preview
node_user -->|"opens method guide"| node_learn

click node_solve_page "https://github.com/advaetuc/augmentr/blob/main/app/solve/page.tsx"
click node_workspace "https://github.com/advaetuc/augmentr/blob/main/components/solver/workspace.tsx"
click node_configuration "https://github.com/advaetuc/augmentr/blob/main/components/solver/configuration.tsx"
click node_matrix "https://github.com/advaetuc/augmentr/blob/main/components/solver/matrix-grid.tsx"
click node_draft "https://github.com/advaetuc/augmentr/blob/main/lib/solver/storage.ts"
click node_api_client "https://github.com/advaetuc/augmentr/blob/main/lib/api/client.ts"
click node_api_entry "https://github.com/advaetuc/augmentr/blob/main/api/index.py"
click node_app_factory "https://github.com/advaetuc/augmentr/blob/main/api_app/__init__.py"
click node_request_models "https://github.com/advaetuc/augmentr/blob/main/api_models/requests.py"
click node_services "https://github.com/advaetuc/augmentr/blob/main/api_app/services.py"
click node_response_models "https://github.com/advaetuc/augmentr/blob/main/api_models/responses.py"
click node_parsing "https://github.com/advaetuc/augmentr/blob/main/solver_core/parsing.py"
click node_classification "https://github.com/advaetuc/augmentr/blob/main/solver_core/classification.py"
click node_diagnostics "https://github.com/advaetuc/augmentr/blob/main/solver_core/diagnostics.py"
click node_gaussian "https://github.com/advaetuc/augmentr/blob/main/solver_core/gaussian.py"
click node_gauss_jordan "https://github.com/advaetuc/augmentr/blob/main/solver_core/gauss_jordan.py"
click node_jacobi "https://github.com/advaetuc/augmentr/blob/main/solver_core/jacobi.py"
click node_seidel "https://github.com/advaetuc/augmentr/blob/main/solver_core/gauss_seidel.py"
click node_elimination "https://github.com/advaetuc/augmentr/blob/main/solver_core/_elimination.py"
click node_result "https://github.com/advaetuc/augmentr/blob/main/components/solver/result-inspector.tsx"
click node_analysis_view "https://github.com/advaetuc/augmentr/blob/main/components/solver/analysis-panel.tsx"
click node_geometry "https://github.com/advaetuc/augmentr/blob/main/lib/geometry/derive.ts"
click node_report "https://github.com/advaetuc/augmentr/blob/main/lib/reports/render.ts"
click node_report_preview "https://github.com/advaetuc/augmentr/blob/main/components/solver/report-preview.tsx"
click node_learn "https://github.com/advaetuc/augmentr/blob/main/app/learn/page.tsx"

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_solve_page,node_workspace,node_configuration,node_matrix,node_draft,node_api_client,node_learn,node_user toneBlue
class node_api_entry,node_app_factory,node_request_models,node_services,node_response_models toneAmber
class node_parsing,node_classification,node_diagnostics,node_gaussian,node_gauss_jordan,node_jacobi,node_seidel,node_elimination toneMint
class node_result,node_analysis_view,node_geometry,node_report,node_report_preview toneRose
```

## Components

### Web experience

- [Solve page](https://github.com/advaetuc/augmentr/blob/main/app/solve/page.tsx): `app/solve/page.tsx`
- [Solver workspace](https://github.com/advaetuc/augmentr/blob/main/components/solver/workspace.tsx): `components/solver/workspace.tsx`
- [Method configuration](https://github.com/advaetuc/augmentr/blob/main/components/solver/configuration.tsx): `components/solver/configuration.tsx`
- [Matrix editor](https://github.com/advaetuc/augmentr/blob/main/components/solver/matrix-grid.tsx): `components/solver/matrix-grid.tsx`
- [Session draft](https://github.com/advaetuc/augmentr/blob/main/lib/solver/storage.ts): `lib/solver/storage.ts`
- [API client](https://github.com/advaetuc/augmentr/blob/main/lib/api/client.ts): `lib/api/client.ts`
- [Method guide](https://github.com/advaetuc/augmentr/blob/main/app/learn/page.tsx): `app/learn/page.tsx`

### API boundary

- [ASGI entrypoint](https://github.com/advaetuc/augmentr/blob/main/api/index.py): `api/index.py`
- [Application factory](https://github.com/advaetuc/augmentr/blob/main/api_app/__init__.py): `api_app/__init__.py`
- [Request contracts](https://github.com/advaetuc/augmentr/blob/main/api_models/requests.py): `api_models/requests.py`
- [Analysis and solve service](https://github.com/advaetuc/augmentr/blob/main/api_app/services.py): `api_app/services.py`
- [Outcome contracts](https://github.com/advaetuc/augmentr/blob/main/api_models/responses.py): `api_models/responses.py`

### Numerical core

- [System parsing](https://github.com/advaetuc/augmentr/blob/main/solver_core/parsing.py): `solver_core/parsing.py`
- [Classification and rank](https://github.com/advaetuc/augmentr/blob/main/solver_core/classification.py): `solver_core/classification.py`
- [Condition diagnostics](https://github.com/advaetuc/augmentr/blob/main/solver_core/diagnostics.py): `solver_core/diagnostics.py`
- [Gaussian elimination](https://github.com/advaetuc/augmentr/blob/main/solver_core/gaussian.py): `solver_core/gaussian.py`
- [Gauss-Jordan](https://github.com/advaetuc/augmentr/blob/main/solver_core/gauss_jordan.py): `solver_core/gauss_jordan.py`
- [Jacobi iteration](https://github.com/advaetuc/augmentr/blob/main/solver_core/jacobi.py): `solver_core/jacobi.py`
- [Gauss-Seidel iteration](https://github.com/advaetuc/augmentr/blob/main/solver_core/gauss_seidel.py): `solver_core/gauss_seidel.py`
- [Row operations and trace](https://github.com/advaetuc/augmentr/blob/main/solver_core/_elimination.py): `solver_core/_elimination.py`

### Result views

- [Result inspection](https://github.com/advaetuc/augmentr/blob/main/components/solver/result-inspector.tsx): `components/solver/result-inspector.tsx`
- [Analysis panel](https://github.com/advaetuc/augmentr/blob/main/components/solver/analysis-panel.tsx): `components/solver/analysis-panel.tsx`
- [Geometry visualization](https://github.com/advaetuc/augmentr/blob/main/lib/geometry/derive.ts): `lib/geometry/derive.ts`
- [Report generation](https://github.com/advaetuc/augmentr/blob/main/lib/reports/render.ts): `lib/reports/render.ts`
- [Report preview](https://github.com/advaetuc/augmentr/blob/main/components/solver/report-preview.tsx): `components/solver/report-preview.tsx`

### Other components

- **Solver user**

## Connections

- Solver user → Solve page: opens solver
- Solve page → Solver workspace: renders workspace
- Solver workspace → Matrix editor: edits system
- Solver workspace → Method configuration: sets options
- Solver workspace → Session draft: restores and saves
- Solver workspace → API client: requests analysis or solve
- API client → ASGI entrypoint: POSTs API request
- ASGI entrypoint → Application factory: creates app
- Application factory → Analysis and solve service: dispatches requests
- Analysis and solve service → Request contracts: accepts validated payload
- Analysis and solve service → System parsing: parses system
- Analysis and solve service → Classification and rank: classifies system
- Analysis and solve service → Condition diagnostics: computes diagnostics
- Analysis and solve service → Gaussian elimination: dispatches Gaussian solve
- Analysis and solve service → Gauss-Jordan: dispatches Gauss-Jordan solve
- Analysis and solve service → Jacobi iteration: dispatches Jacobi solve
- Analysis and solve service → Gauss-Seidel iteration: dispatches Seidel solve
- Gaussian elimination → Row operations and trace: uses row reduction
- Gauss-Jordan → Row operations and trace: uses row reduction
- Analysis and solve service → Outcome contracts: returns typed outcomes
- API client → Analysis panel: supplies analysis outcome
- API client → Result inspection: supplies solve outcome
- Result inspection → Geometry visualization: derives plot data
- Result inspection → Report generation: provides report input
- Report generation → Report preview: renders report blocks
- Solver user → Method guide: opens method guide