How nateislas/paperwise works
Main Components
a. Client Side
• Web Browser + React-TypeScript Frontend
• Chrome Extension (popup, content script, background script)
b. API Layer
• Nginx reverse proxy (serves frontend, routes API calls)
• FastAPI Backend (app.main)
c. AI & Processing
• Multi-Agent System modules (PDF Parser, Methodology, Results, Contextualization, Orchestrator) inside the backend
• AnalysisManager & job orchestration
d. Data & State
• Redis (job queue / state store)
• File system (uploads directory)
e. External Services
• Llama API (external AI inference)
f. Infrastructure
• Docker & Docker-Compose (container orchestration)
• nginx.conf, redis.conf
Relationships and Data Flows
• User uploads PDF or issues query via Web UI or Chrome Extension →
→ Nginx → FastAPI endpoint (/analyses, /analysis)
• FastAPI receives request → stores file in upload directory → logs job state in Redis →
→ invokes AnalysisManager → uses OrchestratorAgent to coordinate sub-agents
• Agents call PyMuPDF (local) for parsing and Llama API for ML inference →
→ collate results → update Redis/job state →
→ FastAPI pushes real-time progress (Server-Sent Events or WebSockets) →
→ Frontend streams results back to user
• Chrome Extension can directly call the same FastAPI endpoints (bypassing the web UI) for in-page analysis
Architectural Patterns & Principles
• Full-stack separation: UI (React), API (FastAPI)
• Modular AI agents (strategy pattern) within a single service
• Stateless API + external stateful store (Redis)
• Reverse proxy pattern (Nginx)
• Containerization (one container per service)
Technologies & Libraries to Annotate
• Frontend: React 18, TypeScript, Tailwind CSS
• Backend: FastAPI, Python 3.8+, LangChain, PyMuPDF
• Agents: base_agent.py, orchestrator_agent.py, contextualization_agent.py, etc.
• Persistence & Queue: Redis
• External AI: Meta Llama API
• DevOps: Dockerfile (frontend & backend), docker-compose.yml, nginx.conf
Detailed Component Breakdown (to include
• Frontend Container
• Components: FileUpload, SearchBar, StreamingAnalysisResults, etc.
• Served via Nginx at port 3000
• Chrome Extension
• popup.html/js, background.js, content.js
• Permissions & Content-script injection
• Nginx
• Serves static assets, reverse-proxies /api/* to FastAPI on port 8000
• Backend Container
• main.py → Uvicorn
• Routers: analyses.py, analysis.py
• Worker (worker.py) invokes AnalysisManager
• Config & job_state modules
• Agents
• PDFParserAgent → PyMuPDF
• MethodologyAgent, ResultsAgent, ContextualizationAgent, FieldClassifierAgent
• OrchestratorAgent ties them together
• Redis
• Used by job_state to track progress
• File System Uploads
• Directory: uploads/ (configurable via UPLOAD_DIR)
• External AI API
• Llama API calls over HTTPS