# mahakagarwal7/diffucat architecture

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

- Interactive diagram: https://gitdiagram.com/mahakagarwal7/diffucat
- Repository: https://github.com/mahakagarwal7/diffucat

## Overview

#### Purpose and entry points
DiffuCat is a catalyst-discovery platform: it accepts molecular SMILES, runs GNN-based prediction/generation/ranking workflows, exposes lab-validation operations, and presents results in a Next.js research console with 3D molecular views. Backend entry point: `src/backend/main.py`; frontend route root: `frontend/app/page.tsx`; primary researcher workspace: `frontend/app/(main)/dashboard/page.tsx`.

#### API and orchestration boundary
FastAPI separates UI clients from scientific services through versioned endpoints for candidate generation, property prediction, ranking, and lab submission. API handlers should remain transport-facing and delegate workflow logic to services.
- `src/backend/api/v1/generate.py`
- `src/backend/api/v1/predict.py`
- `src/backend/api/v1/rank.py`
- `src/backend/api/v1/lab.py`
- `src/backend/services/pipeline.py`

#### Molecular ML pipeline
The core pipeline converts chemical data into model-ready representations, trains or invokes predictive models, and produces candidate-level properties/uncertainty for downstream ranking and visualization. Diffusion-based generation and predictor inference are distinct model concerns.
- `src/data/processor.py`
- `src/models/diffusion.py`
- `src/models/predictor.py`
- `src/training/trainer.py`

#### Selection, learning, and explainability
Post-inference services prioritize molecules, select informative candidates for active-learning cycles, and derive interpretable signals intended for structural uncertainty display. This is the decision layer between raw model output and user/lab actions.
- `src/services/ranking.py`
- `src/services/active_learning.py`
- `src/services/explainability.py`

#### Validation and laboratory integration
Candidates can be validated through interchangeable engines: mock execution, local ORCA computation, or a cloud API. A validation manager abstracts engine selection; the backend lab client connects digital pipeline outcomes to external or simulated laboratory workflows.
- `src/validation/manager.py`
- `src/validation/engines/orca.py`
- `src/validation/engines/cloud_api.py`
- `src/backend/services/lab_client.py`

#### Asynchronous and live execution
Celery supports non-blocking prediction work, while WebSocket functionality supports live visualization/status delivery. This boundary prevents long-running inference or validation from blocking HTTP request handling. Required broker/result infrastructure is implied by Celery configuration and Docker Compose.
- `src/backend/core/celery_app.py`
- `src/backend/tasks/predict_tasks.py`
- `src/backend/websockets/visualization.py`
- `docker/docker-compose.yml`

#### Research UI and visualization
The Next.js frontend provides discovery input/results, laboratory job tracking, and interactive 3D molecular rendering via 3Dmol.js. Client hooks/store form the UI state boundary for molecule and lab-job data; API connectivity is expected to target the FastAPI service.
- `frontend/components/discovery/DashboardUI.jsx`
- `frontend/components/discovery/MoleculeInput.tsx`
- `frontend/components/visualization/Molecule3DViewer.tsx`
- `frontend/components/lab/OptimizationConsole.tsx`
- `frontend/store/discovery.ts`

#### Data, reproducibility, and deployment
DVC governs reproducible data assets/pipelines; configuration is split between shared and backend settings. Docker supplies deployable service composition. Persisted example and DFT outputs under `results/` act as local artifacts for validation/demo workflows.
- `dvc.yaml`
- `configs/default.yaml`
- `configs/backend.yaml`
- `docker/Dockerfile`
- `results/dft_validation.json`

