# scodive/researchgpt architecture

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

- Interactive diagram: https://gitdiagram.com/scodive/researchgpt
- Repository: https://github.com/scodive/researchgpt

## Overview

##### Project Type and Purpose
- ResearchGPT is an intelligent research assistant designed to help researchers explore literature, generate innovative research directions, design experiments, and even generate academic papers with LaTeX output.
- The README clarifies that the system supports research exploration, detailed research plan generation, and multi-lingual paper generation using technologies like the Google Gemini API (with plans for local model deployment).

##### File Structure
- The project is split into multiple layers/components:
- A "frontend" directory: Implements the user interface using Next.js 13 (app router), React, and Tailwind CSS.
- A "backend" directory: Contains Python code (with folders for models and services) that likely handle business logic, research plan generation, and interactions with language models.
- An "app" directory: Likely integrates API endpoints (in TypeScript), such as “compile-latex” and “generate-paper-gemini”, which provide hooks between the front-end and back-end.
- A mix of API endpoints in a “pages/api” directory in Next.js: These provide additional API routing for chat, paper generation, search, etc.
- There are configuration files, like vercel.json for deployment, and package files for front-end dependencies, along with environment variable samples.

##### Key Components
a. Frontend:
- Next.js 13 application with attribute pages for home, about, plan, paper, search, privacy, etc.
- Uses routing (app router and traditional pages API endpoints) to handle user interactions.
- Responsible for responsive UI and local data storage.
b. Backend:
- A Python-based backend (directory “backend”) containing modules for research models and services (e.g., llm_service.py, paper_service.py).
- Contains “main.py” and an environment configuration for deploying the service.
- Handles communication with external APIs (such as Google Gemini API) and possibly local models (as indicated in the README).
c. API Integration Layer:
- The “app/api” folder (with its route.ts files) and “pages/api” endpoints integrate the frontend with backend and third-party services.
- These layers manage the transformation of user requests to the corresponding processor (e.g., paper generation or LaTeX compiling).
d. Data Storage:
- Primarily localStorage as of the current version, with planned support for database storage.
e. External Services and Dependencies:
- Google Gemini API for intelligent generation and possibly local models in the future.
- Communication protocols between frontend and backend components.

##### Relationships and Interactions
- User interactions on the frontend are translated into API calls (via Next.js API endpoints, both in “app/api” and “pages/api”) which trigger backend processing.
- The backend processes these requests (using its services and models) to generate research plans or LaTeX code for papers.
- The system design should capture the data flow: from user input to API gateway, then to backend service invocation, and finally back to the user UI for display or file download.
- The integration with external APIs (like Google Gemini) should be noted as an interaction channel.

##### Architectural Patterns and Key Principles
- Separation of concerns between UI (frontend) and business logic/data processing (backend).
- The use of API gateways (Next.js API routes) to securely decouple the frontend and backend.
- Emphasis on scalable, modular design: independent modules for research exploration, paper generation, and LaTeX compiling.
- The system leverages modern full-stack patterns typical in Next.js applications (server components, API routes) along with traditional RESTful service design for the Python backend.

