Spaces:
Sleeping
Sleeping
Architecture & System Design
🏗️ System Architecture Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ CLIENT LAYER │
│ │
│ ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────────┐ │
│ │ Next.js Web │ │ React Flow UI │ │ Visualization Layer │ │
│ │ (Frontend) │ │ (Graph Browser) │ │ D3.js, Cytoscape │ │
│ └────────┬────────┘ └────────┬─────────┘ └────────────┬────────────┘ │
│ │ │ │ │
│ └────────────────────┼─────────────────────────┘ │
│ │ HTTPS/REST │
│ ↓ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ API GATEWAY LAYER │
│ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ FastAPI Router │ │
│ │ GET/POST /api/v1/analysis/run │ │
│ │ GET /api/v1/analysis/{id}/results │ │
│ │ POST /api/v1/papers/upload │ │
│ │ GET /api/v1/health/ready │ │
│ │ [+ 20+ more endpoints] │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ ↓ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ ORCHESTRATION LAYER │
│ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ LangGraph State Machine │ │
│ │ │ │
│ │ [Input] → [Extract] → [Contradictions] → [Hypotheses] │ │
│ │ ↓ ↓ ↓ │ │
│ │ [Gaps] → [Protocols (3x)] → [Self-Critique] │ │
│ │ ↓ │ │
│ │ [Output] │ │
│ │ │ │
│ │ • Multi-step reasoning workflow │ │
│ │ • Self-consistency layer (3 versions → best selection) │ │
│ │ • Fallback to LLM if K2 unavailable │ │
│ │ • Audit trail of every step │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ ↓ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ SERVICES LAYER │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Analysis │ │ Paper │ │ Project │ │ Protocol │ │
│ │ Service │ │ Service │ │ Service │ │ Service │ │
│ │ │ │ │ │ │ │ │ │
│ │ • Run │ │ • Upload │ │ • Create │ │ • Generate │ │
│ │ • Track │ │ • Parse │ │ • Manage │ │ • Validate │ │
│ │ • Results │ │ • Chunk │ │ • Query │ │ • Export │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ PROCESSING LAYER │
│ │
│ ┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ PDF Parser │ │ Embeddings │ │ K2 Think Client │ │
│ │ │ │ Generator │ │ │ │
│ │ • PyMuPDF │ │ │ │ • Analyze │ │
│ │ • PyPDF2 │ │ • OpenAI API │ │ • Generate │ │
│ │ • Unstructured │ │ • Fallback LLM │ │ • Critique │ │
│ │ │ │ │ │ │ │
│ └────────┬────────┘ └────────┬─────────┘ └────────┬─────────┘ │
│ │ │ │ │
│ └────────────────────┼─────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────────────┐ │
│ │ Vector Store & Semantic Search │ │
│ │ (Qdrant Integration) │ │
│ └──────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ DATA PERSISTENCE LAYER │
│ │
│ ┌─────────────────────────┐ ┌─────────────────────────────────────────┐ │
│ │ PostgreSQL (Primary) │ │ Qdrant (Vector DB) │ │
│ │ │ │ │ │
│ │ ├─ users │ │ ├─ paper_embeddings │ │
│ │ ├─ projects │ │ ├─ chunk_embeddings │ │
│ │ ├─ research_papers │ │ └─ semantic_search_index │ │
│ │ ├─ paper_chunks │ │ │ │
│ │ ├─ analysis_runs │ │ + Hybrid search (keyword + semantic) │ │
│ │ ├─ contradictions │ │ │ │
│ │ ├─ hypotheses │ │ │ │
│ │ ├─ protocols │ │ │ │
│ │ ├─ reasoning_traces │ │ │ │
│ │ ├─ activity_logs │ │ │ │
│ │ └─ research_gaps │ │ │ │
│ │ │ │ │ │
│ │ UUID Primary Keys │ │ Persistent Collections │ │
│ │ JSONB for flexibility │ │ Fast similarity search │ │
│ │ Audit trail support │ │ Metadata filtering │ │
│ │ │ │ │ │
│ └─────────────────────────┘ └─────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ INFRASTRUCTURE LAYER │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Docker │ │ Redis │ │ PostgreSQL │ │ Qdrant │ │
│ │ Containers │ │ (Cache) │ │ (Primary │ │ (Vector │ │
│ │ │ │ │ │ Data) │ │ Search) │ │
│ │ • API │ │ • Queue │ │ │ │ │ │
│ │ • Workers │ │ • Cache │ │ • Cluster │ │ • Cluster │ │
│ │ • Compose │ │ • Sessions │ │ • Backup │ │ • Replicas │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Deployment Orchestration │ │
│ │ • Railway (Hackathon - simple) │ │
│ │ • Kubernetes (Startup - scalable) │ │
│ │ • AWS ECS / GCP Cloud Run (Enterprise) │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
🔄 Data Flow Diagram
1. USER UPLOADS PAPERS
↓
User → [Frontend Upload] → FastAPI /papers/upload → Storage
2. SYSTEM PROCESSES WITH ORCHESTRATION
↓
Papers → [PDFParser] → [Chunking] → [Embeddings]
↓ ↓ ↓
Content ←──┴──────────────┴────────────┴→ [Qdrant Vector DB]
3. ANALYSIS WORKFLOW (LangGraph)
↓
[Extract] → [Contradictions] → [Hypotheses] → [Gaps]
↓ ↓ ↓ ↓
Use: K2 API + OpenAI LLM for each step
4. PROTOCOL GENERATION WITH SELF-CRITIQUE
↓
[Generate v1] ─┐
[Generate v2] ─┼→ [Select Best] → [Validate] → [Store]
[Generate v3] ─┘
5. RESULTS STORED & QUERYABLE
↓
PostgreSQL ← [Analysis Results]
PostgreSQL ← [Contradictions]
PostgreSQL ← [Protocols]
PostgreSQL ← [Audit Trail]
6. FRONTEND VISUALIZES
↓
Results → [API] → [React Components] → [User Views]
↓
Reasoning Trace → [React Flow Graph]
Contradictions → [Data Table + Severity]
Protocols → [Rich Editor + Export]
📊 Technology Stack Layers
┌──────────────────────────────────────────────────────────────┐
│ PRESENTATION LAYER │
│ Next.js | React 18 | Tailwind CSS | React Flow | D3.js │
└──────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────┐
│ API LAYER │
│ FastAPI | Uvicorn | Pydantic | OpenAPI (Swagger) │
└──────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────┐
│ ORCHESTRATION LAYER │
│ LangGraph | LangChain | K2 Think API | OpenAI GPT-4 │
└──────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────┐
│ PROCESSING LAYER │
│ PyMuPDF | Unstructured | sentence-transformers | Qdrant │
└──────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────┐
│ DATA LAYER │
│ PostgreSQL | SQLAlchemy | Qdrant | Redis │
└──────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────┐
│ INFRASTRUCTURE LAYER │
│ Docker | Docker Compose | Kubernetes/Railway/AWS │
└──────────────────────────────────────────────────────────────┘
🚀 Deployment Architecture
Development (Local)
┌─────────────────────────────────────┐
│ Docker Compose on Localhost │
├─────────────────────────────────────┤
│ Frontend (Next.js) :3000 │
│ API (FastAPI) :8000 │
│ PostgreSQL :5432 │
│ Qdrant :6333 │
│ Redis :6379 │
└─────────────────────────────────────┘
Hackathon (Railway)
┌─────────────────────────────────────┐
│ Railway.app │
├─────────────────────────────────────┤
│ API Service │
│ ├─ Auto-scaling │
│ ├─ Load balancing │
│ └─ HTTPS + domain │
│ │
│ PostgreSQL (Managed) │
│ Redis (Managed) │
│ Environment variables │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Vercel.app │
├─────────────────────────────────────┤
│ Next.js Frontend │
│ ├─ Edge functions │
│ ├─ CDN │
│ └─ Analytics │
└─────────────────────────────────────┘
Production (AWS)
┌──────────────────────────────────────────────────────────┐
│ AWS Region │
├──────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────┐ │
│ │ API Tier │ │
│ │ ├─ Application Load Balancer (ALB) │ │
│ │ ├─ ECS Fargate (Auto-scaling) │ │
│ │ ├─ CloudWatch Logs │ │
│ │ └─ EC2 Auto Scaling Groups │ │
│ └─────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Data Tier │ │
│ │ ├─ RDS PostgreSQL (Multi-AZ) │ │
│ │ ├─ ElastiCache Redis │ │
│ │ ├─ S3 for PDF storage │ │
│ │ └─ Secrets Manager │ │
│ └─────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Vector Search Tier │ │
│ │ ├─ Qdrant cluster (3-5 nodes) │ │
│ │ ├─ OpenSearch Domain (optional) │ │
│ │ └─ CloudFront distribution │ │
│ └─────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Frontend Tier │ │
│ │ ├─ CloudFront CDN │ │
│ │ ├─ Route 53 DNS │ │
│ │ └─ Certificate Manager SSL/TLS │ │
│ └─────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Monitoring & Analytics │ │
│ │ ├─ CloudWatch │ │
│ │ ├─ X-Ray tracing │ │
│ │ ├─ GuardDuty (security) │ │
│ │ └─ Cost Explorer │ │
│ └─────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
🔐 Security Architecture
┌─────────────────────────────────────────────────────────┐
│ SECURITY LAYERS │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─ Network Level ─────────────────────────────────┐ │
│ │ • VPC isolation (AWS) │ │
│ │ • Security groups (firewall rules) │ │
│ │ • WAF (Web Application Firewall) │ │
│ │ • DDoS protection (CloudFlare/AWS Shield) │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─ Transport Level ───────────────────────────────┐ │
│ │ • HTTPS/TLS 1.3 │ │
│ │ • Certificate pinning │ │
│ │ • Encryption in transit │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─ Application Level ─────────────────────────────┐ │
│ │ • API authentication (JWT tokens) │ │
│ │ • Rate limiting │ │
│ │ • Input validation & sanitization │ │
│ │ • CORS configuration │ │
│ │ • Security headers (CSP, HSTS) │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─ Data Level ────────────────────────────────────┐ │
│ │ • Database encryption at rest │ │
│ │ • Password hashing (bcrypt) │ │
│ │ • Secrets management (AWS Secrets Manager) │ │
│ │ • PII masking in logs │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─ Audit & Compliance ────────────────────────────┐ │
│ │ • Activity logging (all operations) │ │
│ │ • Audit trail immutability │ │
│ │ • Data retention policies │ │
│ │ • Compliance monitoring (GDPR, HIPAA) │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
📈 Scalability Path
Phase 1: MVP (Hackathon)
├─ Docker Compose locally
├─ Single API server
├─ PostgreSQL single instance
├─ Qdrant single node
└─ Manual scaling
↓
Phase 2: Early Startup
├─ Railway deployment
├─ Managed database
├─ Redis cluster
├─ Qdrant cluster (3 nodes)
├─ Auto-scaling enabled
└─ ~1k users
↓
Phase 3: Growth
├─ AWS multi-region
├─ RDS Multi-AZ
├─ Load balancing
├─ Caching strategy
├─ Async processing
└─ ~10k users
↓
Phase 4: Enterprise
├─ Kubernetes cluster
├─ Database sharding
├─ Vector DB cluster
├─ Multiple regions
├─ Advanced monitoring
└─ ~100k+ users
🎯 Summary
| Component | Technology | Role |
|---|---|---|
| Frontend | Next.js, React, Tailwind | User interface |
| API | FastAPI, Uvicorn | REST endpoints |
| Orchestration | LangGraph, LangChain | Multi-step workflows |
| AI | K2 Think V2, OpenAI GPT-4 | Deep reasoning |
| Document Processing | PyMuPDF, Unstructured | PDF extraction |
| Embeddings | OpenAI embeddings | Vector generation |
| Vector Search | Qdrant | Semantic search |
| Primary DB | PostgreSQL | Structured data |
| Cache | Redis | Performance |
| Deployment | Docker, Railway/AWS | Infrastructure |
This architecture is hackathon-ready AND scalable to production! 🚀