How renuka010/potpie works
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