# nateislas/paperwise architecture

> Architecture diagram of the GitHub repository nateislas/paperwise, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nateislas/paperwise
- Repository: https://github.com/nateislas/paperwise

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
graph TB
    %% Layer 1: Client Layer
    subgraph "Client Layer"
        Browser["Web Browser\n(React-TypeScript)"]:::frontend
        ChromeExt["Chrome Extension"]:::frontend
    end

    %% Layer 2: Presentation Layer
    subgraph "Presentation Layer"
        FrontendContainer["Frontend Container"]:::frontend
        Nginx["Nginx Reverse Proxy"]:::infra
    end

    %% Layer 3: Application Layer
    subgraph "Application Layer"
        FastAPI["FastAPI Backend\n(Uvicorn)"]:::backend
        AnalysesRouter["analyses.py"]:::backend
        AnalysisRouter["analysis.py"]:::backend
        Worker["worker.py"]:::backend
        AnalysisManager["analysis_manager.py"]:::backend
        JobState["job_state.py"]:::backend
        Config["config.py"]:::backend

        subgraph "Multi-Agent System" 
            OrchestratorAgent["orchestrator_agent.py"]:::ai
            PDFAgent["pdf_parser_agent.py"]:::ai
            MethodologyAgent["methodology_agent.py"]:::ai
            ResultsAgent["results_agent.py"]:::ai
            ContextAgent["contextualization_agent.py"]:::ai
            FieldAgent["field_classifier_agent.py"]:::ai
        end
    end

    %% Layer 4: Data & External Layer
    subgraph "Data & External"
        Redis["Redis"]:::external
        FileSystem["File Storage\nuploads/"]:::infra
        LlamaAPI["Llama API"]:::external
    end

    %% Infrastructure Tools
    subgraph "Infrastructure"
        Compose["docker-compose.yml"]:::infra
        BackendImage["backend/Dockerfile"]:::infra
        FrontendImage["frontend/Dockerfile"]:::infra
        NginxConfig["nginx.conf"]:::infra
        RedisConfig["redis.conf"]:::infra
        StartScripts["start-paperwise.sh\nquick-start.sh"]:::infra
    end

    %% Connections
    Browser --> FrontendContainer
    Browser --> Nginx
    ChromeExt --> Nginx
    ChromeExt --> FastAPI

    FrontendContainer --> Nginx
    Nginx --> FastAPI

    FastAPI --> AnalysesRouter
    FastAPI --> AnalysisRouter

    AnalysesRouter --> Worker
    AnalysisRouter --> Worker

    Worker --> AnalysisManager
    Worker --> JobState
    Worker --> Redis

    AnalysisManager --> OrchestratorAgent

    OrchestratorAgent --> PDFAgent
    OrchestratorAgent --> MethodologyAgent
    OrchestratorAgent --> ResultsAgent
    OrchestratorAgent --> ContextAgent
    OrchestratorAgent --> FieldAgent

    PDFAgent --> FileSystem
    MethodologyAgent --> LlamaAPI
    ResultsAgent --> LlamaAPI
    ContextAgent --> LlamaAPI
    FieldAgent --> LlamaAPI

    PDFAgent --> Redis
    MethodologyAgent --> Redis
    ResultsAgent --> Redis
    ContextAgent --> Redis
    FieldAgent --> Redis

    Redis --> FastAPI
    FastAPI --> Browser

    Compose --> FrontendContainer
    Compose --> FastAPI
    Compose --> Redis
    Compose --> Nginx

    %% Click Events
    click Browser "https://github.com/nateislas/paperwise/tree/main/frontend/"
    click FrontendContainer "https://github.com/nateislas/paperwise/tree/main/frontend/Dockerfile"
    click ChromeExt "https://github.com/nateislas/paperwise/tree/main/chrome-extension/"
    click Nginx "https://github.com/nateislas/paperwise/blob/main/nginx.conf"
    click FastAPI "https://github.com/nateislas/paperwise/blob/main/backend/app/main.py"
    click AnalysesRouter "https://github.com/nateislas/paperwise/blob/main/backend/app/routers/analyses.py"
    click AnalysisRouter "https://github.com/nateislas/paperwise/blob/main/backend/app/routers/analysis.py"
    click Worker "https://github.com/nateislas/paperwise/blob/main/backend/app/worker.py"
    click AnalysisManager "https://github.com/nateislas/paperwise/blob/main/backend/app/analysis_manager.py"
    click JobState "https://github.com/nateislas/paperwise/blob/main/backend/app/job_state.py"
    click Config "https://github.com/nateislas/paperwise/blob/main/backend/app/config.py"
    click OrchestratorAgent "https://github.com/nateislas/paperwise/blob/main/backend/app/agents/orchestrator_agent.py"
    click PDFAgent "https://github.com/nateislas/paperwise/blob/main/backend/app/agents/pdf_parser_agent.py"
    click MethodologyAgent "https://github.com/nateislas/paperwise/blob/main/backend/app/agents/methodology_agent.py"
    click ResultsAgent "https://github.com/nateislas/paperwise/blob/main/backend/app/agents/results_agent.py"
    click ContextAgent "https://github.com/nateislas/paperwise/blob/main/backend/app/agents/contextualization_agent.py"
    click FieldAgent "https://github.com/nateislas/paperwise/blob/main/backend/app/agents/field_classifier_agent.py"
    click Compose "https://github.com/nateislas/paperwise/blob/main/docker-compose.yml"
    click BackendImage "https://github.com/nateislas/paperwise/tree/main/backend/Dockerfile"
    click FrontendImage "https://github.com/nateislas/paperwise/tree/main/frontend/Dockerfile"
    click NginxConfig "https://github.com/nateislas/paperwise/blob/main/nginx.conf"
    click RedisConfig "https://github.com/nateislas/paperwise/blob/main/redis.conf"
    click StartScripts "https://github.com/nateislas/paperwise/blob/main/start-paperwise.sh"

    %% Styles
    classDef frontend fill:#cef2ff,stroke:#0066cc,color:#003366
    classDef backend fill:#e0ffe0,stroke:#009900,color:#005500
    classDef ai fill:#ffe5b4,stroke:#ff8000,color:#994d00
    classDef infra fill:#dddddd,stroke:#666666,color:#333333
    classDef external fill:#f0e6ff,stroke:#8000ff,color:#4b0082
```
