# nifdi01/virus-classifier-app architecture

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

- Interactive diagram: https://gitdiagram.com/nifdi01/virus-classifier-app
- Repository: https://github.com/nifdi01/virus-classifier-app

## Overview

#### Purpose and Entry Points
This is a full-stack viral nucleotide-sequence classifier focused on influenza labels. It exposes synchronous single-sequence inference and asynchronous batch processing over multiple ML backends. Backend startup enters at `app/main.py`; Celery workers enter at `worker.py`; the browser UI enters at `frontend/src/main.tsx`. Local multi-service orchestration is defined in `docker-compose.yml`.

#### API and Request Boundary
FastAPI owns HTTP validation, routing, and response shaping. Prediction, batch submission/upload, and model-facing endpoints are separated into `app/routes/predict.py`, `app/routes/batch.py`, and `app/routes/model.py`. Shared request constraints and API models live in `app/schemas.py`, enforcing nucleotide content plus batch size and sequence-length limits before model or queue execution.

#### Model Registry and Inference Layer
`app/registry.py` selects configured backends—HyenaDNA, logistic regression, random forest, and XGBoost—and centralizes model availability/loading decisions. `app/inference.py` provides the application-facing inference path used by synchronous requests and batch tasks. Model-specific wrappers are in `ml/src/hyenadna_model.py`, `ml/src/sklearn_model.py`, and `ml/src/universal_model.py`; persisted artifacts reside under `ml/models/hyenadna/` and `ml/models/baseline/`.

#### Synchronous Prediction Flow
`POST /predict` reaches `app/routes/predict.py`, validates a single sequence through `app/schemas.py`, resolves the requested model through `app/registry.py`, then invokes `app/inference.py`. It returns influenza classification, confidence/scores, sequence length, and actual model used in the HTTP response. This path runs inside the FastAPI process rather than through Celery.

#### Asynchronous Batch Flow
Batch JSON and FASTA/TXT uploads are accepted by `app/routes/batch.py`. Upload handling parses FASTA-style records, validates the resulting sequence list, creates/enqueues a Celery task, and returns a task ID immediately. `app/tasks.py` executes each batch in the worker process, runs inference per sequence, and publishes progress/results through Celery’s Redis-backed state mechanisms. `worker.py` configures the Celery application and worker runtime.

#### Job Status and Persistence Boundary
Redis serves two roles: Celery broker/result backend and recent-job metadata storage. `app/job_store.py` maintains the submitted-job index used by batch listing/history, while task-state lookups expose `PENDING`, `PROGRESS`, `SUCCESS`, and `FAILURE` for an individual task. This makes job execution state and job-list metadata external to API/worker process memory.

#### Frontend and Deployment
The React/Vite TypeScript frontend calls the API through `frontend/src/api/client.ts` and `frontend/src/api/jobs.ts`. Processing/upload is centered in `frontend/src/pages/Processor.tsx`; history and polling/detail views are in `frontend/src/pages/History.tsx` and `frontend/src/pages/JobDetail.tsx`. The system runs as frontend, FastAPI API, Celery worker, and Redis services via `docker-compose.yml`; Python API/worker packaging uses `Dockerfile`, and frontend packaging uses `frontend/Dockerfile`.

