# mizcausevic-dev/open-problems-atlas architecture

> Architecture diagram of the GitHub repository mizcausevic-dev/open-problems-atlas, 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/mizcausevic-dev/open-problems-atlas
- Repository: https://github.com/mizcausevic-dev/open-problems-atlas

## Overview

#### Purpose and principal workflow

Open Problems Atlas is a static, local-first mathematics reference and research workspace: people browse and search a curated problem list, inspect problem details, run mathematical tools, and keep private notes and tracking data in their browser. The primary workflow starts when a **visitor** opens the deployed site; the browser loads the app, whose hash-routed views read the problem corpus and local state. There is no backend or account system. Separate build scripts prepare the problem data and static glossary and quiz pages.

#### Components

##### Application and navigation

- **Visitor** — `null` repository path. A person using the deployed site initiates the main workflow by opening it and interacting with its views and tools.
- **React bootstrap and offline registration** — `src/main.tsx`. Mounts the app and, in production on HTTP(S), registers the service worker.
- **Application shell and route switch** — `src/App.tsx`. Provides navigation and the command palette, reads the current route, and selects the corresponding app view.
- **Hash router and URL state** — `src/lib/router.ts`. Parses hash routes and query parameters and updates the URL for navigation and shareable view state.

##### Problem atlas and reference content

- **Generated problem corpus** — `scripts/build-dataset.mjs`. Parses the documented Wikipedia source article into the generated dataset used by the atlas; the generated output is not present in the supplied tree.
- **Problem browsing and detail views** — `src/views/AtlasView.tsx`. The atlas view presents the problem list and its search/filter workflow; other problem-focused views in `src/views/` cover overview, details, collections, timeline, and dashboard. Their exact data wiring was not sampled.
- **Search and filtering** — `src/lib/search.ts`. Ranks problem matches and applies status, field, tracking, and sort choices; tracking filters are supported by the module’s state model.
- **Glossary content and build input** — `src/data/glossary.mjs`. Supplies hand-authored definitions and explanatory notes for generated static glossary pages.
- **Quiz content** — `src/data/quiz.mjs`. Supplies quiz material; README documents a build-generated static quiz with explanations and glossary links.

##### Research workspace and local state

- **Journal editing surface** — `src/components/MathEditor.tsx`. Edits notes as plain LaTeX text, with insertion and autocomplete aids, supporting preview and export-friendly note content.
- **LaTeX editing primitives** — `src/lib/latex/insert.ts`. Implements pure text and selection operations used by the editor.
- **Local research store** — `src/lib/storage.ts`. Hydrates and persists user data in browser local storage, exposes observable updates, and handles attachment accounting and vault-mode encryption.
- **Browser cryptography** — `src/lib/crypto.ts`. Provides the encryption/decryption functions imported by the store; the README documents AES-GCM encryption with a PBKDF2-derived key.

##### Mathematical lab

- **Lab views and tool coordination** — `src/views/LabView.tsx`. Selects and configures lab tools; the sampled code shows URL-backed plotting inputs and a covering-tool view.
- **Math expression context** — `src/lib/math/mathContext.ts`. Assembles app-specific functions from arithmetic, prime, zeta, and Collatz kernels for use by expressions.
- **Math computation kernels** — `src/lib/math/expression.ts`. The tree identifies the expression engine; separate modules under `src/lib/math/` implement mathematical domains including primes, zeta, Collatz, and covering sets. The sampled context confirms calls to several kernels, but not all tool-to-kernel wiring.

##### Static-site offline and generated pages

- **Service worker** — `public/sw.js`. Caches the app shell and same-origin resources and provides navigation fallbacks for offline use.
- **Build-time page and asset generation** — `scripts/build-glossary.mjs`. The build command also invokes quiz, SEO, and precache scripts; those build steps generate static pages and offline assets, but their detailed behavior was not sampled.

#### Relationships

