# abd19990044-commits/chemistry-web-lab architecture

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

- Interactive diagram: https://gitdiagram.com/abd19990044-commits/chemistry-web-lab
- Repository: https://github.com/abd19990044-commits/chemistry-web-lab

## Overview

Chemistry Lab is a computational-chemistry web platform. Its primary workflow is to prepare a molecule or reaction, choose local/HPC execution (recommended) or optional Kaggle execution, submit an ORCA calculation, then parse and analyze results. The graph also preserves the documented molecular studio, reaction thermochemistry, spectroscopy, and dataset-export capabilities. Some feature branches are documented in the README but their implementation was not sampled; those links are shown only where the documentation supports them.

Main entry points: [`app.py`](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/app.py) (Web application), [`orca_orchestrator/service.py`](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/orca_orchestrator/service.py) (Kaggle orchestration), [`orca_engine/src/orca_engine/io.py`](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/orca_engine/src/orca_engine/io.py) (ORCA file reader), [`api/main.py`](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/api/main.py) (FastAPI layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web platform"]
  node_webapp["Web application<br/>[app.py]"]
  node_api["FastAPI layer<br/>[main.py]"]
  node_auth["Identity and access<br/>[auth_service.py]"]
end

subgraph group_chem["Chemistry workflows"]
  node_molecule["Molecule studio<br/>[chem_core.py]"]
  node_drawing["Structure drawing<br/>[drawing.py]"]
  node_reaction["Reaction workflow"]
end

subgraph group_execution["Execution backends"]
  node_localservice["Agent registry"]
  node_agent["Companion agent<br/>[agent.py]"]
  node_scheduler["HPC schedulers"]
  node_localorca["Local ORCA service"]
  node_worker["Local job worker"]
end

subgraph group_analysis["Scientific analysis"]
  node_engineio["ORCA file reader<br/>[io.py]"]
  node_parser["Output parser<br/>[parser.py]"]
  node_models["Scientific data models<br/>[models.py]"]
  node_spectra["Spectroscopy analysis<br/>[nmr.py]"]
  node_dataset["AI dataset export"]
end

subgraph group_cloud["Cloud and persistence"]
  node_kaggle["Kaggle runner<br/>[kaggle_runner.py]"]
  node_orchestrator["Kaggle orchestration<br/>[service.py]"]
  node_jobstore[("Job state store<br/>[store.py]")]
  node_controlplane["Cloud control plane<br/>[index.ts]"]
  node_kaggle_service["Kaggle service<br/>[kaggle_service.py]"]
end

node_user(("Researcher"))
node_orca["ORCA software"]

node_user -->|"uses"| node_webapp
node_user -->|"calls API"| node_api
node_api -->|"mounts legacy app"| node_webapp
node_webapp -->|"authenticates"| node_auth
node_webapp -->|"uses chemistry tools"| node_molecule
node_drawing -->|"exports structures"| node_engineio
node_webapp -->|"runs reaction workflows"| node_reaction
node_reaction -->|"loads ORCA results"| node_engineio
node_webapp -->|"pairs agents"| node_localservice
node_localservice -.->|"dispatches jobs"| node_agent
node_agent -->|"submits HPC jobs"| node_scheduler
node_scheduler -->|"runs calculations"| node_orca
node_webapp -->|"configures local runs"| node_localorca
node_localorca -->|"enqueues jobs"| node_worker
node_worker -->|"launches"| node_orca
node_webapp -->|"requests cloud runs"| node_kaggle_service
node_kaggle_service -.->|"delegates orchestration"| node_orchestrator
node_orchestrator -->|"submits kernels"| node_kaggle
node_orchestrator -->|"persists job state"| node_jobstore
node_orchestrator -.->|"syncs metadata"| node_controlplane
node_engineio -->|"parses output"| node_parser
node_parser -->|"builds records"| node_models
node_webapp -->|"loads analysis inputs"| node_engineio
node_webapp -->|"presents spectroscopy"| node_spectra
node_webapp -->|"exports training data"| node_dataset

click node_webapp "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/app.py"
click node_api "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/api/main.py"
click node_auth "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/services/auth_service.py"
click node_molecule "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/chem_core.py"
click node_drawing "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/chem_core/drawing.py"
click node_reaction "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/services/reaction_workflow_service.py"
click node_localservice "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/services/local_agent_service.py"
click node_agent "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/local_agent/agent.py"
click node_scheduler "https://github.com/abd19990044-commits/chemistry-web-lab/tree/main/local_agent/hpc"
click node_localorca "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/services/local_orca_service.py"
click node_worker "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/services/local_orca_worker.py"
click node_kaggle "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/kaggle_runner.py"
click node_orchestrator "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/orca_orchestrator/service.py"
click node_jobstore "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/orca_orchestrator/store.py"
click node_controlplane "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/cloudflare-control-plane/src/index.ts"
click node_engineio "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/orca_engine/src/orca_engine/io.py"
click node_parser "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/orca_engine/src/orca_engine/parser.py"
click node_models "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/orca_engine/src/orca_engine/models.py"
click node_spectra "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/orca_engine/src/orca_engine/nmr.py"
click node_dataset "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/tools/export_training_jsonl.py"
click node_kaggle_service "https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/services/kaggle_service.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_webapp,node_api,node_auth toneBlue
class node_molecule,node_drawing,node_reaction toneAmber
class node_localservice,node_agent,node_scheduler,node_localorca,node_worker toneMint
class node_engineio,node_parser,node_models,node_spectra,node_dataset toneRose
class node_kaggle,node_orchestrator,node_jobstore,node_controlplane,node_kaggle_service,node_user,node_orca toneIndigo
```

## Components

### Web platform

- [Web application](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/app.py): `app.py`
- [FastAPI layer](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/api/main.py): `api/main.py`
- [Identity and access](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/services/auth_service.py): `services/auth_service.py`

### Chemistry workflows

- [Molecule studio](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/chem_core.py): `chem_core.py`
- [Structure drawing](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/chem_core/drawing.py): `chem_core/drawing.py`
- [Reaction workflow](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/services/reaction_workflow_service.py): `services/reaction_workflow_service.py`

### Execution backends

- [Agent registry](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/services/local_agent_service.py): `services/local_agent_service.py`
- [Companion agent](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/local_agent/agent.py): `local_agent/agent.py`
- [HPC schedulers](https://github.com/abd19990044-commits/chemistry-web-lab/tree/main/local_agent/hpc): `local_agent/hpc`
- [Local ORCA service](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/services/local_orca_service.py): `services/local_orca_service.py`
- [Local job worker](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/services/local_orca_worker.py): `services/local_orca_worker.py`

### Scientific analysis

- [ORCA file reader](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/orca_engine/src/orca_engine/io.py): `orca_engine/src/orca_engine/io.py`
- [Output parser](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/orca_engine/src/orca_engine/parser.py): `orca_engine/src/orca_engine/parser.py`
- [Scientific data models](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/orca_engine/src/orca_engine/models.py): `orca_engine/src/orca_engine/models.py`
- [Spectroscopy analysis](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/orca_engine/src/orca_engine/nmr.py): `orca_engine/src/orca_engine/nmr.py`
- [AI dataset export](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/tools/export_training_jsonl.py): `tools/export_training_jsonl.py`

### Cloud and persistence

- [Kaggle runner](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/kaggle_runner.py): `kaggle_runner.py`
- [Kaggle orchestration](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/orca_orchestrator/service.py): `orca_orchestrator/service.py`
- [Job state store](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/orca_orchestrator/store.py): `orca_orchestrator/store.py`
- [Cloud control plane](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/cloudflare-control-plane/src/index.ts): `cloudflare-control-plane/src/index.ts`
- [Kaggle service](https://github.com/abd19990044-commits/chemistry-web-lab/blob/main/services/kaggle_service.py): `services/kaggle_service.py`

### Other components

- **Researcher**
- **ORCA software**

## Connections

- Researcher → Web application: uses (evidence: `README.md`)
- Researcher → FastAPI layer: calls API (evidence: `README.md`)
- FastAPI layer → Web application: mounts legacy app (evidence: `api/main.py`)
- Web application → Identity and access: authenticates (evidence: `app.py`)
- Web application → Molecule studio: uses chemistry tools (evidence: `app.py`)
- Structure drawing → ORCA file reader: exports structures (evidence: `chem_core/drawing.py`)
- Web application → Reaction workflow: runs reaction workflows (evidence: `app.py`)
- Reaction workflow → ORCA file reader: loads ORCA results (evidence: `services/reaction_workflow_service.py`)
- Web application → Agent registry: pairs agents (evidence: `app.py`)
- Agent registry → Companion agent: dispatches jobs (evidence: `README.md`)
- Companion agent → HPC schedulers: submits HPC jobs (evidence: `README.md`)
- HPC schedulers → ORCA software: runs calculations (evidence: `README.md`)
- Web application → Local ORCA service: configures local runs (evidence: `app.py`)
- Local ORCA service → Local job worker: enqueues jobs (evidence: `services/local_orca_worker.py`)
- Local job worker → ORCA software: launches (evidence: `services/local_orca_worker.py`)
- Web application → Kaggle service: requests cloud runs (evidence: `app.py`)
- Kaggle service → Kaggle orchestration: delegates orchestration
- Kaggle orchestration → Kaggle runner: submits kernels
- Kaggle orchestration → Job state store: persists job state (evidence: `orca_orchestrator/service.py`)
- Kaggle orchestration → Cloud control plane: syncs metadata
- ORCA file reader → Output parser: parses output (evidence: `orca_engine/src/orca_engine/io.py`)
- Output parser → Scientific data models: builds records (evidence: `orca_engine/src/orca_engine/parser.py`)
- Web application → ORCA file reader: loads analysis inputs (evidence: `app.py`)
- Web application → Spectroscopy analysis: presents spectroscopy (evidence: `README.md`)
- Web application → AI dataset export: exports training data (evidence: `README.md`)
