izaro-c/matematika

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.