- **Visitor -> React bootstrap and offline registration**: opens the deployed site; the bootstrap mounts the application in the browser.
- **React bootstrap and offline registration -> Application shell and route switch**: renders the app inside the React root.
- **Application shell and route switch -> Hash router and URL state**: reads route and query state and uses navigation helpers.
- **Application shell and route switch -> Problem browsing and detail views**: selects views according to the parsed route.
- **Problem browsing and detail views -> Search and filtering**: uses problem search and filter behavior; precise call sites were not sampled.
- **scripts/build-dataset.mjs -> Generated problem corpus**: parses the documented source article to generate the problem data.
- **scripts/build-glossary.mjs -> Glossary content and build input**: uses glossary material in the documented static-page build.
- **Application shell and route switch -> Journal editing surface**: the app includes a journal route; exact view-level wiring was not sampled.
- **Journal editing surface -> LaTeX editing primitives**: imports text insertion, selection, and autocomplete helpers.
- **Journal editing surface -> Local research store**: the journal is documented as private browser data; the precise editor-to-store call site was not sampled.
- **Local research store -> Browser cryptography**: calls encryption when saving vault data and decryption when unlocking it.
- **Lab views and tool coordination -> Hash router and URL state**: writes plot expressions and ranges to shareable URL state.
- **Lab views and tool coordination -> Math expression context**: supports plot-based lab computations; the precise call site is not in the excerpt.
- **Math expression context -> Math computation kernels**: invokes arithmetic-table, sieve, prime-counting, logarithmic-integral, zeta, and Collatz functions.
- **React bootstrap and offline registration -> Service worker**: registers the worker in production for eligible origins.
- **Service worker -> Browser cache**: stores same-origin responses and serves cached resources or navigation fallbacks offline.

#### Coverage limits

The supplied source excerpts are partial. Runtime dataset imports, detailed view-to-store wiring, the full tool dispatch for the lab, and individual build-script implementations could not be established directly. The README documents those product behaviors, but unsupported call-level connections are left unspecified.

