How nifdi01/virus-classifier-app works
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: batch.py Batch endpoints · main.py FastAPI application · tasks.py Batch tasks · docker-compose.yml Compose orchestration
Components 17
Browser UI
- React/Vite app
frontend/src/main.tsx - Processor upload · Submits single and batch sequence work.
frontend/src/pages/Processor.tsx - Job history · Lists jobs and polls task details.
frontend/src/pages/History.tsx - API clients
frontend/src/api/client.ts
FastAPI service
- FastAPI application
app/main.py - Predict endpoint · Handles synchronous POST /predict inference.
app/routes/predict.py - Batch endpoints · Accepts JSON and FASTA/TXT uploads and exposes job status/history.
app/routes/batch.py - Request validation · Enforces nucleotide, batch-size, and sequence-length constraints.
app/schemas.py
ML inference
- Model registry · Selects and loads configured inference backends.
app/registry.py - Inference service · Shared prediction path for API requests and batch tasks.
app/inference.py - Model wrappers · HyenaDNA and classical-model implementations.
ml/src/hyenadna_model.py - Model artifacts
Async processing
- Celery worker
worker.py - Batch tasks · Runs per-sequence inference and reports batch progress.
app/tasks.py - Job store · Maintains the submitted-job index for history.
app/job_store.py - Redis · Celery broker/result backend and recent-job metadata store.
Runtime services
- Compose orchestration · Runs frontend, API, worker, and Redis together.
docker-compose.yml
Connections 23
- 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