# taewooopark/maglab architecture

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

- Interactive diagram: https://gitdiagram.com/taewooopark/maglab
- Repository: https://github.com/taewooopark/maglab

## Overview

MagLab is an AI-for-Science harness for magnetism and spintronics. Researchers enter through the CLI or interactive REPL; the orchestration layer uses configurable LLM backends and deterministic domain tools to coordinate research tasks, then supports inspection, provenance, and publication-ready outputs. Major branches include literature search, physics and simulation, analysis, figures, instrument workflows, lab memory, review, and authoring. The README documents these capabilities; sampled source confirms selected orchestration, LLM, simulation, and storage behavior, so some documented subsystem links are shown as unverified.

Main entry points: [`maglab/core/orchestrator.py`](https://github.com/taewooopark/maglab/blob/main/maglab/core/orchestrator.py) (Research Orchestrator), [`maglab/llm/tools.py`](https://github.com/taewooopark/maglab/blob/main/maglab/llm/tools.py) (Scientific Tools), [`maglab/authoring`](https://github.com/taewooopark/maglab/tree/main/maglab/authoring) (Writing and Presentations), [`maglab/commands/p6_authoring.py`](https://github.com/taewooopark/maglab/blob/main/maglab/commands/p6_authoring.py) (Authoring Commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Research Entry"]
  node_cli["CLI<br/>[cli.py]"]
  node_repl["Interactive REPL<br/>[repl.py]"]
end

subgraph group_harness["AI Harness"]
  node_orchestrator["Research Orchestrator<br/>[orchestrator.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_llm["LLM Backends<br/>[base.py]"]
  node_tools["Scientific Tools<br/>[tools.py]"]
  node_skills["Skills<br/>[skills.py]"]
  node_subagents["Subagents<br/>[subagents.py]"]
  node_budget["Budget Tracking<br/>[budget.py]"]
  node_manifest["Task Manifest<br/>[manifest.py]"]
end

subgraph group_science["Scientific Workflows"]
  node_physics["Physics and Materials<br/>[oracle.py]"]
  node_simulation["Multiscale Simulation<br/>[pipeline.py]"]
  node_analysis["Effect Fitting"]
  node_literature[("Literature Search<br/>[rag.py]")]
  node_figures["Figure Generation"]
end

subgraph group_lab["Lab Operations"]
  node_instruments["Instrument Workflows"]
  node_notebook[("Lab Notebook")]
  node_planning["Experiment Planning"]
  node_provenance[("Provenance")]
  node_gateway["Messaging Gateway<br/>[runner.py]"]
  node_workspace[("Workspace<br/>[workspace.py]")]
  node_atomic["Durable File Writes<br/>[atomic.py]"]
end

subgraph group_outputs["Research Outputs"]
  node_review["Manuscript Review"]
  node_honesty["Integrity Gate<br/>[honesty_gate.py]"]
  node_authoring["Writing and Presentations"]
  node_authoring_cli["Authoring Commands<br/>[p6_authoring.py]"]
  node_vault[("Research Data Vault<br/>[data_vault.py]")]
  node_presentation_catalog["Presentation Catalog<br/>[catalog.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs commands"| node_cli
node_researcher -->|"starts research"| node_repl
node_cli -->|"dispatches tasks"| node_orchestrator
node_repl -->|"submits turns"| node_orchestrator
node_orchestrator -->|"requests completions"| node_llm
node_orchestrator -->|"executes tools"| node_tools
node_orchestrator -->|"records usage"| node_budget
node_orchestrator -->|"loads task plans"| node_manifest
node_orchestrator -->|"loads settings"| node_config
node_orchestrator -.->|"uses capabilities"| node_skills
node_orchestrator -.->|"delegates work"| node_subagents
node_tools -.->|"invokes calculations"| node_physics
node_tools -.->|"invokes simulations"| node_simulation
node_researcher -.->|"searches evidence"| node_literature
node_researcher -.->|"fits measurements"| node_analysis
node_researcher -.->|"creates figures"| node_figures
node_researcher -.->|"prepares experiments"| node_instruments
node_researcher -.->|"records notes"| node_notebook
node_researcher -.->|"plans measurements"| node_planning
node_simulation -->|"records results"| node_provenance
node_analysis -.->|"tracks lineage"| node_provenance
node_literature -->|"supplies corpus context"| node_review
node_review -.->|"supports disclosure"| node_honesty
node_authoring_cli -->|"dispatches drafting"| node_authoring
node_authoring_cli -->|"controls gateway"| node_gateway
node_authoring -.->|"reads verified results"| node_vault
node_authoring -->|"uses slide catalog"| node_presentation_catalog
node_orchestrator -.->|"routes interactions"| node_gateway
node_workspace -.->|"stores durable state"| node_atomic

click node_cli "https://github.com/taewooopark/maglab/blob/main/maglab/cli.py"
click node_repl "https://github.com/taewooopark/maglab/blob/main/maglab/repl.py"
click node_orchestrator "https://github.com/taewooopark/maglab/blob/main/maglab/core/orchestrator.py"
click node_config "https://github.com/taewooopark/maglab/blob/main/maglab/config.py"
click node_llm "https://github.com/taewooopark/maglab/blob/main/maglab/llm/base.py"
click node_tools "https://github.com/taewooopark/maglab/blob/main/maglab/llm/tools.py"
click node_skills "https://github.com/taewooopark/maglab/blob/main/maglab/core/skills.py"
click node_subagents "https://github.com/taewooopark/maglab/blob/main/maglab/core/subagents.py"
click node_budget "https://github.com/taewooopark/maglab/blob/main/maglab/core/budget.py"
click node_manifest "https://github.com/taewooopark/maglab/blob/main/maglab/core/manifest.py"
click node_physics "https://github.com/taewooopark/maglab/blob/main/maglab/physics/oracle.py"
click node_simulation "https://github.com/taewooopark/maglab/blob/main/maglab/sim/pipeline.py"
click node_analysis "https://github.com/taewooopark/maglab/tree/main/maglab/analysis/effects"
click node_literature "https://github.com/taewooopark/maglab/blob/main/maglab/literature/rag.py"
click node_figures "https://github.com/taewooopark/maglab/tree/main/maglab/figure"
click node_instruments "https://github.com/taewooopark/maglab/tree/main/maglab/instrument"
click node_notebook "https://github.com/taewooopark/maglab/tree/main/maglab/lab/notebook"
click node_planning "https://github.com/taewooopark/maglab/tree/main/maglab/lab/planning"
click node_provenance "https://github.com/taewooopark/maglab/tree/main/maglab/provenance"
click node_review "https://github.com/taewooopark/maglab/tree/main/maglab/reviewer"
click node_honesty "https://github.com/taewooopark/maglab/blob/main/maglab/report/honesty_gate.py"
click node_authoring "https://github.com/taewooopark/maglab/tree/main/maglab/authoring"
click node_authoring_cli "https://github.com/taewooopark/maglab/blob/main/maglab/commands/p6_authoring.py"
click node_vault "https://github.com/taewooopark/maglab/blob/main/maglab/authoring/data_vault.py"
click node_presentation_catalog "https://github.com/taewooopark/maglab/blob/main/maglab/authoring/present/catalog.py"
click node_gateway "https://github.com/taewooopark/maglab/blob/main/maglab/gateway/runner.py"
click node_workspace "https://github.com/taewooopark/maglab/blob/main/maglab/workspace.py"
click node_atomic "https://github.com/taewooopark/maglab/blob/main/maglab/core/atomic.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_cli,node_repl toneBlue
class node_orchestrator,node_config,node_llm,node_tools,node_skills,node_subagents,node_budget,node_manifest toneAmber
class node_physics,node_simulation,node_analysis,node_literature,node_figures toneMint
class node_instruments,node_notebook,node_planning,node_provenance,node_gateway,node_workspace,node_atomic toneRose
class node_review,node_honesty,node_authoring,node_authoring_cli,node_vault,node_presentation_catalog,node_researcher toneIndigo
```

## Components

### Research Entry

- [CLI](https://github.com/taewooopark/maglab/blob/main/maglab/cli.py): `maglab/cli.py`
- [Interactive REPL](https://github.com/taewooopark/maglab/blob/main/maglab/repl.py): `maglab/repl.py`

### AI Harness

- [Research Orchestrator](https://github.com/taewooopark/maglab/blob/main/maglab/core/orchestrator.py): `maglab/core/orchestrator.py`
- [Configuration](https://github.com/taewooopark/maglab/blob/main/maglab/config.py): `maglab/config.py`
- [LLM Backends](https://github.com/taewooopark/maglab/blob/main/maglab/llm/base.py): `maglab/llm/base.py`
- [Scientific Tools](https://github.com/taewooopark/maglab/blob/main/maglab/llm/tools.py): `maglab/llm/tools.py`
- [Skills](https://github.com/taewooopark/maglab/blob/main/maglab/core/skills.py): `maglab/core/skills.py`
- [Subagents](https://github.com/taewooopark/maglab/blob/main/maglab/core/subagents.py): `maglab/core/subagents.py`
- [Budget Tracking](https://github.com/taewooopark/maglab/blob/main/maglab/core/budget.py): `maglab/core/budget.py`
- [Task Manifest](https://github.com/taewooopark/maglab/blob/main/maglab/core/manifest.py): `maglab/core/manifest.py`

### Scientific Workflows

- [Physics and Materials](https://github.com/taewooopark/maglab/blob/main/maglab/physics/oracle.py): `maglab/physics/oracle.py`
- [Multiscale Simulation](https://github.com/taewooopark/maglab/blob/main/maglab/sim/pipeline.py): `maglab/sim/pipeline.py`
- [Effect Fitting](https://github.com/taewooopark/maglab/tree/main/maglab/analysis/effects): `maglab/analysis/effects`
- [Literature Search](https://github.com/taewooopark/maglab/blob/main/maglab/literature/rag.py): `maglab/literature/rag.py`
- [Figure Generation](https://github.com/taewooopark/maglab/tree/main/maglab/figure): `maglab/figure`

### Lab Operations

- [Instrument Workflows](https://github.com/taewooopark/maglab/tree/main/maglab/instrument): `maglab/instrument`
- [Lab Notebook](https://github.com/taewooopark/maglab/tree/main/maglab/lab/notebook): `maglab/lab/notebook`
- [Experiment Planning](https://github.com/taewooopark/maglab/tree/main/maglab/lab/planning): `maglab/lab/planning`
- [Provenance](https://github.com/taewooopark/maglab/tree/main/maglab/provenance): `maglab/provenance`
- [Messaging Gateway](https://github.com/taewooopark/maglab/blob/main/maglab/gateway/runner.py): `maglab/gateway/runner.py`
- [Workspace](https://github.com/taewooopark/maglab/blob/main/maglab/workspace.py): `maglab/workspace.py`
- [Durable File Writes](https://github.com/taewooopark/maglab/blob/main/maglab/core/atomic.py): `maglab/core/atomic.py`

### Research Outputs

- [Manuscript Review](https://github.com/taewooopark/maglab/tree/main/maglab/reviewer): `maglab/reviewer`
- [Integrity Gate](https://github.com/taewooopark/maglab/blob/main/maglab/report/honesty_gate.py): `maglab/report/honesty_gate.py`
- [Writing and Presentations](https://github.com/taewooopark/maglab/tree/main/maglab/authoring): `maglab/authoring`
- [Authoring Commands](https://github.com/taewooopark/maglab/blob/main/maglab/commands/p6_authoring.py): `maglab/commands/p6_authoring.py`
- [Research Data Vault](https://github.com/taewooopark/maglab/blob/main/maglab/authoring/data_vault.py): `maglab/authoring/data_vault.py`
- [Presentation Catalog](https://github.com/taewooopark/maglab/blob/main/maglab/authoring/present/catalog.py): `maglab/authoring/present/catalog.py`

### Other components

- **Researcher**

## Connections

- Researcher → CLI: runs commands (evidence: `README.md`)
- Researcher → Interactive REPL: starts research (evidence: `README.md`)
- CLI → Research Orchestrator: dispatches tasks (evidence: `maglab/cli.py`)
- Interactive REPL → Research Orchestrator: submits turns (evidence: `README.md`)
- Research Orchestrator → LLM Backends: requests completions (evidence: `maglab/core/orchestrator.py`)
- Research Orchestrator → Scientific Tools: executes tools (evidence: `maglab/core/orchestrator.py`)
- Research Orchestrator → Budget Tracking: records usage (evidence: `maglab/core/orchestrator.py`)
- Research Orchestrator → Task Manifest: loads task plans (evidence: `maglab/core/orchestrator.py`)
- Research Orchestrator → Configuration: loads settings (evidence: `maglab/core/orchestrator.py`)
- Research Orchestrator → Skills: uses capabilities
- Research Orchestrator → Subagents: delegates work
- Scientific Tools → Physics and Materials: invokes calculations
- Scientific Tools → Multiscale Simulation: invokes simulations
- Researcher → Literature Search: searches evidence (evidence: `README.md`)
- Researcher → Effect Fitting: fits measurements (evidence: `README.md`)
- Researcher → Figure Generation: creates figures (evidence: `README.md`)
- Researcher → Instrument Workflows: prepares experiments (evidence: `README.md`)
- Researcher → Lab Notebook: records notes (evidence: `README.md`)
- Researcher → Experiment Planning: plans measurements (evidence: `README.md`)
- Multiscale Simulation → Provenance: records results (evidence: `maglab/sim/pipeline.py`)
- Effect Fitting → Provenance: tracks lineage (evidence: `README.md`)
- Literature Search → Manuscript Review: supplies corpus context (evidence: `maglab/reviewer/corpus_rag.py`)
- Manuscript Review → Integrity Gate: supports disclosure (evidence: `README.md`)
- Authoring Commands → Writing and Presentations: dispatches drafting (evidence: `maglab/commands/p6_authoring.py`)
- Authoring Commands → Messaging Gateway: controls gateway (evidence: `maglab/commands/p6_authoring.py`)
- Writing and Presentations → Research Data Vault: reads verified results (evidence: `maglab/authoring/present/slide_drafter.py`)
- Writing and Presentations → Presentation Catalog: uses slide catalog (evidence: `maglab/authoring/present/slide_drafter.py`)
- Research Orchestrator → Messaging Gateway: routes interactions (evidence: `maglab/core/orchestrator.py`)
- Workspace → Durable File Writes: stores durable state