Main entry points: [`src/App.tsx`](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/App.tsx) (Application shell), [`src/main.tsx`](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/main.tsx) (React bootstrap), [`src/components/MathEditor.tsx`](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/components/MathEditor.tsx) (Journal editor), [`src/views/LabView.tsx`](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/views/LabView.tsx) (Lab views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application and navigation"]
  node_visitor["Visitor<br/>external actor"]
  node_bootstrap["React bootstrap<br/>application entry"]
  node_app_shell["Application shell<br/>route switch"]
  node_router["Hash router<br/>URL state"]
end

subgraph group_atlas["Atlas and reference content"]
  node_dataset_builder["Dataset builder<br/>build script"]
  node_problem_corpus["Problem corpus<br/>generated data"]
  node_atlas_views["Problem views<br/>atlas UI"]
  node_search["Problem search<br/>filtering"]
  node_glossary_source["Glossary content<br/>reference data"]
end

subgraph group_workspace["Research workspace"]
  node_journal["Journal editor<br/>math editor"]
  node_latex_helpers["LaTeX helpers<br/>editing primitives"]
  node_local_store[("Local research store<br/>browser persistence")]
  node_crypto["Browser cryptography<br/>encryption"]
end

subgraph group_lab["Mathematical lab"]
  node_lab_views["Lab views<br/>tool coordination"]
  node_math_context["Math context<br/>expression functions"]
  node_math_kernels["Math kernels<br/>computation"]
end

subgraph group_offline["Build and offline support"]
  node_glossary_builder["Glossary builder<br/>build script"]
  node_service_worker["Service worker<br/>offline support"]
  node_browser_cache[("Browser cache<br/>offline storage")]
end

node_visitor -->|"opens site"| node_bootstrap
node_bootstrap -->|"mounts"| node_app_shell
node_app_shell -->|"reads and navigates"| node_router
node_app_shell -->|"selects views"| node_atlas_views
node_atlas_views -->|"searches and filters"| node_search
node_dataset_builder -->|"generates"| node_problem_corpus
node_glossary_builder -->|"uses content"| node_glossary_source
node_app_shell -->|"routes to"| node_journal
node_journal -->|"uses"| node_latex_helpers
node_journal -->|"stores notes"| node_local_store
node_local_store -->|"encrypts and decrypts"| node_crypto
node_lab_views -->|"writes URL state"| node_router
node_lab_views -->|"computes plots"| node_math_context
node_math_context -->|"invokes"| node_math_kernels
node_bootstrap -->|"registers"| node_service_worker
node_service_worker -->|"caches responses"| node_browser_cache

click node_bootstrap "https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/main.tsx"
click node_app_shell "https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/App.tsx"
click node_router "https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/lib/router.ts"
click node_dataset_builder "https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/scripts/build-dataset.mjs"
click node_atlas_views "https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/views/AtlasView.tsx"
click node_search "https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/lib/search.ts"
click node_glossary_source "https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/data/glossary.mjs"
click node_glossary_builder "https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/scripts/build-glossary.mjs"
click node_journal "https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/components/MathEditor.tsx"
click node_latex_helpers "https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/lib/latex/insert.ts"
click node_local_store "https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/lib/storage.ts"
click node_crypto "https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/lib/crypto.ts"
click node_lab_views "https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/views/LabView.tsx"
click node_math_context "https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/lib/math/mathContext.ts"
click node_math_kernels "https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/lib/math/expression.ts"
click node_service_worker "https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/public/sw.js"

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_visitor,node_bootstrap,node_app_shell,node_router toneBlue
class node_dataset_builder,node_problem_corpus,node_atlas_views,node_search,node_glossary_source toneAmber
class node_journal,node_latex_helpers,node_local_store,node_crypto toneMint
class node_lab_views,node_math_context,node_math_kernels toneRose
class node_glossary_builder,node_service_worker,node_browser_cache toneIndigo
```

## Components

### Application and navigation

- **Visitor**: external actor
- [React bootstrap](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/main.tsx): application entry · `src/main.tsx`
- [Application shell](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/App.tsx): route switch · `src/App.tsx`
- [Hash router](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/lib/router.ts): URL state · `src/lib/router.ts`

### Atlas and reference content

- [Dataset builder](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/scripts/build-dataset.mjs): build script · `scripts/build-dataset.mjs`
- **Problem corpus**: generated data
- [Problem views](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/views/AtlasView.tsx): atlas UI · `src/views/AtlasView.tsx`
- [Problem search](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/lib/search.ts): filtering · `src/lib/search.ts`
- [Glossary content](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/data/glossary.mjs): reference data · `src/data/glossary.mjs`

### Research workspace

- [Journal editor](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/components/MathEditor.tsx): math editor · `src/components/MathEditor.tsx`
- [LaTeX helpers](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/lib/latex/insert.ts): editing primitives · `src/lib/latex/insert.ts`
- [Local research store](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/lib/storage.ts): browser persistence · `src/lib/storage.ts`
- [Browser cryptography](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/lib/crypto.ts): encryption · `src/lib/crypto.ts`

### Mathematical lab

- [Lab views](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/views/LabView.tsx): tool coordination · `src/views/LabView.tsx`
- [Math context](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/lib/math/mathContext.ts): expression functions · `src/lib/math/mathContext.ts`
- [Math kernels](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/src/lib/math/expression.ts): computation · `src/lib/math/expression.ts`

### Build and offline support

- [Glossary builder](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/scripts/build-glossary.mjs): build script · `scripts/build-glossary.mjs`
- [Service worker](https://github.com/mizcausevic-dev/open-problems-atlas/blob/main/public/sw.js): offline support · `public/sw.js`
- **Browser cache**: offline storage

## Connections

- Visitor → React bootstrap: opens site
- React bootstrap → Application shell: mounts
- Application shell → Hash router: reads and navigates
- Application shell → Problem views: selects views
- Problem views → Problem search: searches and filters
- Dataset builder → Problem corpus: generates
- Glossary builder → Glossary content: uses content
- Application shell → Journal editor: routes to
- Journal editor → LaTeX helpers: uses
- Journal editor → Local research store: stores notes
- Local research store → Browser cryptography: encrypts and decrypts
- Lab views → Hash router: writes URL state
- Lab views → Math context: computes plots
- Math context → Math kernels: invokes
- React bootstrap → Service worker: registers
- Service worker → Browser cache: caches responses