# advaetuc/asymtote architecture

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

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

## Overview

TULYA is an educational linear-system solver whose implemented workflow is API-based: a caller submits a system for analysis or solving, the service parses it and dispatches numerical work, and receives a typed outcome with classification, diagnostics, and (for solving) result/report metadata. The web page is currently an informational methods landing page; the README says the interactive solver UI is planned. The graph reflects documented capabilities, but some numerical implementation wiring is unsampled and is therefore left unconnected.

Main entry points: [`api_app/services.py`](https://github.com/advaetuc/asymtote/blob/main/api_app/services.py) (Solver service), [`api_app/__init__.py`](https://github.com/advaetuc/asymtote/blob/main/api_app/__init__.py) (HTTP routes), [`solver_core/_iterative.py`](https://github.com/advaetuc/asymtote/blob/main/solver_core/_iterative.py) (Iteration engine), [`app/page.tsx`](https://github.com/advaetuc/asymtote/blob/main/app/page.tsx) (Methods landing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web presentation"]
  node_landing["Methods landing<br/>[page.tsx]"]
  node_layout["Page layout<br/>[layout.tsx]"]
end

subgraph group_api["HTTP API"]
  node_entry["ASGI entry<br/>[index.py]"]
  node_http_app["HTTP routes<br/>[__init__.py]"]
  node_request_middleware["Request middleware<br/>[observability.py]"]
  node_service["Solver service<br/>[services.py]"]
end

subgraph group_contracts["Input and outcomes"]
  node_request_models["Request schemas<br/>[requests.py]"]
  node_response_models["Outcome schemas<br/>[responses.py]"]
  node_health_model["Health response<br/>[health.py]"]
end

subgraph group_numerics["Numerical engine"]
  node_parser["Numeric parsing<br/>[parsing.py]"]
  node_domain_models["Solver models<br/>[models.py]"]
  node_classification["Rank classification<br/>[classification.py]"]
  node_gaussian["Gaussian solver<br/>[gaussian.py]"]
  node_gauss_jordan["Gauss-Jordan solver<br/>[gauss_jordan.py]"]
  node_jacobi["Jacobi solver<br/>[jacobi.py]"]
  node_gauss_seidel["Gauss-Seidel solver<br/>[gauss_seidel.py]"]
  node_iteration_engine["Iteration engine<br/>[_iterative.py]"]
  node_convergence["Convergence analysis<br/>[convergence.py]"]
  node_permutations["Row matching<br/>[permutations.py]"]
  node_diagnostics["Condition diagnostics<br/>[diagnostics.py]"]
  node_trace["Operation traces<br/>[trace.py]"]
  node_report["Result reports<br/>[report.py]"]
end

node_visitor(("Site visitor"))
node_api_caller(("API caller"))

node_visitor -->|"views"| node_landing
node_landing -->|"renders within"| node_layout
node_api_caller -->|"submits requests"| node_entry
node_entry -->|"creates app"| node_http_app
node_http_app -->|"installs"| node_request_middleware
node_http_app -->|"validates payloads"| node_request_models
node_http_app -->|"returns health"| node_health_model
node_http_app -->|"dispatches analysis/solve"| node_service
node_request_middleware -->|"wraps requests"| node_http_app
node_request_models -->|"validates numeric tokens"| node_parser
node_service -->|"parses systems"| node_parser
node_service -->|"classifies systems"| node_classification
node_service -->|"dispatches method"| node_gaussian
node_service -->|"dispatches method"| node_gauss_jordan
node_service -->|"dispatches method"| node_jacobi
node_service -->|"dispatches method"| node_gauss_seidel
node_service -->|"checks eligibility"| node_convergence
node_service -->|"checks row matches"| node_permutations
node_service -->|"computes conditioning"| node_diagnostics
node_service -->|"returns typed outcomes"| node_response_models
node_jacobi -->|"runs iteration"| node_iteration_engine
node_gauss_seidel -->|"runs iteration"| node_iteration_engine
node_iteration_engine -->|"requires unique system"| node_classification
node_iteration_engine -->|"assesses convergence"| node_convergence
node_iteration_engine -->|"reorders rows"| node_permutations
node_iteration_engine -->|"computes metrics"| node_diagnostics

click node_landing "https://github.com/advaetuc/asymtote/blob/main/app/page.tsx"
click node_layout "https://github.com/advaetuc/asymtote/blob/main/app/layout.tsx"
click node_entry "https://github.com/advaetuc/asymtote/blob/main/api/index.py"
click node_http_app "https://github.com/advaetuc/asymtote/blob/main/api_app/__init__.py"
click node_request_middleware "https://github.com/advaetuc/asymtote/blob/main/api_app/observability.py"
click node_service "https://github.com/advaetuc/asymtote/blob/main/api_app/services.py"
click node_request_models "https://github.com/advaetuc/asymtote/blob/main/api_models/requests.py"
click node_response_models "https://github.com/advaetuc/asymtote/blob/main/api_models/responses.py"
click node_health_model "https://github.com/advaetuc/asymtote/blob/main/api_models/health.py"
click node_parser "https://github.com/advaetuc/asymtote/blob/main/solver_core/parsing.py"
click node_domain_models "https://github.com/advaetuc/asymtote/blob/main/solver_core/models.py"
click node_classification "https://github.com/advaetuc/asymtote/blob/main/solver_core/classification.py"
click node_gaussian "https://github.com/advaetuc/asymtote/blob/main/solver_core/gaussian.py"
click node_gauss_jordan "https://github.com/advaetuc/asymtote/blob/main/solver_core/gauss_jordan.py"
click node_jacobi "https://github.com/advaetuc/asymtote/blob/main/solver_core/jacobi.py"
click node_gauss_seidel "https://github.com/advaetuc/asymtote/blob/main/solver_core/gauss_seidel.py"
click node_iteration_engine "https://github.com/advaetuc/asymtote/blob/main/solver_core/_iterative.py"
click node_convergence "https://github.com/advaetuc/asymtote/blob/main/solver_core/convergence.py"
click node_permutations "https://github.com/advaetuc/asymtote/blob/main/solver_core/permutations.py"
click node_diagnostics "https://github.com/advaetuc/asymtote/blob/main/solver_core/diagnostics.py"
click node_trace "https://github.com/advaetuc/asymtote/blob/main/solver_core/trace.py"
click node_report "https://github.com/advaetuc/asymtote/blob/main/solver_core/report.py"

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_landing,node_layout toneBlue
class node_entry,node_http_app,node_request_middleware,node_service toneAmber
class node_request_models,node_response_models,node_health_model,node_api_caller toneMint
class node_parser,node_domain_models,node_classification,node_gaussian,node_gauss_jordan,node_jacobi,node_gauss_seidel,node_iteration_engine,node_convergence,node_permutations,node_diagnostics,node_trace,node_report toneRose
class node_visitor toneIndigo
```

## Components

### Web presentation

- [Methods landing](https://github.com/advaetuc/asymtote/blob/main/app/page.tsx): `app/page.tsx`
- [Page layout](https://github.com/advaetuc/asymtote/blob/main/app/layout.tsx): `app/layout.tsx`

### HTTP API

- [ASGI entry](https://github.com/advaetuc/asymtote/blob/main/api/index.py): `api/index.py`
- [HTTP routes](https://github.com/advaetuc/asymtote/blob/main/api_app/__init__.py): `api_app/__init__.py`
- [Request middleware](https://github.com/advaetuc/asymtote/blob/main/api_app/observability.py): `api_app/observability.py`
- [Solver service](https://github.com/advaetuc/asymtote/blob/main/api_app/services.py): `api_app/services.py`

### Input and outcomes

- [Request schemas](https://github.com/advaetuc/asymtote/blob/main/api_models/requests.py): `api_models/requests.py`
- [Outcome schemas](https://github.com/advaetuc/asymtote/blob/main/api_models/responses.py): `api_models/responses.py`
- [Health response](https://github.com/advaetuc/asymtote/blob/main/api_models/health.py): `api_models/health.py`

### Numerical engine

- [Numeric parsing](https://github.com/advaetuc/asymtote/blob/main/solver_core/parsing.py): `solver_core/parsing.py`
- [Solver models](https://github.com/advaetuc/asymtote/blob/main/solver_core/models.py): `solver_core/models.py`
- [Rank classification](https://github.com/advaetuc/asymtote/blob/main/solver_core/classification.py): `solver_core/classification.py`
- [Gaussian solver](https://github.com/advaetuc/asymtote/blob/main/solver_core/gaussian.py): `solver_core/gaussian.py`
- [Gauss-Jordan solver](https://github.com/advaetuc/asymtote/blob/main/solver_core/gauss_jordan.py): `solver_core/gauss_jordan.py`
- [Jacobi solver](https://github.com/advaetuc/asymtote/blob/main/solver_core/jacobi.py): `solver_core/jacobi.py`
- [Gauss-Seidel solver](https://github.com/advaetuc/asymtote/blob/main/solver_core/gauss_seidel.py): `solver_core/gauss_seidel.py`
- [Iteration engine](https://github.com/advaetuc/asymtote/blob/main/solver_core/_iterative.py): `solver_core/_iterative.py`
- [Convergence analysis](https://github.com/advaetuc/asymtote/blob/main/solver_core/convergence.py): `solver_core/convergence.py`
- [Row matching](https://github.com/advaetuc/asymtote/blob/main/solver_core/permutations.py): `solver_core/permutations.py`
- [Condition diagnostics](https://github.com/advaetuc/asymtote/blob/main/solver_core/diagnostics.py): `solver_core/diagnostics.py`
- [Operation traces](https://github.com/advaetuc/asymtote/blob/main/solver_core/trace.py): `solver_core/trace.py`
- [Result reports](https://github.com/advaetuc/asymtote/blob/main/solver_core/report.py): `solver_core/report.py`

### Other components

- **Site visitor**
- **API caller**

## Connections

- Site visitor → Methods landing: views
- Methods landing → Page layout: renders within
- API caller → ASGI entry: submits requests
- ASGI entry → HTTP routes: creates app
- HTTP routes → Request middleware: installs
- HTTP routes → Request schemas: validates payloads
- HTTP routes → Health response: returns health
- HTTP routes → Solver service: dispatches analysis/solve
- Request middleware → HTTP routes: wraps requests
- Request schemas → Numeric parsing: validates numeric tokens
- Solver service → Numeric parsing: parses systems
- Solver service → Rank classification: classifies systems
- Solver service → Gaussian solver: dispatches method
- Solver service → Gauss-Jordan solver: dispatches method
- Solver service → Jacobi solver: dispatches method
- Solver service → Gauss-Seidel solver: dispatches method
- Solver service → Convergence analysis: checks eligibility
- Solver service → Row matching: checks row matches
- Solver service → Condition diagnostics: computes conditioning
- Solver service → Outcome schemas: returns typed outcomes
- Jacobi solver → Iteration engine: runs iteration
- Gauss-Seidel solver → Iteration engine: runs iteration
- Iteration engine → Rank classification: requires unique system
- Iteration engine → Convergence analysis: assesses convergence
- Iteration engine → Row matching: reorders rows
- Iteration engine → Condition diagnostics: computes metrics