Spaces:
Running
Running
| # 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!** 🚀 | |