mahakagarwal7/diffucat

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