Loading...
Loading...
Loading...
> **Version:** 1.0 · **Author:** Manzil · **Last Updated:** 2026-02-13
# PRD: ProteinClassify — Transformer-Based Protein Analysis Platform
> **Version:** 1.0 · **Author:** Manzil · **Last Updated:** 2026-02-13
> **Status:** SHIPPED (Semester 6 Academic Project)
---
## 1. Overview
ProteinClassify is a full-stack bioinformatics dashboard that classifies protein sequences into 321 families using **ESM-2 transformer embeddings**, predicts 3D structures via **ESMFold**, and generates AI-powered biological insights using **Gemini 2.5 Flash**. It targets biology undergrads, researchers, and educators who need fast, interactive protein analysis without GPU infrastructure.
---
## 2. Problem Statement
Protein family classification traditionally requires deep bioinformatics expertise, access to large databases (Pfam, InterPro), and command-line tools. Students and early researchers need an accessible, visual tool that:
1. Classifies unknown protein sequences with high confidence
2. Visualizes where the protein sits in embedding space relative to known families
3. Predicts 3D structure from sequence alone
4. Explains results in human-readable biological language
---
## 3. Target Users
| Persona | Description | Primary Need |
|---------|-------------|--------------|
| **Biology Undergrad** | Learning about protein families | Quick classification + plain-language explanation |
| **Researcher** | Exploring novel sequences | Batch analysis, export, embedding visualization |
| **Educator** | Demonstrating ML in biology | Interactive demo with visual feedback |
---
## 4. Core Features
### 4.1 Single Sequence Classification
- **Input:** Amino acid sequence (paste or sample)
- **Output:** Predicted family, confidence score, PCA coordinates
- **API:** `POST /api/predict`
- **Validation:** Max 2,000 chars, standard amino acid alphabet only (ACDEFGHIKLMNPQRSTVWXY)
### 4.2 Batch FASTA Upload
- **Input:** `.fasta` file (drag-and-drop or file picker), up to 20 sequences
- **Output:** Sortable results table with family, confidence per sequence
- **API:** `POST /api/predict-batch`
- **Export:** CSV download, print-to-PDF
### 4.3 3D Structure Prediction
- **Source:** Meta's ESMFold API (single-sequence, no MSA required)
- **Visualization:** Interactive 3D viewer via NGL Viewer (rotate, zoom, color by chain)
- **API:** `POST /api/fold`
- **Limits:** Sequences capped at 400 residues for the public API
### 4.4 AI Biological Insights
- **Engine:** Google Gemini 2.5 Flash
- **Output:** Structured explanation — What is this family? Biological significance? Structural features? Fun fact.
- **API:** `POST /api/explain`
- **Requires:** `GEMINI_API_KEY` env var
### 4.5 Embedding Space Visualization
- **Method:** PCA (2-component) projection of 320-dim ESM-2 embeddings
- **Display:** Recharts scatter plot showing training data + user's protein
- **API:** `GET /api/data`
### 4.6 Sequence Property Heatmaps
- **Properties:** Hydrophobicity, polarity, charge
- **Display:** Color-coded residue-level heatmap (client-side, no API call)
---
## 5. User Stories & Acceptance Criteria
### 5.1 Student Learning
**As a** biology student,
**I want to** paste a protein sequence I found in a textbook,
**So that I can** see what family it belongs to and understand its function.
**Acceptance Criteria:**
- [ ] Paste inputs < 2000 chars are accepted.
- [ ] Classification returns within 3 seconds.
- [ ] "Predicted Family" is clearly displayed.
- [ ] AI explanation answers "What is this?" in simple terms.
- [ ] 3D viewer loads the structure automatically.
### 5.2 Researcher Batch Analysis
**As a** bioinformatics researcher,
**I want to** upload a FASTA file with 20 unknowns,
**So that I can** quickly filter them for specific transport proteins.
**Acceptance Criteria:**
- [ ] Drag-and-drop `.fasta` support.
- [ ] Progress bar shows batch processing status.
- [ ] Result table allows sorting by "Family" and "Confidence".
- [ ] "Export CSV" button downloads all inputs + predictions.
- [ ] Failed sequences (e.g., non-standard AAs) are highlighted in red.
### 5.3 Error Handling
**As a** user,
**I want** clear feedback when I enter invalid data,
**So that I** know how to fix it without page refresh.
**Acceptance Criteria:**
- [ ] Invalid characters (e.g., "B", "Z", numbers) trigger immediate red error below input.
- [ ] API rate limit (429) shows "Too many requests, please wait 1m" toast.
- [ ] Server error (500) shows a friendly "Service unavailable" message, not a stack trace.
---
## 6. UX/UI Flow
### 6.1 Analysis Flow
1. **Landing**: User sees "Analyze Protein" CTA or "Try Sample".
2. **Input**:
- *Action*: User pastes sequence OR uploads file.
- *Feedback*: Real-time validation (length/chars).
3. **Processing**:
- *State*: "Analyzing..." spinner overlay.
- *Action*: Frontend calls `/api/predict` (and `/api/fold` in parallel).
4. **Results**:
- *Success*: Dashboard reveals with animation.
- *Visualization*: Charts animate in (0 -> 100%).
- *Interaction*: User can rotate 3D model, hover heatmap coordinates.
---
## 7. Data Dictionary
### Protein Object (Internal & API)
| Field | Type | Description |
|-------|------|-------------|
| `sequence` | `string` | The amino acid sequence (cleaned). |
| `family` | `string` | Predicted label (e.g., "GLOBIN"). |
| `confidence`| `float` | Softmax probability (0.00-1.00). |
| `pca_x` | `float` | X-coordinate in 2D embedding space. |
| `pca_y` | `float` | Y-coordinate in 2D embedding space. |
| `pdb_data` | `string` | Raw PDB text for 3D viewer. |
| `explanation`| `string` | AI-generated text block. |
### Batch Item Object
| Field | Type | Description |
|-------|------|-------------|
| `name` | `string` | FASTA header (e.g., ">Seq1"). |
| `sequence` | `string` | The sequence content. |
| `status` | `enum` | `pending` \| `loading` \| `complete` \| `error` |
| `result` | `Protein` | Result object (if complete). |
| `error` | `string` | Error message (if error). |
---
## 8. Success Metrics
| Metric | Goal | Tracking Method |
|--------|------|-----------------|
| **Accuracy** | >95% Top-1 Accuracy | Test set validation log |
| **Latency** | <500ms (P95) | API response time log |
| **Retention** | >3 batch uploads/session | Client-side analytics (future) |
| **Error Rate** | <1% 5xx errors | Server error logs |
---
## 9. Architecture
```
┌─────────────────────┐ ┌──────────────────────────┐ ┌─────────────────┐
│ React Frontend │────▶│ Flask Backend (API) │────▶│ ESMFold API │
│ (Vite + Tailwind) │ │ │ │ (Meta) │
└─────────────────────┘ │ ┌─────────────────────┐ │ └─────────────────┘
│ │ ESM-2 Model (local) │ │
│ │ MLP Classifier │ │ ┌─────────────────┐
│ │ PCA Visualization │ │────▶│ Gemini 2.5 │
│ └─────────────────────┘ │ │ Flash API │
└──────────────────────────┘ └─────────────────┘
```
### Frontend Stack
| Technology | Version | Purpose |
|-----------|---------|---------|
| React | 19.2 | UI framework |
| Vite | 7.3 | Build tool / dev server |
| Tailwind CSS | 3.4 | Styling |
| Framer Motion | 12.x | Animations |
| Recharts | 3.7 | Embedding chart |
| NGL Viewer | 2.4 | 3D protein structure |
| Axios | 1.13 | HTTP client |
| Lucide React | 0.563 | Icons |
### Backend Stack
| Technology | Purpose |
|-----------|---------|
| Flask | API server |
| PyTorch + Transformers | ESM-2 embedding extraction |
| scikit-learn | MLP classifier + PCA |
| joblib | Model serialization |
| google-genai | Gemini API client |
### ML Pipeline
| Stage | Detail |
|-------|--------|
| **Model** | ESM-2 (`facebook/esm2_t6_8M_UR50D`) — 8M params, CPU-friendly |
| **Embeddings** | 320-dimensional per-sequence mean pooling |
| **Classifier** | MLP (scikit-learn) trained on ~2,000 PDB sequences |
| **Classes** | 321 protein families |
| **Artifacts** | `models/real_model.joblib`, `models/label_encoder.joblib` |
---
## 6. Pages & Components
### Pages
| Page | Route | Purpose |
|------|-------|---------|
| Home | `/` | Landing page — hero, features, process, CTA |
| Analyzer | `/analyze` | Main analysis workspace |
### Components
| Component | Parent | Purpose |
|-----------|--------|---------|
| `InputSection` | Analyzer | Sequence input, FASTA upload, sample buttons |
| `ResultsDashboard` | Analyzer | Orchestrates all result panels |
| `EmbeddingChart` | ResultsDashboard | PCA scatter plot (Recharts) |
| `StructureViewer` | ResultsDashboard | 3D protein viewer (NGL) |
| `SequenceHeatmap` | ResultsDashboard | Residue-level property heatmap |
| `ProteinExplainer` | ResultsDashboard | AI-generated insights panel |
| `BatchResults` | Analyzer | Sortable batch results table |
| `SkeletonDashboard` | Analyzer | Shimmer loading placeholders |
| `ErrorBoundary` | App | React error boundary |
---
## 7. API Contract
| Method | Endpoint | Rate Limit | Auth | Description |
|--------|----------|------------|------|-------------|
| `POST` | `/api/predict` | 30/min | Optional | Classify single sequence |
| `POST` | `/api/predict-batch` | 5/min | Optional | Classify up to 20 sequences |
| `POST` | `/api/fold` | 10/min | Optional | Predict 3D structure |
| `POST` | `/api/explain` | 15/min | Optional | AI biological explanation |
| `GET` | `/api/data` | 60/min | Optional | Training data for PCA plot |
### Security
- Input validation (regex, length limits)
- CORS restricted to configured origins
- Per-IP in-memory rate limiting
- Optional `X-API-Key` header auth
- Secure deserialization (joblib, not pickle)
- Error sanitization (generic client messages)
---
## 8. Configuration
| Variable | Required | Default | Purpose |
|----------|----------|---------|---------|
| `GEMINI_API_KEY` | Yes (for /explain) | — | Gemini AI insights |
| `FLASK_DEBUG` | No | `false` | Debug mode |
| `PORT` | No | `5000` | Backend port |
| `API_KEY` | No | — | Endpoint authentication |
| `CORS_ORIGINS` | No | `localhost:5173` | Allowed origins |
---
## 9. Non-Functional Requirements
| Requirement | Target |
|-------------|--------|
| **Performance** | Single prediction < 3s on CPU |
| **Responsiveness** | Mobile-first, hamburger nav, responsive typography |
| **Accessibility** | Semantic HTML, aria labels on interactive elements |
| **Loading UX** | Skeleton placeholders matching result layout |
| **Export** | CSV + print-to-PDF from dashboard |
| **Error Handling** | ErrorBoundary + per-endpoint error states |
---
## 10. Testing
| Suite | Count | Tool | Command |
|-------|-------|------|---------|
| Backend API tests | 19 | unittest | `venv/bin/python -m unittest tests.test_api -v` |
| Data loader tests | 3 | unittest | `venv/bin/python -m unittest tests.test_data_loader -v` |
| Frontend lint | — | ESLint | `cd frontend && npm run lint` |
| Frontend unit tests | — | Vitest | `cd frontend && npx vitest run` |
| CodeRabbit | — | GitHub PR review | Auto-review on push (chill mode) |
---
## 11. Known Limitations & Future Work
### Current Limitations
- ESMFold API has intermittent SSL issues (`esmatlas.com`)
- 321 families — limited coverage of full protein space
- ESM-2 8M variant — smallest model, lower accuracy than larger variants
- In-memory rate limiter resets on server restart
- No user authentication / session persistence
### Potential Enhancements
- [ ] User accounts + saved analysis history
- [ ] Upgrade to ESM-2 35M or 150M for better accuracy
- [ ] Multiple Sequence Alignment (MSA) support
- [ ] Comparison mode (classify 2 proteins side-by-side)
- [ ] Real-time structure prediction (local ESMFold instead of API)
- [ ] Dark mode toggle
- [ ] Redis-backed rate limiting for production
- [ ] CI/CD pipeline (GitHub Actions)
- [ ] PWA support for offline-capable sequence analysis
---
## 12. File Structure
```
sem6/
├── app.py # Flask API server
├── requirements.txt # Python dependencies
├── .env.example # Environment template
├── PRD.md # ← This document
├── PLAN.md # GSD execution plan
├── STATE.md # GSD session memory
├── src/
│ ├── embedding_extractor.py # ESM-2 embedding generation
│ ├── classifier.py # MLP neural network
│ └── data_loader.py # FASTA parsing & preprocessing
├── models/
│ ├── real_model.joblib # Trained MLP classifier
│ └── label_encoder.joblib # Label encoder (321 families)
├── data/
│ ├── embeddings_real.npy # Training embeddings for PCA
│ └── labels_real.npy # Training labels
├── tests/
│ ├── test_api.py # API endpoint tests (22 total)
│ └── test_data_loader.py # Data loader tests
├── frontend/
│ ├── src/
│ │ ├── App.jsx # Router, Nav, Footer
│ │ ├── pages/
│ │ │ ├── Home.jsx # Landing page
│ │ │ └── Analyzer.jsx # Analysis workspace
│ │ ├── components/ # 9 React components
│ │ └── utils/exportUtils # CSV/PDF export
│ └── package.json
├── scripts/ # Training & utility scripts
└── .coderabbit.yaml # CodeRabbit review config
```
---
## 13. Glossary
- **ESM-2**: Evolutionary Scale Modeling (v2). A transformer-based protein language model by Meta AI.
- **ESMFold**: An end-to-end atomic-level protein structure predictor based on ESM-2.
- **Embedding**: A fixed-size vector representation (320-dim) of a protein sequence.
- **PCA**: Principal Component Analysis. Dimensionality reduction technique (320D → 2D).
- **FASTA**: Text-based format for representing nucleotide or amino acid sequences.
- **PDB**: Protein Data Bank format. Atomic coordinate data for 3D structures.
- **Residue**: A single monomer within the protein chain (i.e., one amino acid).
- **Gemini**: Google's multimodal AI model, used here for text explanation.
SkillSprout is an AI-powered microlearning platform designed to help users learn new skills through bite-sized lessons and adaptive quizzes. The platform leverages Azure OpenAI for content generation, Gradio for user interaction, and Model Context Protocol (MCP) for agent interoperability.
This dashboard is a web-based interface built using **Next.js (or Astro)** and hosted on **Vercel**. It acts as the control center for Joey’s stock intelligence, allowing you to:
Gemini Code Flow is an advanced AI-powered development orchestration platform that adapts RuV's Claude Code Flow for Google's Gemini CLI. It enables developers to leverage multiple AI agents working in parallel to write, test, and optimize code using the SPARC methodology.
**Version: 6.0 (FINAL)**