# ulab-uiuc/research-town architecture

> Architecture diagram of the GitHub repository ulab-uiuc/research-town, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ulab-uiuc/research-town
- Repository: https://github.com/ulab-uiuc/research-town

## Overview

##### Main Components Identification

a) Core Components:
- Agents System (research_town/agents/)
- Environment System (research_town/envs/)
- Engine System (research_town/engines/)
- Database System (research_town/dbs/)
- Configuration System (research_town/configs/)
- Frontend Interface (frontend/)
- Backend API (backend/)

b) Supporting Components:
- Evaluator System (research_town/evaluators/)
- Utility Services (research_town/utils/)
- Data Management (research_town/data/)

##### Component Relationships and Architecture

Top Layer (User Interface):
- Frontend React Application
- Backend FastAPI Server

Middle Layer (Core Systems):
- Agent Manager System
- Environment Controller
- Engine Orchestrator
- Database Providers

Bottom Layer (Infrastructure):
- Configuration Management
- Data Storage
- Utility Services

##### Specific Design Elements

Use the following visual elements:
- Hexagons for agents
- Rounded rectangles for environments
- Blue: Core components
- Green: User interface
- Yellow: Data storage
- Purple: Supporting services

##### Key Interactions to Highlight

a) Agent Workflow:
**Frontend -> Backend API -> Engine -> Environment -> Agents**

b) Data Flow:
**Agents <-> Database <-> Environment**

c) Configuration Flow:
**Config System -> All Components**

##### Important Details

- Different types of environments (proposal writing, review writing, etc.)
- Database provider architecture with both local and external options
- Evaluation system's integration
- How the engine manages state transitions between environments

##### Technical Stack Indicators

Technology labels:
- Frontend: React
- Backend: FastAPI
- Database: Multiple providers support
- API: REST endpoints
- LLM Integration: OpenAI API

##### Specific Implementation Notes

- Numbered sequence indicators for key workflows
- Configuration injection points
- Extension points for future modules

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and Classes
    classDef frontend fill:#90EE90,stroke:#333,stroke-width:2px
    classDef backend fill:#87CEEB,stroke:#333,stroke-width:2px
    classDef core fill:#4169E1,stroke:#333,stroke-width:2px
    classDef database fill:#FFD700,stroke:#333,stroke-width:2px
    classDef utils fill:#DDA0DD,stroke:#333,stroke-width:2px
    classDef config fill:#F08080,stroke:#333,stroke-width:2px
    classDef evaluator fill:#98FB98,stroke:#333,stroke-width:2px

    %% User Interface Layer
    subgraph UI
        FE["Frontend React App"]:::frontend
        BE["Backend FastAPI"]:::backend
    end

    %% Core Systems Layer
    subgraph CoreSystems
        AG["Agent System"]:::core
        ENV["Environment System"]:::core
        ENG["Engine System"]:::core
    end

    %% Database Layer
    subgraph Databases
        DB_PAPER["Paper Database"]:::database
        DB_PROFILE["Profile Database"]:::database
        DB_PROGRESS["Progress Database"]:::database
    end

    %% Environment Types
    subgraph Environments
        ENV_PROP["Proposal Writing Env"]:::core
        ENV_REV["Review Writing Env"]:::core
    end

    %% Supporting Systems
    subgraph Support
        EVAL["Evaluator System"]:::evaluator
        UTILS["Utility Services"]:::utils
        CONFIG["Configuration System"]:::config
    end

    %% Data Management
    DM["Data Management"]:::utils

    %% Relationships
    FE --> BE
    BE --> ENG
    ENG --> ENV
    ENV --> AG
    AG --> DB_PAPER
    AG --> DB_PROFILE
    AG --> DB_PROGRESS
    ENV --> ENV_PROP
    ENV --> ENV_REV
    CONFIG --> AG
    CONFIG --> ENV
    CONFIG --> ENG
    EVAL --> AG
    EVAL --> ENV
    UTILS --> AG
    UTILS --> ENV
    DM --> DB_PAPER
    DM --> DB_PROFILE
    DM --> DB_PROGRESS

    %% Click Events
    click AG "https://github.com/ulab-uiuc/research-town/tree/main/research_town/agents/"
    click ENV "https://github.com/ulab-uiuc/research-town/tree/main/research_town/envs/"
    click ENG "https://github.com/ulab-uiuc/research-town/tree/main/research_town/engines/"
    click DB_PAPER "https://github.com/ulab-uiuc/research-town/blob/main/research_town/dbs/db_paper.py"
    click DB_PROFILE "https://github.com/ulab-uiuc/research-town/blob/main/research_town/dbs/db_profile.py"
    click DB_PROGRESS "https://github.com/ulab-uiuc/research-town/blob/main/research_town/dbs/db_progress.py"
    click CONFIG "https://github.com/ulab-uiuc/research-town/tree/main/research_town/configs/"
    click FE "https://github.com/ulab-uiuc/research-town/tree/main/frontend/"
    click BE "https://github.com/ulab-uiuc/research-town/tree/main/backend/app/"
    click EVAL "https://github.com/ulab-uiuc/research-town/tree/main/research_town/evaluators/"
    click UTILS "https://github.com/ulab-uiuc/research-town/tree/main/research_town/utils/"
    click DM "https://github.com/ulab-uiuc/research-town/tree/main/research_town/data/"
    click ENV_PROP "https://github.com/ulab-uiuc/research-town/blob/main/research_town/envs/env_proposal_writing_with_rag.py"
    click ENV_REV "https://github.com/ulab-uiuc/research-town/blob/main/research_town/envs/env_review_writing.py"
```
