# andyly213/ai-peer-review-platform architecture

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

- Interactive diagram: https://gitdiagram.com/andyly213/ai-peer-review-platform
- Repository: https://github.com/andyly213/ai-peer-review-platform

## Overview

##### Project type and purpose
- This is an open-source multi-agent simulation tool written in Python.
- It models the academic peer-review process as a token-based economy, using AutoGen to orchestrate AI agents and Ollama as the LLM backend.
- It integrates with the PeerRead dataset for realistic paper and review data.

##### Main architectural components
a. Entry Point & Configuration
- main.py / src/simulation/peer_review_simulation.py
- config/ (environment variables for Ollama model and API endpoint)
b. Data Layer
- src/data/paper_database.py: loads PeerRead or test dataset
- src/data/create_test_dataset.py + test_dataset/: generate and store a small subset
- src/data/token_system.py: manages the token economy logic
c. Core Multi-Agent System
- src/core/multi_agent_system.py: base class
- src/core/enhanced_multi_agent_system.py / customizable_agent_system.py: specialized system behaviors
- src/core/agent_factory.py & agent_templates.py: factory pattern for creating agents
d. Agents
- src/agents/editor_agent.py: simulates editors who request reviews
- src/agents/researcher_agent.py: simulates researchers who write and review
- src/agents/researcher_templates.py: prompt templates defining agent behavior
e. Simulation Orchestrator
- peer_review_simulation.py: ties data loading, agent instantiation, and the simulation loop
f. External Services
- Ollama LLM API (configured via OLLAMA_API_BASE)
- AutoGen library for multi-agent interaction

##### Relationships and data flows
- Start at main.py → load environment config → initialize PaperDatabase
- Database loads papers from test_dataset/ or full PeerRead
- TokenSystem instantiates initial token counts
- AgentFactory creates EditorAgent and multiple ResearcherAgents (using agent_templates)
- EnhancedMultiAgentSystem registers agents and orchestrates turn-based interactions
- Editors submit papers → Researchers pull review tasks → Researchers earn/spend tokens
- All agent-to-agent calls go through AutoGen which dispatches to Ollama API
- Simulation orchestrator collects results, metrics, and outputs statistics

##### Architectural patterns and design principles
- Factory pattern: agent_factory.py
- Template method pattern: researcher_templates.py defines prompt structures
- Layered architecture: clear separation between Data, Core, Agents, Simulation
- Plugin-style extensibility: add new agent types or dataset handlers

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point & Orchestrator
    Entry["main.py"]:::orchestrator
    Orchestrator["PeerReviewSimulation\n(src/simulation/peer_review_simulation.py)"]:::orchestrator

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        PaperDB["PaperDatabase\n(src/data/paper_database.py)"]:::data
        CreateTest["create_test_dataset\n(src/data/create_test_dataset.py)"]:::data
        TestDB["test_paper_database\n(src/data/test_paper_database.py)"]:::data
    end

    %% Core System
    subgraph "Core System"
        direction TB
        TokenSys["TokenSystem\n(src/core/token_system.py)"]:::core
        MASBase["MultiAgentSystem\n(src/core/multi_agent_system.py)"]:::core
        EnhancedMAS["EnhancedMultiAgentSystem\n(src/core/enhanced_multi_agent_system.py)"]:::core
        CustomMAS["CustomizableAgentSystem\n(src/core/customizable_agent_system.py)"]:::core
        AgentFactory["AgentFactory\n(src/core/agent_factory.py)"]:::core
        Templates["AgentTemplates\n(src/core/agent_templates.py)"]:::core
    end

    %% Agents
    subgraph "Agents"
        direction TB
        Editor["EditorAgent\n(src/agents/editor_agent.py)"]:::agents
        Researcher["ResearcherAgent\n(src/agents/researcher_agent.py)"]:::agents
        RTemplates["ResearcherTemplates\n(src/agents/researcher_templates.py)"]:::agents
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AutoGen["AutoGen Library"]:::external
        Ollama["Ollama LLM API"]:::external
    end

    %% Flows
    Entry -->|"start simulation"| Orchestrator
    Orchestrator -->|"load_peerread_dataset()"| PaperDB
    PaperDB -->|"use test subset"| TestDB
    PaperDB -->|"create subset"| CreateTest

    Orchestrator -->|"init token economy"| TokenSys
    Orchestrator -->|"instantiate agents"| AgentFactory
    Orchestrator -->|"orchestrate turns"| EnhancedMAS

    AgentFactory -->|"create EditorAgent"| Editor
    AgentFactory -->|"create ResearcherAgent"| Researcher
    AgentFactory -->|"use templates"| Templates
    AgentFactory -->|"use researcher prompts"| RTemplates

    EnhancedMAS -->|"base behaviors"| MASBase
    EnhancedMAS -->|"plugin custom behaviors"| CustomMAS
    EnhancedMAS -->|"register agents"| Editor
    EnhancedMAS -->|"register agents"| Researcher
    EnhancedMAS -->|"dispatch via"| AutoGen

    Editor -->|"send_prompt() →"| Ollama
    Researcher -->|"send_prompt() →"| Ollama

    %% Click Events
    click Entry "https://github.com/andyly213/ai-peer-review-platform/blob/master/main.py"
    click Orchestrator "https://github.com/andyly213/ai-peer-review-platform/blob/master/src/simulation/peer_review_simulation.py"
    click PaperDB "https://github.com/andyly213/ai-peer-review-platform/blob/master/src/data/paper_database.py"
    click CreateTest "https://github.com/andyly213/ai-peer-review-platform/blob/master/src/data/create_test_dataset.py"
    click TestDB "https://github.com/andyly213/ai-peer-review-platform/blob/master/src/data/test_paper_database.py"
    click TokenSys "https://github.com/andyly213/ai-peer-review-platform/blob/master/src/core/token_system.py"
    click MASBase "https://github.com/andyly213/ai-peer-review-platform/blob/master/src/core/multi_agent_system.py"
    click EnhancedMAS "https://github.com/andyly213/ai-peer-review-platform/blob/master/src/core/enhanced_multi_agent_system.py"
    click CustomMAS "https://github.com/andyly213/ai-peer-review-platform/blob/master/src/core/customizable_agent_system.py"
    click AgentFactory "https://github.com/andyly213/ai-peer-review-platform/blob/master/src/core/agent_factory.py"
    click Templates "https://github.com/andyly213/ai-peer-review-platform/blob/master/src/core/agent_templates.py"
    click Editor "https://github.com/andyly213/ai-peer-review-platform/blob/master/src/agents/editor_agent.py"
    click Researcher "https://github.com/andyly213/ai-peer-review-platform/blob/master/src/agents/researcher_agent.py"
    click RTemplates "https://github.com/andyly213/ai-peer-review-platform/blob/master/src/agents/researcher_templates.py"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef agents fill:#FFA500,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
