# trypear/pearai-master architecture

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

- Interactive diagram: https://gitdiagram.com/trypear/pearai-master
- Repository: https://github.com/trypear/pearai-master

## Overview

##### Main Components
- pearai-app: This is the main VSCode fork and acts as the core application. It houses the editor functionalities.
- pearai-submodule: Integrated as a submodule of pearai-app, this holds the AI chat features.
- pear-landing-page: A Next.js/React-based front-end website that serves as the landing page and directs users into the ecosystem.
- pearai-documentation: The documentation site offering detailed guides and API docs to users.
- pearai-server: A Python FastAPI server with a Supabase database which handles backend and authentication services for users who choose convenience over managing their own API keys.
- pearai-server-issues-public: A separate repository that publicly logs issues for the server, representing the monitoring or support layer.
- Additional directories (like PearAI-Roo-Code and pearai-mcp) should be checked for specialized internal functionalities or tooling, even if they are not explicitly mentioned in the README. They might represent support code or further integrations.

##### Relationships and Interactions
- Submodule Integration: Under the pearai-app, pearai-submodule provides AI chat functionalities. Indicate this as a nested relationship or an internal module within the core app.
- Authentication and Database: The landing page uses Supabase for authentication on a Next.js/React setup. Represent this by linking the landing-page component with both the Supabase service (possibly shown as an external service or a cloud resource) and supporting design elements like TailwindCSS with Shadcn.
- Logging/Telemetry: Axiom is used for logging and telemetry. Add this element as an optional service that connects with multiple components (such as the server or possibly even pearai-app) to monitor operations.

##### Architectural Patterns and Design Principles
- Modularity: Emphasize the modular organization of the project – each repository has a focused responsibility, which is ideal for scaling and individual contributions.
- Microservices / Separation of Concerns: The separation between frontend elements (pearai-app, pear-landing-page, pearai-documentation) and backend (pearai-server) reflects a common microservices or service-oriented pattern.
- Submodule Integration: Represent the use of submodules, showing that pearai-submodule is tightly coupled with pearai-app.
- Use of Standard Technologies: Indicate the tech stacks (TypeScript/Electron.js for the app, Next.js/React for the landing page, Python FastAPI for the backend) to provide further context on how components interact.

- Clear labels for each component (e.g., “pearai-app (VSCode-based core)”, “AI Chat - pearai-submodule”, “Landing Page – Next.js/React”, “Backend API – Python FastAPI”, “Documentation Site”, “Logging/Telemetry - Axiom”, “Auth & DB – Supabase”).
– Data flow between pearai-app (and its submodule) to pearai-server.
– User interactions with pear-landing-page, which in turn may interact with the documentation site and authentication systems.
– Communication lines (APIs) between client-side components and backend services.
– Frontend components (perhaps using rounded rectangles for all web-based UI items).
– External/integrated services like Supabase and Axiom.
– Supporting tools/scripts (like the setup_master_repo.sh and update_submodules.sh scripts can be annotated as orchestration/build/configuration tools).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        A["pearai-app (VSCode-based core)"]:::frontend
        B["AI Chat - pearai-submodule"]:::frontend
        C["Landing Page – Next.js/React"]:::frontend
        D["Documentation Site"]:::frontend
        A -->|"contains"| B
        C -->|"redirects"| D
    end

    %% Business Logic/API Layer
    subgraph "Business Logic/API Layer"
        E["Backend API – Python FastAPI"]:::backend
    end

    %% External Services
    subgraph "External Services"
        F["Auth & DB – Supabase"]:::external
        G["Logging/Telemetry – Axiom"]:::external
    end

    %% Support & Monitoring
    subgraph "Support & Monitoring"
        H["Server Issues Tracking"]:::support
        I["Internal Support Code/Tooling"]:::support
        J["Additional Internal Module/Tool"]:::support
    end

    %% Build/Orchestration
    subgraph "Build/Orchestration"
        K["Master Repo Setup Script"]:::build
        L["Update Submodules Script"]:::build
        M["GitHub Workflow: Update Submodules"]:::build
    end

    %% Relationships between layers
    A -->|"API_Call"| E
    C -->|"API_Interaction"| E
    C -->|"Auth"| F
    E -->|"Logs_to"| G
    E -->|"Monitors_Issues"| H
    I -->|"supports"| A
    J -->|"extends"| A

    %% Build orchestration relationships
    K -->|"orchestrates"| A
    L -->|"updates"| B
    M -->|"triggers"| L

    %% Styling classes
    classDef frontend fill:#a9d08e,stroke:#333,stroke-width:2px;
    classDef backend fill:#f4b084,stroke:#333,stroke-width:2px;
    classDef external fill:#c9daf8,stroke:#333,stroke-width:2px;
    classDef support fill:#ead1dc,stroke:#333,stroke-width:2px;
    classDef build fill:#ffe599,stroke:#333,stroke-width:2px;

    %% Click Events
    click A "https://github.com/trypear/pearai-master/tree/main/pearai-app"
    click B "https://github.com/trypear/pearai-master/tree/main/pearai-submodule"
    click C "https://github.com/trypear/pearai-master/tree/main/pear-landing-page"
    click D "https://github.com/trypear/pearai-master/tree/main/pearai-documentation"
    click E "https://github.com/trypear/pearai-master/tree/main/pearai-server"
    click H "https://github.com/trypear/pearai-master/tree/main/pearai-server-issues-public"
    click I "https://github.com/trypear/pearai-master/tree/main/PearAI-Roo-Code"
    click J "https://github.com/trypear/pearai-master/tree/main/pearai-mcp"
    click K "https://github.com/trypear/pearai-master/blob/main/setup_master_repo.sh"
    click L "https://github.com/trypear/pearai-master/blob/main/update_submodules.sh"
    click M "https://github.com/trypear/pearai-master/blob/main/.github/workflows/update-submodules.yml"
```
