# renuka010/potpie architecture

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

- Interactive diagram: https://gitdiagram.com/renuka010/potpie
- Repository: https://github.com/renuka010/potpie

## Overview

##### Project Type and Purpose
- This is a full-stack, open-source AI platform (“Potpie”) that provides:
- A backend monolith (FastAPI + Celery) exposing REST APIs
- An asynchronous task system for parsing repositories and running AI agents
- A frontend UI (submodule “potpie-ui”) for human interaction
- Integration with external services (GitHub, Slack, VSCode, LLM providers)
- A persistent knowledge graph (Neo4j), relational metadata (PostgreSQL), and a message broker (Redis/Celery)

##### Top-Level Architectural Components
a. Frontend (potpie-ui)
- React/Vue app (built via pnpm) served separately (Docker container or static host)
- Communicates with the backend over HTTPS REST endpoints
b. Backend API Server (FastAPI in app/main.py)
- Exposes versioned routes under `/api/v1/…`
- Implements domain modules: auth, users, projects, parsing, intelligence, search, usage, etc.
- Uses a modular folder structure: each module holds controller/router, service, schema, models, tests
- Core utilities for config, logging, email, Firebase, PostHog
- Alembic migrations for PostgreSQL
c. Asynchronous Worker (Celery)
- Celery app configured in `app/celery/celery_app.py`
- Tasks (e.g., parsing, model inference, code graph generation) in `app/celery/tasks`
- Worker launched via `celery worker` and managed by supervisord in production
d. Datastores & Broker
- PostgreSQL: stores users, projects, conversation and agent metadata
- Neo4j: stores the knowledge graph of code elements
- Redis: acts both as Celery broker (and optional result backend)
e. External Services
- LLM providers (OpenAI, Anthropic, Ollama via Litellm) for inference & chat models
- GitHub (and other VCS) for repository cloning and webhook integrations
- Slack, VSCode extension, external CI/CD via Jenkins
- Secret management (Firebase, AWS Secret Manager)

##### Relationships & Data Flows
- User → Frontend UI → Backend API → (1) PostgreSQL for CRUD (2) Trigger Celery tasks
- Backend → Celery Broker (Redis) → Celery Worker → Database writes / Neo4j graph updates
- Celery tasks → LLM Provider APIs → Process responses → Store in Postgres/Neo4j
- Backend “parse” endpoints start graph construction workflows (parsing module → code_graph → knowledge_graph)
- Agents call “tools” via internal service layer → query Neo4j or filesystem or external APIs
- Jenkins pipelines / Docker Compose for deployment orchestration

##### Architectural Patterns & Principles
- Layered/hexagonal architecture: routers/controllers → services → core/database → repositories
- Modular plugin-style “tools” for AI agents under `app/modules/intelligence/tools`
- Event-driven/asynchronous processing via Celery for long-running tasks
- Infrastructure as code: Dockerfiles, docker-compose.yaml, Jenkinsfiles, supervisord configs
- Domain-driven module boundaries: auth, users, projects, parsing, intelligence, search, usage

##### Essential Elements to Capture
- Frontend ↔ Backend interactions (REST)
- Backend → Celery (task enqueue) → Worker → Databases
- Data ownership: which datastore holds what (metadata vs. knowledge graph)
- External integrations: where they attach to the flow
- Deployment artifacts: Docker containers, CI/CD pipelines

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend (UI)"
        UI["potpie-ui"]:::frontend
    end

    subgraph "Backend API Server"
        Main["FastAPI Server\n(app/main.py)"]:::backend
        Router["API Routers\n(app/api/router.py)"]:::backend
        subgraph "API Server Layers"
            Routers["Routers/Controllers"]:::backend
            Services["Service Layer"]:::backend
            DataLayer["Models & Repositories"]:::backend
            CoreUtil["Core Utilities"]:::backend
            Migrations["Alembic Migrations"]:::backend
        end
    end

    UI -->|HTTPS REST| Main
    Main --> Router
    Router --> Routers
    Routers --> Services
    Services --> DataLayer
    CoreUtil --> DataLayer
    Migrations --> DataLayer

    subgraph "Asynchronous Layer"
        Broker["Redis (Broker)"]:::datastore
        Worker["Celery Worker"]:::async
    end

    Main -->|enqueue tasks| Broker
    Broker --> Worker
    Worker -->|writes| DataLayer

    subgraph "Datastores"
        PostgreSQL[(PostgreSQL)]:::datastore
        Neo4j[(Neo4j)]:::datastore
        Redis[(Redis)]:::datastore
    end

    DataLayer --> PostgreSQL
    Worker --> Neo4j
    Broker -.-> Redis
    Worker -.-> Redis

    subgraph "External Services"
        LLM["LLM Providers"]:::external
        GitHub["GitHub"]:::external
        Slack["Slack"]:::external
        VSCode["VSCode Extension"]:::external
    end

    Worker -->|API calls| LLM
    Worker -->|clone/repos| GitHub
    Main -->|webhooks| GitHub
    Main -->|notifications| Slack
    Main -->|extension API| VSCode

    click UI "https://github.com/renuka010/potpie/tree/main/potpie-ui/"
    click Main "https://github.com/renuka010/potpie/blob/main/app/main.py"
    click Router "https://github.com/renuka010/potpie/blob/main/app/api/router.py"
    click CoreUtil "https://github.com/renuka010/potpie/blob/main/app/core/config_provider.py"
    click CoreUtil "https://github.com/renuka010/potpie/blob/main/app/core/database.py"
    click CoreUtil "https://github.com/renuka010/potpie/blob/main/app/core/models.py"
    click CoreUtil "https://github.com/renuka010/potpie/blob/main/app/core/base_model.py"
    click Migrations "https://github.com/renuka010/potpie/blob/main/alembic.ini"
    click Migrations "https://github.com/renuka010/potpie/tree/main/app/alembic/"

    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#333,stroke-width:1px
    classDef async fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef datastore fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef external fill:#e2d5f3,stroke:#333,stroke-width:1px
```
