# izaro-c/matematika architecture

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

- Interactive diagram: https://gitdiagram.com/izaro-c/matematika
- Repository: https://github.com/izaro-c/matematika

## Overview

#### Purpose and entry points
Matematika is a Spanish interactive mathematics encyclopedia: MDX articles, semantic navigation, dependency graphs, geometry simulations, study progress, and a separate authoring workflow. The React/Vite browser application starts at `src/app/main.tsx`, composes global providers in `src/app/App.tsx`, and dispatches routes through `src/app/routes/AppRouter.tsx`. Page-level entry points include `src/pages/TheoremPage.tsx`, `src/pages/GraphPage.tsx`, and `src/pages/DiagramEditorPage.tsx`.

#### Content system and semantic boundaries
The filesystem is the primary content database: typed MDX articles live under `src/database/content/`, such as `src/database/content/theorems/teorema-pitagoras.mdx`. `src/entities/content/ContentStore.ts` loads and validates these documents; schemas, metadata types, search, and generated indexes are concentrated in `src/entities/content/schemas.ts`, `src/entities/content/loaders.ts`, and `src/entities/content/searchApi.ts`. Invalid or unresolved references are intentionally non-fatal at runtime, allowing editorial work in progress while exposing warnings/controlled missing-content states.

#### Knowledge graph and learning flow
Article metadata and semantic links feed a logical/semantic graph represented by `src/entities/graph/graph_structure.json` and domain classes in `src/entities/graph/Grafo.ts`. The graph feature builds and processes graph data, including worker offloading, through `src/features/graph/lib/knowledgeGraphBuilder.ts`, `src/features/graph/graph.worker.ts`, and `src/features/graph/GraphStore.ts`. Graph pages and axiomatic exploration consume this layer; study-plan and completion state are managed separately through `src/features/progress/context/StudyPlanContext.ts` and `src/features/progress/UserProgressStore.ts`.

#### Published content rendering
Pages render MDX with shared interactive blocks and reader-oriented layouts. `src/widgets/mdx/MDXBlocks.tsx` is the MDX component boundary; `src/widgets/content/DemonstrationSection.tsx` and `src/widgets/content/MarginaliaPanel.tsx` provide proof presentation and contextual linked-content viewing. Navigation should use semantic concept links rather than ordinary inter-article routing, enabling contextual previews and graph relationships. Exercises are runtime React components rooted in `src/features/exercises/ui/ExerciseContext.tsx` and embedded from authored content.

#### Diagram platform
A shared declarative diagram specification separates authored geometry from rendering. Specification/schema, migrations, and semantics reside in `src/shared/diagrams/spec/schema.ts`, `src/shared/diagrams/spec/schemaV3.ts`, and `src/shared/diagrams/spec/migrations.ts`; the publication runtime is `src/shared/diagrams/runtime/DiagramRenderer.tsx`, backed by the JSXGraph adapter at `src/shared/diagrams/runtime/jsxgraphAdapter.ts`. Existing authored React diagram widgets under `src/widgets/diagrams/` coexist with this shared spec/runtime. This boundary is critical: published pages and the editor should render the same diagram semantics.

#### Editor and persistence service
The editor is a substantial feature for lossless MDX and diagram authoring. Document parsing/projection/edit application live in `src/features/editor/document/parseEditorDocument.ts`, `src/features/editor/document/applySourceEdits.ts`, and `src/features/editor/core/useEditorCore.ts`. The diagram workbench owns editable state and source conversion in `src/features/editor/diagrams/state/reducer.ts`, `src/features/editor/diagrams/source/parser.ts`, and `src/features/editor/diagrams/source/generator.ts`. Browser persistence is coordinated by `src/features/editor/persistence/saveCoordinator.ts` against an editor API client; the Node API server and persistence backend are `scripts/editor/editorApiServer.ts` and `scripts/editor/editorPersistenceBackend.ts`. The API has container/Fly deployment artifacts: `Dockerfile.editor-api` and `fly.editor-api.toml`.

#### Formal verification and delivery
Lean 4 formalizes the geometry basis under `lean/Matematika.lean` and `lean/Matematika/Geometry/Hilbert/`. Repository scripts generate a Lean-derived graph and validate correspondence between formal proofs and MDX via `scripts/core/generate-lean-graph.ts` and `scripts/core/validate-bridge-phase.ts`. The main runtime stack is React 19, TypeScript, Vite/Rollup, Wouter, MDX/KaTeX, Zod, and force-graph/d3; CI and deployment are defined in `.github/workflows/ci.yml`, `.github/workflows/deploy.yml`, and `.github/workflows/deploy-editor-api.yml`.

