ReViewPoint System Architecture¶

Welcome to the technical architecture overview for ReViewPoint—a modular, scalable, and LLM-powered platform for scientific paper review. This document provides a visual and narrative guide to the system’s structure, data flow, and extensibility.

High-Level System Structure¶

flowchart TD
    ROOT[project-root]
    BACKEND[backend/]:::backend
    DOCS[docs/]:::docs
    FRONTEND[frontend/]:::frontend
    ROOT --> BACKEND
    ROOT --> DOCS
    ROOT --> FRONTEND
    BACKEND --> B_SRC[src/]:::backend
    BACKEND --> B_TESTS[tests/]:::backend
    DOCS --> D_CONTENT[content/]:::docs
    DOCS --> D_OVERRIDES[overrides/]:::docs
    FRONTEND --> F_SRC[src/]:::frontend
    FRONTEND --> F_PUBLIC[public/]:::frontend
    classDef backend fill:#f9f,stroke:#333,stroke-width:2px;
    classDef docs fill:#bbf,stroke:#333,stroke-width:2px;
    classDef frontend fill:#bfb,stroke:#333,stroke-width:2px;
    click BACKEND "#backend-details" "See backend details"
    click DOCS "#docs-details" "See docs details"
    click FRONTEND "#frontend-details" "See frontend details"

Directory Structure & Legends¶

Backend Details (src/)¶

Backend src/ Communication Overview¶

flowchart

    %% Nodes
    MAIN[main.py]
    API[api/]
    MIDDLEWARE[middlewares/]
    SERVICES[services/]
    SCHEMAS[schemas/]
    UTILS[utils/]
    REPOS[repositories/]
    MODELS[models/]
    CORE[core/]

    %% Grouping (visual only)
    subgraph Application_Entry
        MAIN
    end
    subgraph Web_Layer
        API
        MIDDLEWARE
    end
    subgraph Core_Logic
        SERVICES
        SCHEMAS
        UTILS
    end
    subgraph Data_Layer
        REPOS
        MODELS
    end
    subgraph Configuration
        CORE
    end

    %% Relationships
    MAIN --> API
    MAIN --> MIDDLEWARE
    MAIN --> SERVICES
    MAIN --> REPOS
    MAIN --> SCHEMAS
    MAIN --> MODELS
    MAIN --> CORE
    MAIN --> UTILS

    API -->|routes use| SERVICES
    API -->|schemas for requests| SCHEMAS
    API -->|helpers from| UTILS
    API --> MIDDLEWARE

    SERVICES -->|CRUD through| REPOS
    SERVICES -->|validate with| SCHEMAS
    SERVICES -->|helpers| UTILS

    REPOS -->|query| MODELS
    REPOS -->|return| SCHEMAS
    REPOS -->|log/hash| UTILS

    SCHEMAS <-->|shared structure| MODELS

    MIDDLEWARE -->|reads| CORE
    CORE --> API
    CORE --> SERVICES
    CORE --> MIDDLEWARE
    CORE --> UTILS

    %% Styling
    classDef entry fill:#fff2cc,stroke:#333,stroke-width:2px;
    classDef web fill:#d5e8d4,stroke:#333,stroke-width:2px;
    classDef core fill:#dae8fc,stroke:#333,stroke-width:2px;
    classDef data fill:#f8cecc,stroke:#333,stroke-width:2px;
    classDef config fill:#e1d5e7,stroke:#333,stroke-width:2px;

    class MAIN entry;
    class API,MIDDLEWARE web;
    class SERVICES,SCHEMAS,UTILS core;
    class REPOS,MODELS data;
    class CORE config;

Docs Structure¶

flowchart TD
    D_CONTENT[docs/content/]:::docs
    D_CONTENT --> D_BACKEND[backend/]:::docs
    D_CONTENT --> D_FRONTEND[frontend/]:::docs
    D_CONTENT --> D_IMAGES[images/]:::docs
    D_CONTENT --> D_SRC[src/]:::docs
    D_CONTENT --> D_TESTS[tests/]:::docs
    D_CONTENT --> D_INDEX[index.md]:::docs
    classDef docs fill:#bbf,stroke:#333,stroke-width:2px;
    click D_BACKEND "#docs-backend" "Backend documentation"
    click D_FRONTEND "#docs-frontend" "Frontend documentation"
    click D_IMAGES "#docs-images" "Documentation images"
    click D_SRC "#docs-src" "Docs source code (if any)"
    click D_TESTS "#docs-tests" "Docs test files (if any)"
    click D_INDEX "#docs-index" "Docs homepage"

Docs Legend¶

Frontend Structure¶

flowchart TD
    F_SRC[frontend/src/]:::frontend
    %% Add more as your frontend grows
    classDef frontend fill:#bfb,stroke:#333,stroke-width:2px;

Frontend Legend¶

Component Interactions & Data Flow¶

Data Flow Diagram¶

graph LR
  PDF[PDF Upload] -->|HTTP| API[FastAPI API]
  API -->|Parse/Dispatch| MODS[Modules]
  MODS -->|Results| API
  API -->|Prompt| LLM[LLM Adapter]
  LLM -->|LLM Output| API
  API -->|Aggregate| FE[Frontend]
  API --> DB[(PostgreSQL)]
  API --> STORAGE[(MinIO/S3)]

Sequence: Module Dispatch & LLM Interaction¶

sequenceDiagram
  participant FE as Frontend
  participant API as FastAPI Backend
  participant MOD as Module Service(s)
  participant LLM as LLM Adapter
  participant DB as Database
  participant STORAGE as MinIO/S3

  FE->>API: Upload PDF / Submit for Analysis
  API->>STORAGE: Store PDF
  API->>DB: Save file metadata
  API->>MOD: Dispatch analysis request(s)
  MOD-->>API: Module results
  API->>LLM: Prompt for summary/feedback
  LLM-->>API: LLM output
  API->>DB: Store results
  API-->>FE: Aggregated results & feedback

Data Flow Summary¶

Backend Details¶

• Core: config.py, database.py, logging.py, security.py, events.py
• API: deps.py, v1/ (auth, uploads, users)
• Models: base.py, user.py, file.py, used_password_reset_token.py
• Repositories: user.py, file.py
• Services: user.py, upload.py
• Middlewares: logging.py
• Utils: hashing.py, file.py, cache.py, errors.py, rate_limit.py, validation.py
• Migrations: alembic_migrations/
• Entry Point: main.py

Frontend Details¶

• Stack: React, Vite, TailwindCSS
• Responsibilities:
• User authentication and session management
• PDF upload and preview
• Display of module results and LLM summaries
• Interaction with backend via REST API
• Responsive UI and error handling

Docs Details¶

• Docs: MkDocs for live documentation
• Content: Markdown, API docs, images
• Overrides: Custom theme, 404 page, etc.

Scalability & Extensibility Features¶

• Modular Microservices: Each analysis module is a Dockerized REST service, independently deployable and testable.
• Parallel Evaluation: Backend can dispatch multiple modules in parallel for faster analysis.
• Plug-and-Play LLM Providers: Easily switch between OpenAI, vLLM, or future providers.
• Decoupled CI/CD: Modules and core backend have separate CI pipelines for independent development.
• Observability: Optional Prometheus/Grafana integration for monitoring and metrics.
• Extensible API: Versioned API structure allows safe evolution of endpoints.

Standard Module Output Example¶

{
  "module_name": "structure_validator",
  "score": 78,
  "status": "warning",
  "feedback": ["Missing conclusion section.", "Introduction too short."],
  "version": "1.0.0"
}

For more details on each segment, see the Backend Source Guide, Module Guide, and Frontend Overview