Main entry points: [`app/routes/batch.py`](https://github.com/nifdi01/virus-classifier-app/blob/main/app/routes/batch.py) (Batch endpoints), [`app/main.py`](https://github.com/nifdi01/virus-classifier-app/blob/main/app/main.py) (FastAPI application), [`app/tasks.py`](https://github.com/nifdi01/virus-classifier-app/blob/main/app/tasks.py) (Batch tasks), [`docker-compose.yml`](https://github.com/nifdi01/virus-classifier-app/blob/main/docker-compose.yml) (Compose orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser UI"]
  node_ui_entry["React/Vite app<br/>frontend entry<br/>[main.tsx]"]
  node_processor["Processor upload<br/>UI page<br/>[Processor.tsx]"]
  node_history["Job history<br/>UI pages<br/>[History.tsx]"]
  node_api_client["API clients<br/>TypeScript client<br/>[client.ts]"]
end

subgraph group_api["FastAPI service"]
  node_api_entry["FastAPI application<br/>HTTP entry<br/>[main.py]"]
  node_predict_route["Predict endpoint<br/>FastAPI route<br/>[predict.py]"]
  node_batch_route["Batch endpoints<br/>FastAPI route<br/>[batch.py]"]
  node_schemas["Request validation<br/>Pydantic schemas<br/>[schemas.py]"]
end

subgraph group_ml["ML inference"]
  node_registry["Model registry<br/>backend selector<br/>[registry.py]"]
  node_inference["Inference service<br/>application inference<br/>[inference.py]"]
  node_model_wrappers["Model wrappers<br/>ML adapters<br/>[hyenadna_model.py]"]
  node_model_artifacts[("Model artifacts<br/>persisted models")]
end

subgraph group_async["Async processing"]
  node_worker["Celery worker<br/>worker entry<br/>[worker.py]"]
  node_tasks["Batch tasks<br/>Celery tasks<br/>[tasks.py]"]
  node_job_store["Job store<br/>job metadata<br/>[job_store.py]"]
  node_redis[("Redis<br/>broker and state store")]
end

subgraph group_deploy["Runtime services"]
  node_compose["Compose orchestration<br/>service topology<br/>[docker-compose.yml]"]
end

node_ui_entry -->|"renders"| node_processor
node_ui_entry -->|"renders"| node_history
node_processor -->|"uses"| node_api_client
node_history -->|"uses"| node_api_client
node_api_client -->|"HTTP requests"| node_api_entry
node_api_entry -->|"routes"| node_predict_route
node_api_entry -->|"routes"| node_batch_route
node_predict_route -->|"validates"| node_schemas
node_batch_route -->|"parses and validates"| node_schemas
node_predict_route -->|"resolves model"| node_registry
node_registry -->|"configures backend"| node_inference
node_inference -->|"invokes"| node_model_wrappers
node_model_wrappers -->|"loads"| node_model_artifacts
node_batch_route -->|"enqueues batch"| node_tasks
node_worker -->|"executes"| node_tasks
node_tasks -->|"predicts each sequence"| node_inference
node_batch_route -->|"records submission"| node_job_store
node_job_store -->|"stores index"| node_redis
node_tasks -->|"broker, progress, results"| node_redis
node_batch_route -->|"reads task state"| node_redis
node_compose -.->|"runs service"| node_api_entry
node_compose -.->|"runs service"| node_worker
node_compose -.->|"runs service"| node_redis

click node_ui_entry "https://github.com/nifdi01/virus-classifier-app/blob/main/frontend/src/main.tsx"
click node_processor "https://github.com/nifdi01/virus-classifier-app/blob/main/frontend/src/pages/Processor.tsx"
click node_history "https://github.com/nifdi01/virus-classifier-app/blob/main/frontend/src/pages/History.tsx"
click node_api_client "https://github.com/nifdi01/virus-classifier-app/blob/main/frontend/src/api/client.ts"
click node_api_entry "https://github.com/nifdi01/virus-classifier-app/blob/main/app/main.py"
click node_predict_route "https://github.com/nifdi01/virus-classifier-app/blob/main/app/routes/predict.py"
click node_batch_route "https://github.com/nifdi01/virus-classifier-app/blob/main/app/routes/batch.py"
click node_schemas "https://github.com/nifdi01/virus-classifier-app/blob/main/app/schemas.py"
click node_registry "https://github.com/nifdi01/virus-classifier-app/blob/main/app/registry.py"
click node_inference "https://github.com/nifdi01/virus-classifier-app/blob/main/app/inference.py"
click node_model_wrappers "https://github.com/nifdi01/virus-classifier-app/blob/main/ml/src/hyenadna_model.py"
click node_worker "https://github.com/nifdi01/virus-classifier-app/blob/main/worker.py"
click node_tasks "https://github.com/nifdi01/virus-classifier-app/blob/main/app/tasks.py"
click node_job_store "https://github.com/nifdi01/virus-classifier-app/blob/main/app/job_store.py"
click node_compose "https://github.com/nifdi01/virus-classifier-app/blob/main/docker-compose.yml"

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_entry,node_processor,node_history,node_api_client toneBlue
class node_api_entry,node_predict_route,node_batch_route,node_schemas toneAmber
class node_registry,node_inference,node_model_wrappers,node_model_artifacts toneMint
class node_worker,node_tasks,node_job_store,node_redis toneRose
class node_compose toneIndigo
```

## Components

### Browser UI

- [React/Vite app](https://github.com/nifdi01/virus-classifier-app/blob/main/frontend/src/main.tsx): frontend entry · `frontend/src/main.tsx`
- [Processor upload](https://github.com/nifdi01/virus-classifier-app/blob/main/frontend/src/pages/Processor.tsx): UI page · Submits single and batch sequence work. · `frontend/src/pages/Processor.tsx`
- [Job history](https://github.com/nifdi01/virus-classifier-app/blob/main/frontend/src/pages/History.tsx): UI pages · Lists jobs and polls task details. · `frontend/src/pages/History.tsx`
- [API clients](https://github.com/nifdi01/virus-classifier-app/blob/main/frontend/src/api/client.ts): TypeScript client · `frontend/src/api/client.ts`

### FastAPI service

- [FastAPI application](https://github.com/nifdi01/virus-classifier-app/blob/main/app/main.py): HTTP entry · `app/main.py`
- [Predict endpoint](https://github.com/nifdi01/virus-classifier-app/blob/main/app/routes/predict.py): FastAPI route · Handles synchronous POST /predict inference. · `app/routes/predict.py`
- [Batch endpoints](https://github.com/nifdi01/virus-classifier-app/blob/main/app/routes/batch.py): FastAPI route · Accepts JSON and FASTA/TXT uploads and exposes job status/history. · `app/routes/batch.py`
- [Request validation](https://github.com/nifdi01/virus-classifier-app/blob/main/app/schemas.py): Pydantic schemas · Enforces nucleotide, batch-size, and sequence-length constraints. · `app/schemas.py`

### ML inference

- [Model registry](https://github.com/nifdi01/virus-classifier-app/blob/main/app/registry.py): backend selector · Selects and loads configured inference backends. · `app/registry.py`
- [Inference service](https://github.com/nifdi01/virus-classifier-app/blob/main/app/inference.py): application inference · Shared prediction path for API requests and batch tasks. · `app/inference.py`
- [Model wrappers](https://github.com/nifdi01/virus-classifier-app/blob/main/ml/src/hyenadna_model.py): ML adapters · HyenaDNA and classical-model implementations. · `ml/src/hyenadna_model.py`
- **Model artifacts**: persisted models

### Async processing

- [Celery worker](https://github.com/nifdi01/virus-classifier-app/blob/main/worker.py): worker entry · `worker.py`
- [Batch tasks](https://github.com/nifdi01/virus-classifier-app/blob/main/app/tasks.py): Celery tasks · Runs per-sequence inference and reports batch progress. · `app/tasks.py`
- [Job store](https://github.com/nifdi01/virus-classifier-app/blob/main/app/job_store.py): job metadata · Maintains the submitted-job index for history. · `app/job_store.py`
- **Redis**: broker and state store · Celery broker/result backend and recent-job metadata store.

### Runtime services

- [Compose orchestration](https://github.com/nifdi01/virus-classifier-app/blob/main/docker-compose.yml): service topology · Runs frontend, API, worker, and Redis together. · `docker-compose.yml`

## Connections

- React/Vite app → Processor upload: renders
- React/Vite app → Job history: renders
- Processor upload → API clients: uses
- Job history → API clients: uses
- API clients → FastAPI application: HTTP requests
- FastAPI application → Predict endpoint: routes
- FastAPI application → Batch endpoints: routes
- Predict endpoint → Request validation: validates
- Batch endpoints → Request validation: parses and validates
- Predict endpoint → Model registry: resolves model
- Model registry → Inference service: configures backend
- Inference service → Model wrappers: invokes
- Model wrappers → Model artifacts: loads
- Batch endpoints → Batch tasks: enqueues batch
- Celery worker → Batch tasks: executes
- Batch tasks → Inference service: predicts each sequence
- Batch endpoints → Job store: records submission
- Job store → Redis: stores index
- Batch tasks → Redis: broker, progress, results
- Batch endpoints → Redis: reads task state
- Compose orchestration → FastAPI application: runs service
- Compose orchestration → Celery worker: runs service
- Compose orchestration → Redis: runs service