Main entry points: [`src/models/predictor.py`](https://github.com/mahakagarwal7/diffucat/blob/main/src/models/predictor.py) (Property predictor), [`src/backend/api/v1/generate.py`](https://github.com/mahakagarwal7/diffucat/blob/main/src/backend/api/v1/generate.py) (Versioned API), [`src/validation/manager.py`](https://github.com/mahakagarwal7/diffucat/blob/main/src/validation/manager.py) (Validation manager), [`src/data/processor.py`](https://github.com/mahakagarwal7/diffucat/blob/main/src/data/processor.py) (Molecular processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Research Console"]
  node_ui_dashboard["Research dashboard<br/>Next.js page<br/>[page.tsx]"]
  node_ui_discovery["Discovery UI<br/>React component<br/>[DashboardUI.jsx]"]
  node_ui_state["Discovery state<br/>client store<br/>[discovery.ts]"]
  node_ui_viewer["3D molecule viewer<br/>3Dmol.js component"]
end

subgraph group_backend["FastAPI &amp; Workflows"]
  node_api{{"Versioned API<br/>FastAPI routes<br/>[generate.py]"}}
  node_pipeline["Workflow pipeline<br/>backend service<br/>[pipeline.py]"]
  node_lab_client["Lab client<br/>backend service<br/>[lab_client.py]"]
end

subgraph group_ml["Molecular ML"]
  node_processor["Molecular processor<br/>data transform<br/>[processor.py]"]
  node_diffusion["Diffusion generator<br/>GNN model<br/>[diffusion.py]"]
  node_predictor["Property predictor<br/>GNN model<br/>[predictor.py]"]
  node_trainer["Model training<br/>training runtime<br/>[trainer.py]"]
end

subgraph group_decision["Decision Layer"]
  node_ranking["Candidate ranking<br/>selection service<br/>[ranking.py]"]
  node_active_learning["Active learning<br/>selection service<br/>[active_learning.py]"]
  node_explainability["Structural explanations<br/>explainability service<br/>[explainability.py]"]
end

subgraph group_validation["Validation"]
  node_validation_manager["Validation manager<br/>engine adapter<br/>[manager.py]"]
  node_orca["ORCA engine<br/>local DFT engine<br/>[orca.py]"]
  node_cloud_validation{{"Cloud validation<br/>external API engine<br/>[cloud_api.py]"}}
  node_validation_results[("DFT result artifacts<br/>local results")]
end

subgraph group_runtime["Async &amp; Delivery"]
  node_celery["Celery app<br/>task runtime<br/>[celery_app.py]"]
  node_predict_tasks["Prediction tasks<br/>async tasks<br/>[predict_tasks.py]"]
  node_live_updates["Live visualization<br/>WebSocket service<br/>[visualization.py]"]
  node_compose["Service composition<br/>Docker Compose<br/>[docker-compose.yml]"]
end

node_reproducibility["Data reproducibility<br/>DVC pipeline<br/>[dvc.yaml]"]

node_ui_dashboard -->|"renders"| node_ui_discovery
node_ui_discovery -->|"reads/writes"| node_ui_state
node_ui_state -->|"API requests"| node_api
node_api -->|"delegates"| node_pipeline
node_api -->|"lab submission"| node_lab_client
node_api -->|"queues prediction"| node_predict_tasks
node_predict_tasks -->|"runs on"| node_celery
node_celery -.->|"uses broker/results"| node_compose
node_pipeline -->|"prepares SMILES"| node_processor
node_processor -->|"model inputs"| node_diffusion
node_processor -->|"model inputs"| node_predictor
node_diffusion -->|"generated candidates"| node_predictor
node_predictor -->|"properties &amp; uncertainty"| node_ranking
node_ranking -->|"prioritized candidates"| node_active_learning
node_predictor -->|"model outputs"| node_explainability
node_ranking -->|"selected candidates"| node_lab_client
node_lab_client -->|"validation request"| node_validation_manager
node_validation_manager -->|"local engine"| node_orca
node_validation_manager -->|"cloud engine"| node_cloud_validation
node_validation_manager -->|"writes outputs"| node_validation_results
node_live_updates -->|"streams status/structures"| node_ui_viewer
node_ui_state -->|"molecule data"| node_ui_viewer
node_predictor -.->|"trained by"| node_trainer
node_reproducibility -.->|"versioned data"| node_processor

click node_ui_dashboard "https://github.com/mahakagarwal7/diffucat/blob/main/frontend/app/(main)/dashboard/page.tsx"
click node_ui_discovery "https://github.com/mahakagarwal7/diffucat/blob/main/frontend/components/discovery/DashboardUI.jsx"
click node_ui_state "https://github.com/mahakagarwal7/diffucat/blob/main/frontend/store/discovery.ts"
click node_ui_viewer "https://github.com/mahakagarwal7/diffucat/blob/main/frontend/components/visualization/Molecule3DViewer.tsx"
click node_api "https://github.com/mahakagarwal7/diffucat/blob/main/src/backend/api/v1/generate.py"
click node_pipeline "https://github.com/mahakagarwal7/diffucat/blob/main/src/backend/services/pipeline.py"
click node_lab_client "https://github.com/mahakagarwal7/diffucat/blob/main/src/backend/services/lab_client.py"
click node_processor "https://github.com/mahakagarwal7/diffucat/blob/main/src/data/processor.py"
click node_diffusion "https://github.com/mahakagarwal7/diffucat/blob/main/src/models/diffusion.py"
click node_predictor "https://github.com/mahakagarwal7/diffucat/blob/main/src/models/predictor.py"
click node_trainer "https://github.com/mahakagarwal7/diffucat/blob/main/src/training/trainer.py"
click node_ranking "https://github.com/mahakagarwal7/diffucat/blob/main/src/services/ranking.py"
click node_active_learning "https://github.com/mahakagarwal7/diffucat/blob/main/src/services/active_learning.py"
click node_explainability "https://github.com/mahakagarwal7/diffucat/blob/main/src/services/explainability.py"
click node_validation_manager "https://github.com/mahakagarwal7/diffucat/blob/main/src/validation/manager.py"
click node_orca "https://github.com/mahakagarwal7/diffucat/blob/main/src/validation/engines/orca.py"
click node_cloud_validation "https://github.com/mahakagarwal7/diffucat/blob/main/src/validation/engines/cloud_api.py"
click node_celery "https://github.com/mahakagarwal7/diffucat/blob/main/src/backend/core/celery_app.py"
click node_predict_tasks "https://github.com/mahakagarwal7/diffucat/blob/main/src/backend/tasks/predict_tasks.py"
click node_live_updates "https://github.com/mahakagarwal7/diffucat/blob/main/src/backend/websockets/visualization.py"
click node_compose "https://github.com/mahakagarwal7/diffucat/blob/main/docker/docker-compose.yml"
click node_reproducibility "https://github.com/mahakagarwal7/diffucat/blob/main/dvc.yaml"
click node_validation_results "https://github.com/mahakagarwal7/diffucat/blob/main/results/dft_validation.json"

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_ui_dashboard,node_ui_discovery,node_ui_state,node_ui_viewer toneBlue
class node_api,node_pipeline,node_lab_client toneAmber
class node_processor,node_diffusion,node_predictor,node_trainer toneMint
class node_ranking,node_active_learning,node_explainability toneRose
class node_validation_manager,node_orca,node_cloud_validation,node_validation_results toneIndigo
class node_celery,node_predict_tasks,node_live_updates,node_compose toneTeal
class node_reproducibility toneNeutral
```

## Components

### Research Console

- [Research dashboard](https://github.com/mahakagarwal7/diffucat/blob/main/frontend/app/(main)/dashboard/page.tsx): Next.js page · `frontend/app/(main)/dashboard/page.tsx`
- [Discovery UI](https://github.com/mahakagarwal7/diffucat/blob/main/frontend/components/discovery/DashboardUI.jsx): React component · `frontend/components/discovery/DashboardUI.jsx`
- [Discovery state](https://github.com/mahakagarwal7/diffucat/blob/main/frontend/store/discovery.ts): client store · Molecule and lab-job UI state boundary. · `frontend/store/discovery.ts`
- [3D molecule viewer](https://github.com/mahakagarwal7/diffucat/blob/main/frontend/components/visualization/Molecule3DViewer.tsx): 3Dmol.js component · `frontend/components/visualization/Molecule3DViewer.tsx`

### FastAPI & Workflows

- [Versioned API](https://github.com/mahakagarwal7/diffucat/blob/main/src/backend/api/v1/generate.py): FastAPI routes · Generation, prediction, ranking, and lab endpoints. · `src/backend/api/v1/generate.py`
- [Workflow pipeline](https://github.com/mahakagarwal7/diffucat/blob/main/src/backend/services/pipeline.py): backend service · Orchestrates scientific workflow requests. · `src/backend/services/pipeline.py`
- [Lab client](https://github.com/mahakagarwal7/diffucat/blob/main/src/backend/services/lab_client.py): backend service · `src/backend/services/lab_client.py`

### Molecular ML

- [Molecular processor](https://github.com/mahakagarwal7/diffucat/blob/main/src/data/processor.py): data transform · Converts chemical inputs to model-ready representations. · `src/data/processor.py`
- [Diffusion generator](https://github.com/mahakagarwal7/diffucat/blob/main/src/models/diffusion.py): GNN model · `src/models/diffusion.py`
- [Property predictor](https://github.com/mahakagarwal7/diffucat/blob/main/src/models/predictor.py): GNN model · Produces candidate properties and uncertainty. · `src/models/predictor.py`
- [Model training](https://github.com/mahakagarwal7/diffucat/blob/main/src/training/trainer.py): training runtime · `src/training/trainer.py`

### Decision Layer

- [Candidate ranking](https://github.com/mahakagarwal7/diffucat/blob/main/src/services/ranking.py): selection service · `src/services/ranking.py`
- [Active learning](https://github.com/mahakagarwal7/diffucat/blob/main/src/services/active_learning.py): selection service · Selects informative candidates for learning cycles. · `src/services/active_learning.py`
- [Structural explanations](https://github.com/mahakagarwal7/diffucat/blob/main/src/services/explainability.py): explainability service · Derives signals for uncertainty display. · `src/services/explainability.py`

### Validation

- [Validation manager](https://github.com/mahakagarwal7/diffucat/blob/main/src/validation/manager.py): engine adapter · Selects mock, local, or cloud validation engines. · `src/validation/manager.py`
- [ORCA engine](https://github.com/mahakagarwal7/diffucat/blob/main/src/validation/engines/orca.py): local DFT engine · `src/validation/engines/orca.py`
- [Cloud validation](https://github.com/mahakagarwal7/diffucat/blob/main/src/validation/engines/cloud_api.py): external API engine · `src/validation/engines/cloud_api.py`
- [DFT result artifacts](https://github.com/mahakagarwal7/diffucat/blob/main/results/dft_validation.json): local results · Persisted validation and demo outputs. · `results/dft_validation.json`

### Async & Delivery

- [Celery app](https://github.com/mahakagarwal7/diffucat/blob/main/src/backend/core/celery_app.py): task runtime · `src/backend/core/celery_app.py`
- [Prediction tasks](https://github.com/mahakagarwal7/diffucat/blob/main/src/backend/tasks/predict_tasks.py): async tasks · Moves long-running prediction off HTTP requests. · `src/backend/tasks/predict_tasks.py`
- [Live visualization](https://github.com/mahakagarwal7/diffucat/blob/main/src/backend/websockets/visualization.py): WebSocket service · Streams status and visualization updates. · `src/backend/websockets/visualization.py`
- [Service composition](https://github.com/mahakagarwal7/diffucat/blob/main/docker/docker-compose.yml): Docker Compose · Supplies deployable services and Celery broker/result infrastructure. · `docker/docker-compose.yml`

### Other components

- [Data reproducibility](https://github.com/mahakagarwal7/diffucat/blob/main/dvc.yaml): DVC pipeline · `dvc.yaml`

## Connections

- Research dashboard → Discovery UI: renders
- Discovery UI → Discovery state: reads/writes
- Discovery state → Versioned API: API requests
- Versioned API → Workflow pipeline: delegates
- Versioned API → Lab client: lab submission
- Versioned API → Prediction tasks: queues prediction
- Prediction tasks → Celery app: runs on
- Celery app → Service composition: uses broker/results
- Workflow pipeline → Molecular processor: prepares SMILES
- Molecular processor → Diffusion generator: model inputs
- Molecular processor → Property predictor: model inputs
- Diffusion generator → Property predictor: generated candidates
- Property predictor → Candidate ranking: properties & uncertainty
- Candidate ranking → Active learning: prioritized candidates
- Property predictor → Structural explanations: model outputs
- Candidate ranking → Lab client: selected candidates
- Lab client → Validation manager: validation request
- Validation manager → ORCA engine: local engine
- Validation manager → Cloud validation: cloud engine
- Validation manager → DFT result artifacts: writes outputs
- Live visualization → 3D molecule viewer: streams status/structures
- Discovery state → 3D molecule viewer: molecule data
- Property predictor → Model training: trained by
- Data reproducibility → Molecular processor: versioned data