# s0t0e0f0a0n/molecular-merge-and-match architecture

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

- Interactive diagram: https://gitdiagram.com/s0t0e0f0a0n/molecular-merge-and-match
- Repository: https://github.com/s0t0e0f0a0n/molecular-merge-and-match

## Overview

Molecular Merge and Match is a desktop-hosted NMR structure-elucidation learning tool. Students load an exercise, select or create molecular fragments, associate fragments with ¹H/¹³C peaks, merge fragments into a candidate molecule, and check the result against the exercise solution. The frontend also provides exercise authoring/import, spectra viewing, progress and logbook features, and settings. Electron starts the local API backend; the API serves exercise and chemistry data backed by SQLite. The README documents additional domain capabilities whose detailed implementation was not sampled, so their internal wiring is shown only where supported by the API structure.

Main entry points: [`frontend/src/features/layout/MolecularBookkeepingPage.tsx`](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/layout/MolecularBookkeepingPage.tsx) (Bookkeeping workspace), [`backend/app/db/session.py`](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/db/session.py) (Database session), [`frontend/src/features/molecule/MoleculeWorkspace.tsx`](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/molecule/MoleculeWorkspace.tsx) (Fragment editing), [`backend/app/api/warnings.py`](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/api/warnings.py) (Warning checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop runtime"]
  node_electron["Electron host<br/>[main.js]"]
  node_frontend["React application<br/>[App.tsx]"]
end

subgraph group_learning["Elucidation workflow"]
  node_exercise_page["Bookkeeping workspace"]
  node_exercise_context["Exercise state"]
  node_spectra["Spectra viewing"]
  node_fragment_editor["Fragment editing"]
  node_fragment_hook["Fragment operations<br/>[useFragments.ts]"]
  node_predefined["Fragment library"]
  node_linking["Peak-fragment linking<br/>[useLinking.ts]"]
  node_working_strip["Working fragments"]
  node_merge["Molecule merging<br/>[mergeFragments.ts]"]
  node_solution["Candidate solution"]
  node_warnings["Chemistry warnings"]
end

subgraph group_support["Learning support"]
  node_history["Logbook and progress<br/>[LogbookPanel.tsx]"]
  node_statistics["Statistics"]
  node_exercise_tools["Exercise authoring/import"]
  node_settings["Settings<br/>[SettingsPanel.tsx]"]
end

subgraph group_backend["API and persistence"]
  node_backend_app["FastAPI application<br/>[main.py]"]
  node_exercise_api["Exercise management<br/>[exercises.py]"]
  node_fragment_api["Fragment API<br/>[fragments.py]"]
  node_predefined_api["Predefined fragments"]
  node_solution_api["Solution API"]
  node_warning_api["Warning checks<br/>[warnings.py]"]
  node_chem_calc["Chemistry calculations<br/>[calculation.py]"]
  node_logbook_api["Logbook API<br/>[logbook.py]"]
  node_statistics_api["Statistics API<br/>[statistics.py]"]
  node_settings_api["Settings API<br/>[settings.py]"]
  node_db_session["Database session<br/>[session.py]"]
  node_db[("SQLite data<br/>[models.py]")]
end

node_student(("Student"))

node_student -->|"uses"| node_frontend
node_electron -->|"starts backend"| node_backend_app
node_frontend -->|"renders"| node_exercise_page
node_exercise_page -->|"reads exercise state"| node_exercise_context
node_exercise_page -->|"shows spectra"| node_spectra
node_exercise_page -->|"opens editor"| node_fragment_editor
node_exercise_page -->|"shows fragments"| node_working_strip
node_exercise_page -->|"manages links"| node_linking
node_exercise_page -->|"presents candidate"| node_solution
node_fragment_editor -->|"edits fragments"| node_fragment_hook
node_fragment_hook -->|"fetches and mutates"| node_fragment_api
node_fragment_editor -->|"selects fragments"| node_predefined
node_predefined -->|"searches library"| node_predefined_api
node_working_strip -->|"merges structures"| node_merge
node_exercise_page -->|"checks assignments"| node_warnings
node_warnings -->|"submits checks"| node_warning_api
node_warning_api -->|"calculates chemistry"| node_chem_calc
node_exercise_page -->|"loads exercises"| node_exercise_api
node_solution -->|"stores candidate"| node_solution_api
node_history -->|"loads progress"| node_logbook_api
node_statistics -->|"requests statistics"| node_statistics_api
node_exercise_tools -->|"creates or imports"| node_exercise_api
node_settings -->|"reads and updates"| node_settings_api
node_backend_app -->|"initializes database"| node_db_session
node_exercise_api -->|"accesses records"| node_db_session
node_fragment_api -->|"accesses records"| node_db_session
node_predefined_api -->|"reads library"| node_db_session
node_solution_api -->|"accesses records"| node_db_session
node_logbook_api -->|"accesses records"| node_db_session
node_statistics_api -->|"accesses records"| node_db_session
node_settings_api -->|"accesses records"| node_db_session
node_warning_api -->|"reads exercise data"| node_db_session
node_db_session -->|"reads and writes"| node_db

click node_electron "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/main.js"
click node_frontend "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/App.tsx"
click node_backend_app "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/main.py"
click node_exercise_page "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/layout/MolecularBookkeepingPage.tsx"
click node_exercise_api "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/api/exercises.py"
click node_exercise_context "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/context/ExerciseDataContext.tsx"
click node_spectra "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/viewingSpectra/SpectraPrototype.tsx"
click node_fragment_editor "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/molecule/MoleculeWorkspace.tsx"
click node_fragment_hook "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/hooks/useFragments.ts"
click node_fragment_api "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/api/fragments.py"
click node_predefined "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/molecule/PredefinedFragmentMenu.tsx"
click node_predefined_api "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/api/predefined_fragments.py"
click node_linking "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/hooks/useLinking.ts"
click node_working_strip "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/linking/WorkingFragmentsStrip.tsx"
click node_merge "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/utils/mergeFragments.ts"
click node_solution "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/solution/WorkingSolutionPanel.tsx"
click node_solution_api "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/api/working_solution.py"
click node_warnings "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/hooks/useLinkedFragmentWarnings.ts"
click node_warning_api "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/api/warnings.py"
click node_chem_calc "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/core/calculation.py"
click node_history "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/history/LogbookPanel.tsx"
click node_logbook_api "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/api/logbook.py"
click node_statistics "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/statistics/StatisticsPanel.tsx"
click node_statistics_api "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/api/statistics.py"
click node_exercise_tools "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/exercises/ExerciseCreationForm.tsx"
click node_settings "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/settings/SettingsPanel.tsx"
click node_settings_api "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/api/settings.py"
click node_db_session "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/db/session.py"
click node_db "https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/db/models.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_electron,node_frontend toneBlue
class node_exercise_page,node_exercise_context,node_spectra,node_fragment_editor,node_fragment_hook,node_predefined,node_linking,node_working_strip,node_merge,node_solution,node_warnings toneAmber
class node_history,node_statistics,node_exercise_tools,node_settings toneMint
class node_backend_app,node_exercise_api,node_fragment_api,node_predefined_api,node_solution_api,node_warning_api,node_chem_calc,node_logbook_api,node_statistics_api,node_settings_api,node_db_session,node_db toneRose
class node_student toneIndigo
```

## Components

### Desktop runtime

- [Electron host](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/main.js): `main.js`
- [React application](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### Elucidation workflow

- [Bookkeeping workspace](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/layout/MolecularBookkeepingPage.tsx): `frontend/src/features/layout/MolecularBookkeepingPage.tsx`
- [Exercise state](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/context/ExerciseDataContext.tsx): `frontend/src/context/ExerciseDataContext.tsx`
- [Spectra viewing](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/viewingSpectra/SpectraPrototype.tsx): `frontend/src/features/viewingSpectra/SpectraPrototype.tsx`
- [Fragment editing](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/molecule/MoleculeWorkspace.tsx): `frontend/src/features/molecule/MoleculeWorkspace.tsx`
- [Fragment operations](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/hooks/useFragments.ts): `frontend/src/hooks/useFragments.ts`
- [Fragment library](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/molecule/PredefinedFragmentMenu.tsx): `frontend/src/features/molecule/PredefinedFragmentMenu.tsx`
- [Peak-fragment linking](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/hooks/useLinking.ts): `frontend/src/hooks/useLinking.ts`
- [Working fragments](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/linking/WorkingFragmentsStrip.tsx): `frontend/src/features/linking/WorkingFragmentsStrip.tsx`
- [Molecule merging](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/utils/mergeFragments.ts): `frontend/src/utils/mergeFragments.ts`
- [Candidate solution](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/solution/WorkingSolutionPanel.tsx): `frontend/src/features/solution/WorkingSolutionPanel.tsx`
- [Chemistry warnings](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/hooks/useLinkedFragmentWarnings.ts): `frontend/src/hooks/useLinkedFragmentWarnings.ts`

### Learning support

- [Logbook and progress](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/history/LogbookPanel.tsx): `frontend/src/features/history/LogbookPanel.tsx`
- [Statistics](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/statistics/StatisticsPanel.tsx): `frontend/src/features/statistics/StatisticsPanel.tsx`
- [Exercise authoring/import](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/exercises/ExerciseCreationForm.tsx): `frontend/src/features/exercises/ExerciseCreationForm.tsx`
- [Settings](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/frontend/src/features/settings/SettingsPanel.tsx): `frontend/src/features/settings/SettingsPanel.tsx`

### API and persistence

- [FastAPI application](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/main.py): `backend/app/main.py`
- [Exercise management](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/api/exercises.py): `backend/app/api/exercises.py`
- [Fragment API](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/api/fragments.py): `backend/app/api/fragments.py`
- [Predefined fragments](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/api/predefined_fragments.py): `backend/app/api/predefined_fragments.py`
- [Solution API](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/api/working_solution.py): `backend/app/api/working_solution.py`
- [Warning checks](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/api/warnings.py): `backend/app/api/warnings.py`
- [Chemistry calculations](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/core/calculation.py): `backend/app/core/calculation.py`
- [Logbook API](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/api/logbook.py): `backend/app/api/logbook.py`
- [Statistics API](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/api/statistics.py): `backend/app/api/statistics.py`
- [Settings API](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/api/settings.py): `backend/app/api/settings.py`
- [Database session](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [SQLite data](https://github.com/s0t0e0f0a0n/molecular-merge-and-match/blob/main/backend/app/db/models.py): `backend/app/db/models.py`

### Other components

- **Student**

## Connections

- Student → React application: uses
- Electron host → FastAPI application: starts backend
- React application → Bookkeeping workspace: renders
- Bookkeeping workspace → Exercise state: reads exercise state
- Bookkeeping workspace → Spectra viewing: shows spectra
- Bookkeeping workspace → Fragment editing: opens editor
- Bookkeeping workspace → Working fragments: shows fragments
- Bookkeeping workspace → Peak-fragment linking: manages links
- Bookkeeping workspace → Candidate solution: presents candidate
- Fragment editing → Fragment operations: edits fragments
- Fragment operations → Fragment API: fetches and mutates
- Fragment editing → Fragment library: selects fragments
- Fragment library → Predefined fragments: searches library
- Working fragments → Molecule merging: merges structures
- Bookkeeping workspace → Chemistry warnings: checks assignments
- Chemistry warnings → Warning checks: submits checks
- Warning checks → Chemistry calculations: calculates chemistry
- Bookkeeping workspace → Exercise management: loads exercises
- Candidate solution → Solution API: stores candidate
- Logbook and progress → Logbook API: loads progress
- Statistics → Statistics API: requests statistics
- Exercise authoring/import → Exercise management: creates or imports
- Settings → Settings API: reads and updates
- FastAPI application → Database session: initializes database
- Exercise management → Database session: accesses records
- Fragment API → Database session: accesses records
- Predefined fragments → Database session: reads library
- Solution API → Database session: accesses records
- Logbook API → Database session: accesses records
- Statistics API → Database session: accesses records
- Settings API → Database session: accesses records
- Warning checks → Database session: reads exercise data
- Database session → SQLite data: reads and writes