##### Instructing the Principal Software Engineer
- That capturing as many components as possible — from detailed API endpoints to service modules — is crucial for understanding the entire architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    U("Researcher"):::user

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE("Frontend UI (Next.js Application)"):::frontend
        FE_H("Home Page (page.tsx)"):::frontend
        FE_A("About Page (about/page.tsx)"):::frontend
        FE_P("Plan Page ([id]/page.tsx)"):::frontend
        FE_PP("Paper Page (paper/page.tsx)"):::frontend
        FE_Pr("Privacy Page (privacy/page.tsx)"):::frontend
        FE_S("Search Page (search/page.tsx)"):::frontend
        DS("localStorage"):::storage
    end

    %% API Gateway Layer
    subgraph "API Gateway Layer"
        APIGA("Compile LaTeX Endpoint"):::api
        APIGA2("Generate Paper Gemini Endpoint"):::api
        APIP1("Chat Endpoint"):::api
        APIP2("Generate Paper Gemini (Pages API)"):::api
        APIP3("Generate Paper Local Endpoint"):::api
        APIP4("Generate Paper Endpoint"):::api
        APIP5("Search Endpoint"):::api
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BE_MAIN("Main Backend"):::backend
        BE_RM("Research Models"):::backend
        BE_LLM("LLM Service"):::backend
        BE_PS("Paper Service"):::backend
    end

    %% External Services
    subgraph "External Services"
        EX("Google Gemini API"):::external
    end

    %% Data Flow Connections
    U -->|"initiates"| FE
    FE -->|"reads/writes"| DS

    %% Frontend to API Gateway
    FE -->|"calls"| APIGA
    FE -->|"calls"| APIP1

    %% Additional API endpoints from Frontend (if applicable)
    FE -->|"calls"| APIP2
    FE -->|"calls"| APIP3
    FE -->|"calls"| APIP4
    FE -->|"calls"| APIP5
    FE -->|"calls"| APIGA2

    %% API Gateway to Backend
    APIGA -->|"triggers"| BE_MAIN
    APIGA2 -->|"triggers"| BE_MAIN
    APIP1 -->|"triggers"| BE_MAIN
    APIP2 -->|"triggers"| BE_MAIN
    APIP3 -->|"triggers"| BE_MAIN
    APIP4 -->|"triggers"| BE_MAIN
    APIP5 -->|"triggers"| BE_MAIN

    %% Backend internal calls
    BE_MAIN -->|"utilizes"| BE_RM
    BE_MAIN -->|"utilizes"| BE_LLM
    BE_MAIN -->|"utilizes"| BE_PS

    %% Backend to External Services
    BE_LLM -->|"calls"| EX
    BE_PS -->|"calls"| EX

    %% Return flow from Backend to Frontend via API
    BE_MAIN -->|"responds"| APIGA
    BE_MAIN -->|"responds"| APIP1
    BE_MAIN -->|"responds"| APIP2
    BE_MAIN -->|"responds"| APIP3
    BE_MAIN -->|"responds"| APIP4
    BE_MAIN -->|"responds"| APIP5
    BE_MAIN -->|"responds"| APIGA2
    APIGA -->|"sends data"| FE

    %% Click Events for Frontend UI
    click FE "https://github.com/scodive/researchgpt/tree/main/frontend/app"
    click FE_H "https://github.com/scodive/researchgpt/blob/main/frontend/app/page.tsx"
    click FE_A "https://github.com/scodive/researchgpt/blob/main/frontend/app/about/page.tsx"
    click FE_P "https://github.com/scodive/researchgpt/blob/main/frontend/app/plan/[id]/page.tsx"
    click FE_PP "https://github.com/scodive/researchgpt/blob/main/frontend/app/paper/page.tsx"
    click FE_Pr "https://github.com/scodive/researchgpt/blob/main/frontend/app/privacy/page.tsx"
    click FE_S "https://github.com/scodive/researchgpt/blob/main/frontend/app/search/page.tsx"

    %% Click Events for API Gateway Endpoints
    click APIGA "https://github.com/scodive/researchgpt/blob/main/app/api/compile-latex/route.ts"
    click APIGA2 "https://github.com/scodive/researchgpt/blob/main/app/api/generate-paper-gemini/route.ts"

    %% Click Events for Additional API Endpoints
    click APIP1 "https://github.com/scodive/researchgpt/blob/main/pages/api/chat.ts"
    click APIP2 "https://github.com/scodive/researchgpt/blob/main/pages/api/generate-paper-gemini.ts"
    click APIP3 "https://github.com/scodive/researchgpt/blob/main/pages/api/generate-paper-local.ts"
    click APIP4 "https://github.com/scodive/researchgpt/blob/main/pages/api/generate-paper.ts"
    click APIP5 "https://github.com/scodive/researchgpt/blob/main/pages/api/search.ts"

    %% Click Events for Backend Services and Models
    click BE_RM "https://github.com/scodive/researchgpt/blob/main/backend/app/models/research_models.py"
    click BE_LLM "https://github.com/scodive/researchgpt/blob/main/backend/app/services/llm_service.py"
    click BE_PS "https://github.com/scodive/researchgpt/blob/main/backend/app/services/paper_service.py"
    click BE_MAIN "https://github.com/scodive/researchgpt/blob/main/backend/main.py"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef api fill:#ffdead,stroke:#000,stroke-width:2px;
    classDef backend fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef external fill:#dda0dd,stroke:#000,stroke-width:2px;
    classDef user fill:#ffc0cb,stroke:#000,stroke-width:2px;
    classDef storage fill:#f0e68c,stroke:#000,stroke-width:2px;
```
