# rudrakshyadav1/deepseapoc architecture

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

- Interactive diagram: https://gitdiagram.com/rudrakshyadav1/deepseapoc
- Repository: https://github.com/rudrakshyadav1/deepseapoc

## Overview

#### Purpose and Topology
This repository is a bioinformatics analysis product: a Next.js frontend lets users upload and inspect site/sample analyses, while a Python backend exposes job-oriented APIs and a standalone Python pipeline processes sequencing data through QC, taxonomy, and reporting stages.

#### Frontend Application
Next.js App Router provides public pages, authentication, and a dashboard. Primary page entry points are:
- `frontend/src/app/page.tsx`
- `frontend/src/app/dashboard/page.tsx`
- `frontend/src/app/layout.tsx`

Dashboard UI is organized around upload, map/site selection, and result presentation:
- `frontend/src/app/components/dashboard/UploadPanel.tsx`
- `frontend/src/app/components/dashboard/MapComponent.tsx`
- `frontend/src/app/components/dashboard/ResultsPanel.tsx`

The map uses a bundled India GeoJSON dataset at `frontend/public/india-composite.geojson`.

#### Frontend State, Identity, and Backend Boundary
`JobContext` coordinates analysis-job state across dashboard components, while Redux store setup includes an authentication slice:
- `frontend/src/app/contexts/JobContext.tsx`
- `frontend/src/store/store.tsx`
- `frontend/src/store/authSlice.ts`

Firebase is the apparent client authentication integration:
- `frontend/src/firebase/firebase.ts`

`BackendDataService` is the principal frontend-to-backend boundary; it should encapsulate API calls rather than allowing dashboard components to depend directly on backend endpoints:
- `frontend/src/app/services/BackendDataService.ts`

Mock site/sample data supports frontend operation independent of completed backend analyses:
- `frontend/src/data/mockSamples.json`
- `frontend/src/data/mockSites.json`

#### Backend API and Job Control Plane
The Python backend is structured as an API service with versioned route modules. Application startup and shared infrastructure are centered in:
- `backend/app/main.py`
- `backend/app/db.py`
- `backend/app/core/config.py`

The externally meaningful workflow endpoints are separated by responsibility:
- upload intake: `backend/app/api/v1/upload.py`
- job creation/status: `backend/app/api/v1/jobs.py`
- analysis retrieval: `backend/app/api/v1/results.py`

A health endpoint supports service monitoring at `backend/app/api/v1/health.py`. There is also a routes-level jobs module, suggesting job routing or compatibility logic:
- `backend/app/routes/jobs.py`

#### Persistence, Schemas, and Security
Backend models define persisted job/result domain entities, and schemas define request/response contracts:
- `backend/app/models/models.py`
- `backend/app/schemas/schemas.py`

Security concerns are isolated from endpoint handlers:
- `backend/app/core/security.py`

The database implementation is represented by `backend/app/db.py`; the tree does not identify its database vendor. Logging is similarly centralized:
- `backend/app/core/logger.py`

#### Asynchronous Processing Boundary
Celery is the designated background-worker runtime, separating API request handling from long-running analysis execution:
- `backend/app/workers/celery_worker.py`
- `backend/app/api/v1/jobs.py`

The intended control flow is: frontend uploads data → backend creates/persists a job → Celery worker executes analysis → frontend polls or retrieves job results through the results API. Broker/result-backend infrastructure is not identifiable from the supplied tree.

#### Bioinformatics Pipeline
The standalone pipeline orchestrator is:
- `pipeline/run_pipeline.py`

It composes a staged analysis flow over uploaded sequencing inputs:
1. Input conversion and QC: `pipeline/converter.py`, `pipeline/steps/qc.py`
2. Read cleanup: `pipeline/steps/adapters.py`, `pipeline/steps/filter.py`, `pipeline/steps/chimera.py`, `pipeline/steps/contam.py`
3. Biological reduction/classification: `pipeline/steps/cluster.py`, `pipeline/steps/annotate.py`, `pipeline/steps/genus.py`
4. Analytical output generation: `pipeline/steps/abundance.py`, `pipeline/steps/embed.py`, `pipeline/steps/reduce.py`, `pipeline/steps/report.py`