Main entry points: [`src/pages/TheoremPage.tsx`](https://github.com/izaro-c/matematika/blob/main/src/pages/TheoremPage.tsx) (Content pages), [`src/entities/content/ContentStore.ts`](https://github.com/izaro-c/matematika/blob/main/src/entities/content/ContentStore.ts) (Content store), [`src/app/routes/AppRouter.tsx`](https://github.com/izaro-c/matematika/blob/main/src/app/routes/AppRouter.tsx) (Route dispatcher), [`src/widgets/mdx/MDXBlocks.tsx`](https://github.com/izaro-c/matematika/blob/main/src/widgets/mdx/MDXBlocks.tsx) (MDX component boundary)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser application"]
  node_main["Browser entry<br/>React bootstrap<br/>[main.tsx]"]
  node_app["Global providers<br/>App shell<br/>[App.tsx]"]
  node_router["Route dispatcher<br/>Wouter routes<br/>[AppRouter.tsx]"]
  node_content_pages["Content pages<br/>Reader pages<br/>[TheoremPage.tsx]"]
  node_graph_pages["Graph pages<br/>Graph views<br/>[GraphPage.tsx]"]
  node_mdx_blocks["MDX component boundary<br/>MDX renderer<br/>[MDXBlocks.tsx]"]
  node_exercise_runtime["Exercise runtime<br/>Interactive exercises"]
end

subgraph group_knowledge["Content and knowledge"]
  node_content_store["Content store<br/>MDX loader<br/>[ContentStore.ts]"]
  node_mdx_content[("MDX content database<br/>Filesystem content")]
  node_content_schema["Content schemas and search<br/>Metadata API<br/>[schemas.ts]"]
  node_semantic_graph{{"Semantic graph<br/>Graph model<br/>[Grafo.ts]"}}
  node_graph_data["Graph structure<br/>Generated graph data"]
  node_graph_feature["Knowledge graph feature<br/>Graph processing"]
  node_progress["Study progress<br/>Learning state"]
end

subgraph group_diagrams["Diagram platform"]
  node_diagram_spec["Diagram specification<br/>Versioned schema<br/>[schema.ts]"]
  node_diagram_runtime["Diagram renderer<br/>Publication runtime"]
end

subgraph group_authoring["Authoring and persistence"]
  node_editor_core["Editor document core<br/>Lossless MDX editor<br/>[useEditorCore.ts]"]
  node_diagram_workbench["Diagram workbench<br/>Editable diagram state<br/>[reducer.ts]"]
  node_save_coordinator["Save coordinator<br/>Browser persistence<br/>[saveCoordinator.ts]"]
  node_editor_api["Editor API service<br/>Node API server<br/>[editorApiServer.ts]"]
end

subgraph group_formal["Formal verification and delivery"]
  node_lean["Lean geometry basis<br/>Lean 4 formalization<br/>[Matematika.lean]"]
  node_bridge_validation["Formal-content bridge<br/>Validation pipeline"]
end

node_main --> node_app
node_app --> node_router
node_router -->|"content routes"| node_content_pages
node_router -->|"graph and editor routes"| node_graph_pages
node_content_pages -->|"loads articles"| node_content_store
node_content_store -->|"reads MDX"| node_mdx_content
node_content_store -->|"validates metadata"| node_content_schema
node_content_pages -->|"renders MDX"| node_mdx_blocks
node_mdx_blocks -->|"embeds exercises"| node_exercise_runtime
node_content_store -->|"semantic links"| node_semantic_graph
node_graph_data -->|"graph structure"| node_semantic_graph
node_semantic_graph -->|"processed for views"| node_graph_feature
node_graph_feature -->|"renders exploration"| node_graph_pages
node_content_pages -->|"records study state"| node_progress
node_mdx_blocks -->|"renders diagrams"| node_diagram_runtime
node_diagram_runtime -->|"interprets spec"| node_diagram_spec
node_graph_pages -->|"editor route"| node_editor_core
node_editor_core -->|"edits diagram blocks"| node_diagram_workbench
node_diagram_workbench -->|"uses shared semantics"| node_diagram_spec
node_editor_core -->|"saves source edits"| node_save_coordinator
node_save_coordinator -->|"persistence API"| node_editor_api
node_lean -->|"formal proofs"| node_bridge_validation
node_bridge_validation -.->|"validates correspondence"| node_mdx_content
node_bridge_validation -->|"generates Lean graph"| node_graph_data

click node_main "https://github.com/izaro-c/matematika/blob/main/src/app/main.tsx"
click node_app "https://github.com/izaro-c/matematika/blob/main/src/app/App.tsx"
click node_router "https://github.com/izaro-c/matematika/blob/main/src/app/routes/AppRouter.tsx"
click node_content_pages "https://github.com/izaro-c/matematika/blob/main/src/pages/TheoremPage.tsx"
click node_graph_pages "https://github.com/izaro-c/matematika/blob/main/src/pages/GraphPage.tsx"
click node_content_store "https://github.com/izaro-c/matematika/blob/main/src/entities/content/ContentStore.ts"
click node_content_schema "https://github.com/izaro-c/matematika/blob/main/src/entities/content/schemas.ts"
click node_semantic_graph "https://github.com/izaro-c/matematika/blob/main/src/entities/graph/Grafo.ts"
click node_graph_data "https://github.com/izaro-c/matematika/blob/main/src/entities/graph/graph_structure.json"
click node_graph_feature "https://github.com/izaro-c/matematika/blob/main/src/features/graph/lib/knowledgeGraphBuilder.ts"
click node_progress "https://github.com/izaro-c/matematika/blob/main/src/features/progress/UserProgressStore.ts"
click node_mdx_blocks "https://github.com/izaro-c/matematika/blob/main/src/widgets/mdx/MDXBlocks.tsx"
click node_exercise_runtime "https://github.com/izaro-c/matematika/blob/main/src/features/exercises/ui/ExerciseContext.tsx"
click node_diagram_spec "https://github.com/izaro-c/matematika/blob/main/src/shared/diagrams/spec/schema.ts"
click node_diagram_runtime "https://github.com/izaro-c/matematika/blob/main/src/shared/diagrams/runtime/DiagramRenderer.tsx"
click node_editor_core "https://github.com/izaro-c/matematika/blob/main/src/features/editor/core/useEditorCore.ts"
click node_diagram_workbench "https://github.com/izaro-c/matematika/blob/main/src/features/editor/diagrams/state/reducer.ts"
click node_save_coordinator "https://github.com/izaro-c/matematika/blob/main/src/features/editor/persistence/saveCoordinator.ts"
click node_editor_api "https://github.com/izaro-c/matematika/blob/main/scripts/editor/editorApiServer.ts"
click node_lean "https://github.com/izaro-c/matematika/blob/main/lean/Matematika.lean"
click node_bridge_validation "https://github.com/izaro-c/matematika/blob/main/scripts/core/validate-bridge-phase.ts"

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_main,node_app,node_router,node_content_pages,node_graph_pages,node_mdx_blocks,node_exercise_runtime toneBlue
class node_content_store,node_mdx_content,node_content_schema,node_semantic_graph,node_graph_data,node_graph_feature,node_progress toneAmber
class node_diagram_spec,node_diagram_runtime toneMint
class node_editor_core,node_diagram_workbench,node_save_coordinator,node_editor_api toneRose
class node_lean,node_bridge_validation toneIndigo
```

## Components

### Browser application

- [Browser entry](https://github.com/izaro-c/matematika/blob/main/src/app/main.tsx): React bootstrap · `src/app/main.tsx`
- [Global providers](https://github.com/izaro-c/matematika/blob/main/src/app/App.tsx): App shell · `src/app/App.tsx`
- [Route dispatcher](https://github.com/izaro-c/matematika/blob/main/src/app/routes/AppRouter.tsx): Wouter routes · `src/app/routes/AppRouter.tsx`
- [Content pages](https://github.com/izaro-c/matematika/blob/main/src/pages/TheoremPage.tsx): Reader pages · Theorem pages render published mathematical content. · `src/pages/TheoremPage.tsx`
- [Graph pages](https://github.com/izaro-c/matematika/blob/main/src/pages/GraphPage.tsx): Graph views · Includes semantic graph and editor page entry points. · `src/pages/GraphPage.tsx`
- [MDX component boundary](https://github.com/izaro-c/matematika/blob/main/src/widgets/mdx/MDXBlocks.tsx): MDX renderer · Maps authored MDX to shared interactive reader blocks. · `src/widgets/mdx/MDXBlocks.tsx`
- [Exercise runtime](https://github.com/izaro-c/matematika/blob/main/src/features/exercises/ui/ExerciseContext.tsx): Interactive exercises · `src/features/exercises/ui/ExerciseContext.tsx`

### Content and knowledge

- [Content store](https://github.com/izaro-c/matematika/blob/main/src/entities/content/ContentStore.ts): MDX loader · Loads and validates authored documents while tolerating unresolved editorial references. · `src/entities/content/ContentStore.ts`
- **MDX content database**: Filesystem content
- [Content schemas and search](https://github.com/izaro-c/matematika/blob/main/src/entities/content/schemas.ts): Metadata API · `src/entities/content/schemas.ts`
- [Semantic graph](https://github.com/izaro-c/matematika/blob/main/src/entities/graph/Grafo.ts): Graph model · `src/entities/graph/Grafo.ts`
- [Graph structure](https://github.com/izaro-c/matematika/blob/main/src/entities/graph/graph_structure.json): Generated graph data · `src/entities/graph/graph_structure.json`
- [Knowledge graph feature](https://github.com/izaro-c/matematika/blob/main/src/features/graph/lib/knowledgeGraphBuilder.ts): Graph processing · Builds graph data and offloads processing to a worker. · `src/features/graph/lib/knowledgeGraphBuilder.ts`
- [Study progress](https://github.com/izaro-c/matematika/blob/main/src/features/progress/UserProgressStore.ts): Learning state · `src/features/progress/UserProgressStore.ts`

### Diagram platform

- [Diagram specification](https://github.com/izaro-c/matematika/blob/main/src/shared/diagrams/spec/schema.ts): Versioned schema · Shared authored geometry semantics and migrations. · `src/shared/diagrams/spec/schema.ts`
- [Diagram renderer](https://github.com/izaro-c/matematika/blob/main/src/shared/diagrams/runtime/DiagramRenderer.tsx): Publication runtime · Renders declarative diagrams through the JSXGraph adapter. · `src/shared/diagrams/runtime/DiagramRenderer.tsx`

### Authoring and persistence

- [Editor document core](https://github.com/izaro-c/matematika/blob/main/src/features/editor/core/useEditorCore.ts): Lossless MDX editor · Parses, projects, and applies source edits. · `src/features/editor/core/useEditorCore.ts`
- [Diagram workbench](https://github.com/izaro-c/matematika/blob/main/src/features/editor/diagrams/state/reducer.ts): Editable diagram state · Converts between diagram source and editable state. · `src/features/editor/diagrams/state/reducer.ts`
- [Save coordinator](https://github.com/izaro-c/matematika/blob/main/src/features/editor/persistence/saveCoordinator.ts): Browser persistence · `src/features/editor/persistence/saveCoordinator.ts`
- [Editor API service](https://github.com/izaro-c/matematika/blob/main/scripts/editor/editorApiServer.ts): Node API server · Persists authoring documents through the backend. · `scripts/editor/editorApiServer.ts`

### Formal verification and delivery

- [Lean geometry basis](https://github.com/izaro-c/matematika/blob/main/lean/Matematika.lean): Lean 4 formalization · `lean/Matematika.lean`
- [Formal-content bridge](https://github.com/izaro-c/matematika/blob/main/scripts/core/validate-bridge-phase.ts): Validation pipeline · Generates a Lean graph and checks proof-to-MDX correspondence. · `scripts/core/validate-bridge-phase.ts`

## Connections

- Browser entry → Global providers
- Global providers → Route dispatcher
- Route dispatcher → Content pages: content routes
- Route dispatcher → Graph pages: graph and editor routes
- Content pages → Content store: loads articles
- Content store → MDX content database: reads MDX
- Content store → Content schemas and search: validates metadata
- Content pages → MDX component boundary: renders MDX
- MDX component boundary → Exercise runtime: embeds exercises
- Content store → Semantic graph: semantic links
- Graph structure → Semantic graph: graph structure
- Semantic graph → Knowledge graph feature: processed for views
- Knowledge graph feature → Graph pages: renders exploration
- Content pages → Study progress: records study state
- MDX component boundary → Diagram renderer: renders diagrams
- Diagram renderer → Diagram specification: interprets spec
- Graph pages → Editor document core: editor route
- Editor document core → Diagram workbench: edits diagram blocks
- Diagram workbench → Diagram specification: uses shared semantics
- Editor document core → Save coordinator: saves source edits
- Save coordinator → Editor API service: persistence API
- Lean geometry basis → Formal-content bridge: formal proofs
- Formal-content bridge → MDX content database: validates correspondence
- Formal-content bridge → Graph structure: generates Lean graph