# moalimjaveed/mocs-cert architecture

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

- Interactive diagram: https://gitdiagram.com/moalimjaveed/mocs-cert
- Repository: https://github.com/moalimjaveed/mocs-cert

## Overview

MOCS-Cert is a molecular-dynamics trajectory query engine with a scientific workstation. A user submits a declarative query; the backend compiles and executes it against trajectory data and spatial indexes, refines uncertain intervals, and emits evidence that can be audited. The UI exposes query, visualization, timeline, certificate, benchmark, and workflow views. Workflow orchestration and ecosystem integrations form a separate capability. The README documents these capabilities; unsampled endpoint and frontend source limits which implementation-level links can be asserted.

Main entry points: [`backend/app/core/compiler_service.py`](https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/core/compiler_service.py) (Query compiler), [`backend/app/core/trajectory_service.py`](https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/core/trajectory_service.py) (Trajectory service), [`backend/app/main.py`](https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/api/websockets/query_stream.py`](https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/api/websockets/query_stream.py) (Query stream)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and execution"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_query_api["Query endpoint<br/>[query.py]"]
  node_stream_api["Query stream<br/>[query_stream.py]"]
  node_trajectory_service["Trajectory service"]
  node_workflow_api["Workflow endpoint<br/>[workflow.py]"]
  node_molecular_api["Molecular endpoints<br/>[molecular.py]"]
end

subgraph group_engine["Certified query engine"]
  node_compiler["Query compiler"]
  node_planner["Plan selector<br/>[plan_selector.py]"]
  node_trajectory_io["Trajectory I/O<br/>[mda_source.py]"]
  node_mci[("MCI index<br/>[reader.py]")]
  node_bounds["Periodic bounds<br/>[periodic_bounds.py]"]
  node_certificate["Certificate auditor<br/>[auditor.py]"]
end

subgraph group_science["Molecular analysis"]
end

subgraph group_workflow["Scientific workflows"]
  node_workflow_engine["Workflow engine<br/>[engine.py]"]
  node_workflow_pipelines["Workflow pipelines"]
  node_selection["Structural selection"]
  node_backend_registry["Backend ecosystem<br/>[registry.py]"]
end

subgraph group_workstation["Scientific workstation"]
  node_workstation["React workstation<br/>[App.tsx]"]
  node_query_editor["Query editor"]
  node_timeline["Refinement timeline"]
  node_proof_view["Certificate inspection"]
  node_molecular_view["Molecular viewer"]
  node_workflow_view["Workflow workspace"]
  node_benchmark_view["Benchmark view"]
end

node_researcher(("Researcher"))

node_researcher -->|"uses"| node_workstation
node_workstation -->|"edits queries"| node_query_editor
node_query_editor -->|"submits query"| node_query_api
node_api_app -->|"mounts route"| node_query_api
node_api_app -->|"mounts socket"| node_stream_api
node_api_app -->|"mounts route"| node_workflow_api
node_api_app -->|"mounts route"| node_molecular_api
node_query_api -->|"invokes"| node_compiler
node_stream_api -->|"refines blocks"| node_trajectory_service
node_stream_api -->|"compiles query"| node_compiler
node_compiler -->|"selects plan"| node_planner
node_compiler -->|"resolves trajectory"| node_trajectory_service
node_compiler -->|"computes bounds"| node_bounds
node_compiler -->|"reads index"| node_mci
node_compiler -->|"audits evidence"| node_certificate
node_trajectory_service -->|"loads blocks"| node_mci
node_trajectory_service -->|"computes PBC bounds"| node_bounds
node_trajectory_service -->|"opens source"| node_trajectory_io
node_timeline -.->|"requests refinement"| node_stream_api
node_proof_view -.->|"inspects proof"| node_certificate
node_molecular_view -.->|"loads structures"| node_molecular_api
node_researcher -->|"orchestrates workflows"| node_workflow_view
node_workflow_api -.->|"dispatches workflow"| node_workflow_engine
node_workflow_engine -->|"runs pipelines"| node_workflow_pipelines
node_workflow_engine -->|"discovers backends"| node_backend_registry
node_selection -.->|"supports selection"| node_workflow_pipelines
node_researcher -->|"reviews benchmarks"| node_benchmark_view

click node_api_app "https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/main.py"
click node_query_api "https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/api/endpoints/query.py"
click node_stream_api "https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/api/websockets/query_stream.py"
click node_trajectory_service "https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/core/trajectory_service.py"
click node_compiler "https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/core/compiler_service.py"
click node_planner "https://github.com/moalimjaveed/mocs-cert/blob/main/mocs/planner/plan_selector.py"
click node_trajectory_io "https://github.com/moalimjaveed/mocs-cert/blob/main/mocs/io/mda_source.py"
click node_mci "https://github.com/moalimjaveed/mocs-cert/blob/main/mocs/mci/reader.py"
click node_bounds "https://github.com/moalimjaveed/mocs-cert/blob/main/mocs/bounds/periodic_bounds.py"
click node_certificate "https://github.com/moalimjaveed/mocs-cert/blob/main/mocs/certificates/auditor.py"
click node_workflow_api "https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/api/endpoints/workflow.py"
click node_workflow_engine "https://github.com/moalimjaveed/mocs-cert/blob/main/mocs/workflow/engine.py"
click node_workflow_pipelines "https://github.com/moalimjaveed/mocs-cert/tree/main/mocs/workflow/pipelines"
click node_selection "https://github.com/moalimjaveed/mocs-cert/blob/main/mocs/workflow/pipelines/selection_pipeline.py"
click node_backend_registry "https://github.com/moalimjaveed/mocs-cert/blob/main/mocs/ecosystem/registry.py"
click node_workstation "https://github.com/moalimjaveed/mocs-cert/blob/main/frontend/src/App.tsx"
click node_query_editor "https://github.com/moalimjaveed/mocs-cert/blob/main/frontend/src/components/editor/MonacoQueryEditor.tsx"
click node_timeline "https://github.com/moalimjaveed/mocs-cert/blob/main/frontend/src/components/timeline/TimelineLattice.tsx"
click node_proof_view "https://github.com/moalimjaveed/mocs-cert/blob/main/frontend/src/components/proof/CertificateAuditorModal.tsx"
click node_molecular_view "https://github.com/moalimjaveed/mocs-cert/blob/main/frontend/src/components/viewer/MolecularViewport.tsx"
click node_workflow_view "https://github.com/moalimjaveed/mocs-cert/blob/main/frontend/src/components/views/WorkflowOrchestrationView.tsx"
click node_benchmark_view "https://github.com/moalimjaveed/mocs-cert/blob/main/frontend/src/components/views/ExecutionBenchmarksView.tsx"
click node_molecular_api "https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/api/endpoints/molecular.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_api_app,node_query_api,node_stream_api,node_trajectory_service,node_workflow_api,node_molecular_api toneBlue
class node_compiler,node_planner,node_trajectory_io,node_mci,node_bounds,node_certificate toneAmber
class node_workflow_engine,node_workflow_pipelines,node_selection,node_backend_registry toneRose
class node_workstation,node_query_editor,node_timeline,node_proof_view,node_molecular_view,node_workflow_view,node_benchmark_view,node_researcher toneIndigo
```

## Components

### API and execution

- [FastAPI application](https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/main.py): `backend/app/main.py`
- [Query endpoint](https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/api/endpoints/query.py): `backend/app/api/endpoints/query.py`
- [Query stream](https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/api/websockets/query_stream.py): `backend/app/api/websockets/query_stream.py`
- [Trajectory service](https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/core/trajectory_service.py): `backend/app/core/trajectory_service.py`
- [Workflow endpoint](https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/api/endpoints/workflow.py): `backend/app/api/endpoints/workflow.py`
- [Molecular endpoints](https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/api/endpoints/molecular.py): `backend/app/api/endpoints/molecular.py`

### Certified query engine

- [Query compiler](https://github.com/moalimjaveed/mocs-cert/blob/main/backend/app/core/compiler_service.py): `backend/app/core/compiler_service.py`
- [Plan selector](https://github.com/moalimjaveed/mocs-cert/blob/main/mocs/planner/plan_selector.py): `mocs/planner/plan_selector.py`
- [Trajectory I/O](https://github.com/moalimjaveed/mocs-cert/blob/main/mocs/io/mda_source.py): `mocs/io/mda_source.py`
- [MCI index](https://github.com/moalimjaveed/mocs-cert/blob/main/mocs/mci/reader.py): `mocs/mci/reader.py`
- [Periodic bounds](https://github.com/moalimjaveed/mocs-cert/blob/main/mocs/bounds/periodic_bounds.py): `mocs/bounds/periodic_bounds.py`
- [Certificate auditor](https://github.com/moalimjaveed/mocs-cert/blob/main/mocs/certificates/auditor.py): `mocs/certificates/auditor.py`

### Scientific workflows

- [Workflow engine](https://github.com/moalimjaveed/mocs-cert/blob/main/mocs/workflow/engine.py): `mocs/workflow/engine.py`
- [Workflow pipelines](https://github.com/moalimjaveed/mocs-cert/tree/main/mocs/workflow/pipelines): `mocs/workflow/pipelines`
- [Structural selection](https://github.com/moalimjaveed/mocs-cert/blob/main/mocs/workflow/pipelines/selection_pipeline.py): `mocs/workflow/pipelines/selection_pipeline.py`
- [Backend ecosystem](https://github.com/moalimjaveed/mocs-cert/blob/main/mocs/ecosystem/registry.py): `mocs/ecosystem/registry.py`

### Scientific workstation

- [React workstation](https://github.com/moalimjaveed/mocs-cert/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Query editor](https://github.com/moalimjaveed/mocs-cert/blob/main/frontend/src/components/editor/MonacoQueryEditor.tsx): `frontend/src/components/editor/MonacoQueryEditor.tsx`
- [Refinement timeline](https://github.com/moalimjaveed/mocs-cert/blob/main/frontend/src/components/timeline/TimelineLattice.tsx): `frontend/src/components/timeline/TimelineLattice.tsx`
- [Certificate inspection](https://github.com/moalimjaveed/mocs-cert/blob/main/frontend/src/components/proof/CertificateAuditorModal.tsx): `frontend/src/components/proof/CertificateAuditorModal.tsx`
- [Molecular viewer](https://github.com/moalimjaveed/mocs-cert/blob/main/frontend/src/components/viewer/MolecularViewport.tsx): `frontend/src/components/viewer/MolecularViewport.tsx`
- [Workflow workspace](https://github.com/moalimjaveed/mocs-cert/blob/main/frontend/src/components/views/WorkflowOrchestrationView.tsx): `frontend/src/components/views/WorkflowOrchestrationView.tsx`
- [Benchmark view](https://github.com/moalimjaveed/mocs-cert/blob/main/frontend/src/components/views/ExecutionBenchmarksView.tsx): `frontend/src/components/views/ExecutionBenchmarksView.tsx`

### Other components

- **Researcher**

## Connections

- Researcher → React workstation: uses (evidence: `README.md`)
- React workstation → Query editor: edits queries (evidence: `README.md`)
- Query editor → Query endpoint: submits query (evidence: `README.md`)
- FastAPI application → Query endpoint: mounts route (evidence: `backend/app/main.py`)
- FastAPI application → Query stream: mounts socket (evidence: `backend/app/main.py`)
- FastAPI application → Workflow endpoint: mounts route (evidence: `backend/app/main.py`)
- FastAPI application → Molecular endpoints: mounts route (evidence: `backend/app/main.py`)
- Query endpoint → Query compiler: invokes (evidence: `backend/app/api/endpoints/query.py`)
- Query stream → Trajectory service: refines blocks (evidence: `backend/app/api/websockets/query_stream.py`)
- Query stream → Query compiler: compiles query (evidence: `backend/app/api/websockets/query_stream.py`)
- Query compiler → Plan selector: selects plan (evidence: `backend/app/core/compiler_service.py`)
- Query compiler → Trajectory service: resolves trajectory (evidence: `backend/app/core/compiler_service.py`)
- Query compiler → Periodic bounds: computes bounds (evidence: `backend/app/core/compiler_service.py`)
- Query compiler → MCI index: reads index (evidence: `backend/app/core/compiler_service.py`)
- Query compiler → Certificate auditor: audits evidence (evidence: `backend/app/core/compiler_service.py`)
- Trajectory service → MCI index: loads blocks (evidence: `backend/app/core/trajectory_service.py`)
- Trajectory service → Periodic bounds: computes PBC bounds (evidence: `backend/app/core/trajectory_service.py`)
- Trajectory service → Trajectory I/O: opens source (evidence: `backend/app/core/trajectory_service.py`)
- Refinement timeline → Query stream: requests refinement
- Certificate inspection → Certificate auditor: inspects proof (evidence: `README.md`)
- Molecular viewer → Molecular endpoints: loads structures
- Researcher → Workflow workspace: orchestrates workflows (evidence: `README.md`)
- Workflow endpoint → Workflow engine: dispatches workflow
- Workflow engine → Workflow pipelines: runs pipelines (evidence: `mocs/workflow/engine.py`)
- Workflow engine → Backend ecosystem: discovers backends (evidence: `mocs/workflow/engine.py`)
- Structural selection → Workflow pipelines: supports selection
- Researcher → Benchmark view: reviews benchmarks (evidence: `README.md`)