`pipeline/cache/ncbi_cache.json` indicates NCBI-derived lookup/cache usage, likely associated with annotation. Pipeline outputs must be translated into the backend’s result model/API contract for dashboard consumption.

Main entry points: [`frontend/src/app/dashboard/page.tsx`](https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/app/dashboard/page.tsx) (Dashboard), [`frontend/src/app/services/BackendDataService.ts`](https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/app/services/BackendDataService.ts) (Backend data service), [`backend/app/api/v1/jobs.py`](https://github.com/rudrakshyadav1/deepseapoc/blob/main/backend/app/api/v1/jobs.py) (Job API), [`backend/app/models/models.py`](https://github.com/rudrakshyadav1/deepseapoc/blob/main/backend/app/models/models.py) (Job/result domain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js frontend"]
  node_app["App Router<br/>Next.js app<br/>[layout.tsx]"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_upload_ui["Upload panel<br/>UI component<br/>[UploadPanel.tsx]"]
  node_map_ui["Site map<br/>UI component<br/>[MapComponent.tsx]"]
  node_results_ui["Results panel<br/>UI component<br/>[ResultsPanel.tsx]"]
  node_job_state["Job state<br/>React context<br/>[JobContext.tsx]"]
  node_auth["Authentication<br/>Redux + Firebase<br/>[authSlice.ts]"]
  node_data_service{{"Backend data service<br/>API client boundary"}}
  node_mock_data["Mock sites &amp; samples<br/>JSON fixtures<br/>[mockSamples.json]"]
end

subgraph group_backend["Python API &amp; workers"]
  node_api_app["API application<br/>Python API service<br/>[main.py]"]
  node_upload_api["Upload intake<br/>API route<br/>[upload.py]"]
  node_jobs_api["Job API<br/>API route<br/>[jobs.py]"]
  node_results_api["Results API<br/>API route<br/>[results.py]"]
  node_domain["Job/result domain<br/>models &amp; schemas<br/>[models.py]"]
  node_database[("Database<br/>persistence<br/>[db.py]")]
  node_worker["Celery worker<br/>background runtime<br/>[celery_worker.py]"]
end

subgraph group_pipeline["Analysis pipeline"]
  node_orchestrator["Pipeline orchestrator<br/>pipeline runner<br/>[run_pipeline.py]"]
  node_qc["Conversion &amp; QC<br/>pipeline stage<br/>[converter.py]"]
  node_cleanup["Read cleanup<br/>pipeline stage<br/>[adapters.py]"]
  node_classification["Classification<br/>pipeline stage<br/>[cluster.py]"]
  node_reporting["Analytical reporting<br/>pipeline stage<br/>[abundance.py]"]
  node_ncbi_cache["NCBI cache<br/>lookup cache<br/>[ncbi_cache.json]"]
end

node_app -->|"renders"| node_dashboard
node_dashboard -->|"includes"| node_upload_ui
node_dashboard -->|"includes"| node_map_ui
node_dashboard -->|"includes"| node_results_ui
node_dashboard -->|"uses"| node_job_state
node_dashboard -->|"uses identity"| node_auth
node_map_ui -.->|"fallback data"| node_mock_data
node_results_ui -.->|"fallback data"| node_mock_data
node_upload_ui -->|"submits input"| node_data_service
node_job_state -->|"tracks jobs"| node_data_service
node_results_ui -->|"retrieves results"| node_data_service
node_data_service -->|"uploads"| node_upload_api
node_data_service -->|"creates / polls"| node_jobs_api
node_data_service -->|"fetches"| node_results_api
node_api_app -->|"serves"| node_upload_api
node_api_app -->|"serves"| node_jobs_api
node_api_app -->|"serves"| node_results_api
node_upload_api -->|"initiates job"| node_jobs_api
node_jobs_api -->|"uses contracts"| node_domain
node_results_api -->|"serializes"| node_domain
node_domain -->|"persists"| node_database
node_jobs_api -->|"dispatches"| node_worker
node_worker -->|"executes"| node_orchestrator
node_orchestrator -->|"runs first"| node_qc
node_qc -->|"clean reads"| node_cleanup
node_cleanup -->|"prepared reads"| node_classification
node_classification -.->|"lookup data"| node_ncbi_cache
node_classification -->|"taxonomic output"| node_reporting
node_reporting -->|"maps outputs to results"| node_domain

click node_app "https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/app/layout.tsx"
click node_dashboard "https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/app/dashboard/page.tsx"
click node_upload_ui "https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/app/components/dashboard/UploadPanel.tsx"
click node_map_ui "https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/app/components/dashboard/MapComponent.tsx"
click node_results_ui "https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/app/components/dashboard/ResultsPanel.tsx"
click node_job_state "https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/app/contexts/JobContext.tsx"
click node_auth "https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/store/authSlice.ts"
click node_data_service "https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/app/services/BackendDataService.ts"
click node_mock_data "https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/data/mockSamples.json"
click node_api_app "https://github.com/rudrakshyadav1/deepseapoc/blob/main/backend/app/main.py"
click node_upload_api "https://github.com/rudrakshyadav1/deepseapoc/blob/main/backend/app/api/v1/upload.py"
click node_jobs_api "https://github.com/rudrakshyadav1/deepseapoc/blob/main/backend/app/api/v1/jobs.py"
click node_results_api "https://github.com/rudrakshyadav1/deepseapoc/blob/main/backend/app/api/v1/results.py"
click node_domain "https://github.com/rudrakshyadav1/deepseapoc/blob/main/backend/app/models/models.py"
click node_database "https://github.com/rudrakshyadav1/deepseapoc/blob/main/backend/app/db.py"
click node_worker "https://github.com/rudrakshyadav1/deepseapoc/blob/main/backend/app/workers/celery_worker.py"
click node_orchestrator "https://github.com/rudrakshyadav1/deepseapoc/blob/main/pipeline/run_pipeline.py"
click node_qc "https://github.com/rudrakshyadav1/deepseapoc/blob/main/pipeline/converter.py"
click node_cleanup "https://github.com/rudrakshyadav1/deepseapoc/blob/main/pipeline/steps/adapters.py"
click node_classification "https://github.com/rudrakshyadav1/deepseapoc/blob/main/pipeline/steps/cluster.py"
click node_reporting "https://github.com/rudrakshyadav1/deepseapoc/blob/main/pipeline/steps/abundance.py"
click node_ncbi_cache "https://github.com/rudrakshyadav1/deepseapoc/blob/main/pipeline/cache/ncbi_cache.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_app,node_dashboard,node_upload_ui,node_map_ui,node_results_ui,node_job_state,node_auth,node_data_service,node_mock_data toneBlue
class node_api_app,node_upload_api,node_jobs_api,node_results_api,node_domain,node_database,node_worker toneAmber
class node_orchestrator,node_qc,node_cleanup,node_classification,node_reporting,node_ncbi_cache toneMint
```

## Components

### Next.js frontend

- [App Router](https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/app/layout.tsx): Next.js app · Public, auth, and dashboard page entry points. · `frontend/src/app/layout.tsx`
- [Dashboard](https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/app/dashboard/page.tsx): dashboard UI · Upload, site selection, and result presentation. · `frontend/src/app/dashboard/page.tsx`
- [Upload panel](https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/app/components/dashboard/UploadPanel.tsx): UI component · `frontend/src/app/components/dashboard/UploadPanel.tsx`
- [Site map](https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/app/components/dashboard/MapComponent.tsx): UI component · Renders India site geography. · `frontend/src/app/components/dashboard/MapComponent.tsx`
- [Results panel](https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/app/components/dashboard/ResultsPanel.tsx): UI component · `frontend/src/app/components/dashboard/ResultsPanel.tsx`
- [Job state](https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/app/contexts/JobContext.tsx): React context · Coordinates analysis jobs across dashboard components. · `frontend/src/app/contexts/JobContext.tsx`
- [Authentication](https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/store/authSlice.ts): Redux + Firebase · Client identity state and Firebase integration. · `frontend/src/store/authSlice.ts`
- [Backend data service](https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/app/services/BackendDataService.ts): API client boundary · Encapsulates frontend calls to backend APIs. · `frontend/src/app/services/BackendDataService.ts`
- [Mock sites & samples](https://github.com/rudrakshyadav1/deepseapoc/blob/main/frontend/src/data/mockSamples.json): JSON fixtures · Supports frontend use without completed analyses. · `frontend/src/data/mockSamples.json`

### Python API & workers

- [API application](https://github.com/rudrakshyadav1/deepseapoc/blob/main/backend/app/main.py): Python API service · Application startup and versioned API composition. · `backend/app/main.py`
- [Upload intake](https://github.com/rudrakshyadav1/deepseapoc/blob/main/backend/app/api/v1/upload.py): API route · `backend/app/api/v1/upload.py`
- [Job API](https://github.com/rudrakshyadav1/deepseapoc/blob/main/backend/app/api/v1/jobs.py): API route · Creates jobs and exposes their status. · `backend/app/api/v1/jobs.py`
- [Results API](https://github.com/rudrakshyadav1/deepseapoc/blob/main/backend/app/api/v1/results.py): API route · Returns completed analysis results. · `backend/app/api/v1/results.py`
- [Job/result domain](https://github.com/rudrakshyadav1/deepseapoc/blob/main/backend/app/models/models.py): models & schemas · Persisted entities and API contracts. · `backend/app/models/models.py`
- [Database](https://github.com/rudrakshyadav1/deepseapoc/blob/main/backend/app/db.py): persistence · Vendor is not identified. · `backend/app/db.py`
- [Celery worker](https://github.com/rudrakshyadav1/deepseapoc/blob/main/backend/app/workers/celery_worker.py): background runtime · Runs long-lived analysis outside API requests. · `backend/app/workers/celery_worker.py`

### Analysis pipeline

- [Pipeline orchestrator](https://github.com/rudrakshyadav1/deepseapoc/blob/main/pipeline/run_pipeline.py): pipeline runner · Composes sequencing analysis stages for worker jobs. · `pipeline/run_pipeline.py`
- [Conversion & QC](https://github.com/rudrakshyadav1/deepseapoc/blob/main/pipeline/converter.py): pipeline stage · Converts inputs and performs quality control. · `pipeline/converter.py`
- [Read cleanup](https://github.com/rudrakshyadav1/deepseapoc/blob/main/pipeline/steps/adapters.py): pipeline stage · Adapter, filter, chimera, and contaminant processing. · `pipeline/steps/adapters.py`
- [Classification](https://github.com/rudrakshyadav1/deepseapoc/blob/main/pipeline/steps/cluster.py): pipeline stage · Clustering, annotation, and genus reduction. · `pipeline/steps/cluster.py`
- [Analytical reporting](https://github.com/rudrakshyadav1/deepseapoc/blob/main/pipeline/steps/abundance.py): pipeline stage · Abundance, embedding, reduction, and report output. · `pipeline/steps/abundance.py`
- [NCBI cache](https://github.com/rudrakshyadav1/deepseapoc/blob/main/pipeline/cache/ncbi_cache.json): lookup cache · Cached NCBI-derived annotation data. · `pipeline/cache/ncbi_cache.json`

## Connections

- App Router → Dashboard: renders
- Dashboard → Upload panel: includes
- Dashboard → Site map: includes
- Dashboard → Results panel: includes
- Dashboard → Job state: uses
- Dashboard → Authentication: uses identity
- Site map → Mock sites & samples: fallback data
- Results panel → Mock sites & samples: fallback data
- Upload panel → Backend data service: submits input
- Job state → Backend data service: tracks jobs
- Results panel → Backend data service: retrieves results
- Backend data service → Upload intake: uploads
- Backend data service → Job API: creates / polls
- Backend data service → Results API: fetches
- API application → Upload intake: serves
- API application → Job API: serves
- API application → Results API: serves
- Upload intake → Job API: initiates job
- Job API → Job/result domain: uses contracts
- Results API → Job/result domain: serializes
- Job/result domain → Database: persists
- Job API → Celery worker: dispatches
- Celery worker → Pipeline orchestrator: executes
- Pipeline orchestrator → Conversion & QC: runs first
- Conversion & QC → Read cleanup: clean reads
- Read cleanup → Classification: prepared reads
- Classification → NCBI cache: lookup data
- Classification → Analytical reporting: taxonomic output
- Analytical reporting → Job/result domain: maps outputs to results