# ayazxdev/aquadex architecture

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

- Interactive diagram: https://gitdiagram.com/ayazxdev/aquadex
- Repository: https://github.com/ayazxdev/aquadex

## Overview

AQUADEX is a web platform for analyzing environmental DNA sequencing data, classifying taxa, and exploring biodiversity and novelty results. Users upload sequence files, start a run, follow its status, then inspect summaries, visualizations, sequences, and downloadable artifacts. The FastAPI service coordinates run storage and pipeline execution; the real pipeline includes quality control, denoising, classification, embedding, novelty scoring, clustering, phylogeny, and reports. The tree also documents additional pipeline stages. Their exact runtime wiring is not established by the sampled excerpts, so those links are omitted.

Main entry points: [`backend/app/pipeline/pipeline_runner.py`](https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/pipeline_runner.py) (Pipeline runner), [`backend/app/api/routes.py`](https://github.com/ayazxdev/aquadex/blob/main/backend/app/api/routes.py) (API routes), [`frontend/src/App.jsx`](https://github.com/ayazxdev/aquadex/blob/main/frontend/src/App.jsx) (Page navigation), [`backend/app/services/pipeline.py`](https://github.com/ayazxdev/aquadex/blob/main/backend/app/services/pipeline.py) (Pipeline service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Web interface"]
  node_app["Page navigation<br/>[App.jsx]"]
  node_runpage["Run submission<br/>[Run.jsx]"]
  node_resultspage["Results explorer<br/>[Results.jsx]"]
end

subgraph group_api["API and run services"]
  node_main["FastAPI app<br/>[main.py]"]
  node_routes["API routes<br/>[routes.py]"]
  node_storage["Run storage<br/>[storage.py]"]
  node_pipeline_service["Pipeline service<br/>[pipeline.py]"]
end

subgraph group_analysis["Bioinformatics analysis"]
  node_runner["Pipeline runner<br/>[pipeline_runner.py]"]
  node_qc["Quality control<br/>[pipeline_runner.py]"]
  node_denoise["Denoising<br/>[pipeline_runner.py]"]
  node_taxonomy["Taxonomic classification<br/>[pipeline_runner.py]"]
  node_embeddings["Sequence embeddings<br/>[step_embeddings.py]"]
  node_novelty["Novelty scoring<br/>[pipeline_runner.py]"]
  node_clustering["Clustering<br/>[pipeline_runner.py]"]
  node_phylogeny["Phylogeny<br/>[pipeline_runner.py]"]
  node_reports["Report generation<br/>[pipeline_runner.py]"]
end

subgraph group_results["Results and artifacts"]
  node_aggregator["Result aggregation"]
  node_results_service["Results service<br/>[results.py]"]
  node_database[("Run files")]
end

node_user(("Research user"))
node_tools["Bioinformatics tools"]
node_model["DNABERT-S model"]

node_user -->|"uses"| node_app
node_app -->|"navigates"| node_runpage
node_app -->|"navigates"| node_resultspage
node_runpage -->|"uploads and starts"| node_routes
node_resultspage -->|"requests results"| node_routes
node_main -->|"mounts"| node_routes
node_routes -->|"creates run directories"| node_storage
node_routes -->|"starts pipeline"| node_pipeline_service
node_pipeline_service -->|"reads run files"| node_storage
node_pipeline_service -->|"runs analysis"| node_runner
node_runner -->|"runs"| node_qc
node_runner -->|"runs"| node_denoise
node_runner -->|"runs"| node_taxonomy
node_runner -->|"runs"| node_embeddings
node_runner -->|"runs"| node_novelty
node_runner -->|"runs"| node_clustering
node_runner -->|"runs"| node_phylogeny
node_runner -->|"runs"| node_reports
node_qc -->|"invokes"| node_tools
node_denoise -->|"invokes"| node_tools
node_taxonomy -->|"invokes"| node_tools
node_embeddings -->|"loads"| node_model
node_runner -->|"writes outputs"| node_database
node_routes -->|"reads summaries"| node_results_service
node_results_service -->|"aggregates"| node_aggregator
node_aggregator -->|"reads run outputs"| node_database
node_routes -->|"serves artifacts"| node_database

click node_app "https://github.com/ayazxdev/aquadex/blob/main/frontend/src/App.jsx"
click node_runpage "https://github.com/ayazxdev/aquadex/blob/main/frontend/src/pages/Run.jsx"
click node_resultspage "https://github.com/ayazxdev/aquadex/blob/main/frontend/src/pages/Results.jsx"
click node_main "https://github.com/ayazxdev/aquadex/blob/main/backend/app/main.py"
click node_routes "https://github.com/ayazxdev/aquadex/blob/main/backend/app/api/routes.py"
click node_storage "https://github.com/ayazxdev/aquadex/blob/main/backend/app/services/storage.py"
click node_pipeline_service "https://github.com/ayazxdev/aquadex/blob/main/backend/app/services/pipeline.py"
click node_runner "https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/pipeline_runner.py"
click node_qc "https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/pipeline_runner.py"
click node_denoise "https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/pipeline_runner.py"
click node_taxonomy "https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/pipeline_runner.py"
click node_embeddings "https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/step_embeddings.py"
click node_novelty "https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/pipeline_runner.py"
click node_clustering "https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/pipeline_runner.py"
click node_phylogeny "https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/pipeline_runner.py"
click node_reports "https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/pipeline_runner.py"
click node_aggregator "https://github.com/ayazxdev/aquadex/blob/main/backend/app/results_aggregator.py"
click node_results_service "https://github.com/ayazxdev/aquadex/blob/main/backend/app/services/results.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_app,node_runpage,node_resultspage,node_user toneBlue
class node_main,node_routes,node_storage,node_pipeline_service toneAmber
class node_runner,node_qc,node_denoise,node_taxonomy,node_embeddings,node_novelty,node_clustering,node_phylogeny,node_reports toneMint
class node_aggregator,node_results_service,node_database toneRose
class node_tools,node_model toneIndigo
```

## Components

### Web interface

- [Page navigation](https://github.com/ayazxdev/aquadex/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Run submission](https://github.com/ayazxdev/aquadex/blob/main/frontend/src/pages/Run.jsx): `frontend/src/pages/Run.jsx`
- [Results explorer](https://github.com/ayazxdev/aquadex/blob/main/frontend/src/pages/Results.jsx): `frontend/src/pages/Results.jsx`

### API and run services

- [FastAPI app](https://github.com/ayazxdev/aquadex/blob/main/backend/app/main.py): `backend/app/main.py`
- [API routes](https://github.com/ayazxdev/aquadex/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Run storage](https://github.com/ayazxdev/aquadex/blob/main/backend/app/services/storage.py): `backend/app/services/storage.py`
- [Pipeline service](https://github.com/ayazxdev/aquadex/blob/main/backend/app/services/pipeline.py): `backend/app/services/pipeline.py`

### Bioinformatics analysis

- [Pipeline runner](https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/pipeline_runner.py): `backend/app/pipeline/pipeline_runner.py`
- [Quality control](https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/pipeline_runner.py): `backend/app/pipeline/pipeline_runner.py`
- [Denoising](https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/pipeline_runner.py): `backend/app/pipeline/pipeline_runner.py`
- [Taxonomic classification](https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/pipeline_runner.py): `backend/app/pipeline/pipeline_runner.py`
- [Sequence embeddings](https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/step_embeddings.py): `backend/app/pipeline/step_embeddings.py`
- [Novelty scoring](https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/pipeline_runner.py): `backend/app/pipeline/pipeline_runner.py`
- [Clustering](https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/pipeline_runner.py): `backend/app/pipeline/pipeline_runner.py`
- [Phylogeny](https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/pipeline_runner.py): `backend/app/pipeline/pipeline_runner.py`
- [Report generation](https://github.com/ayazxdev/aquadex/blob/main/backend/app/pipeline/pipeline_runner.py): `backend/app/pipeline/pipeline_runner.py`

### Results and artifacts

- [Result aggregation](https://github.com/ayazxdev/aquadex/blob/main/backend/app/results_aggregator.py): `backend/app/results_aggregator.py`
- [Results service](https://github.com/ayazxdev/aquadex/blob/main/backend/app/services/results.py): `backend/app/services/results.py`
- **Run files**

### Other components

- **Research user**
- **Bioinformatics tools**
- **DNABERT-S model**

## Connections

- Research user → Page navigation: uses
- Page navigation → Run submission: navigates
- Page navigation → Results explorer: navigates
- Run submission → API routes: uploads and starts
- Results explorer → API routes: requests results
- FastAPI app → API routes: mounts
- API routes → Run storage: creates run directories
- API routes → Pipeline service: starts pipeline
- Pipeline service → Run storage: reads run files
- Pipeline service → Pipeline runner: runs analysis
- Pipeline runner → Quality control: runs
- Pipeline runner → Denoising: runs
- Pipeline runner → Taxonomic classification: runs
- Pipeline runner → Sequence embeddings: runs
- Pipeline runner → Novelty scoring: runs
- Pipeline runner → Clustering: runs
- Pipeline runner → Phylogeny: runs
- Pipeline runner → Report generation: runs
- Quality control → Bioinformatics tools: invokes
- Denoising → Bioinformatics tools: invokes
- Taxonomic classification → Bioinformatics tools: invokes
- Sequence embeddings → DNABERT-S model: loads
- Pipeline runner → Run files: writes outputs
- API routes → Results service: reads summaries
- Results service → Result aggregation: aggregates
- Result aggregation → Run files: reads run outputs
- API routes → Run files: serves artifacts