# potpie-ai/potpie-ui architecture

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

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

## Overview

##### Project Type and Purpose
- This is the User Interface layer of “Potpie,” an AI‑driven platform for generating custom engineering agents over your codebase.
- Built with Next.js (the new App Router), React, TypeScript, Tailwind CSS, and pnpm.
- Its sole responsibility is to render pages, manage state, and communicate with Potpie’s backend and third‑party services (Firebase Auth, PostHog, Formbricks, GitHub).

##### Top‑Level File Structure Analysis
- app/
- Next.js App Router pages and layouts, split into two route segments:
– /(auth): sign‑in, sign‑up, GitHub linking, onboarding flows
– /(main): protected UI—chat, agents, workflows, repositories, account, key management, subscription, etc.
- runtime.ts files for route‑level server logic (e.g., streaming chat).
- components/: Reusable UI primitives (buttons, cards, dialogs) plus domain‑specific panels (AgentCreationChatPanel, NodeSelector, Subscription).
- contexts/ & lib/state/: React Context and Redux‑style store for global state (user, chat, repo/branch).
- services/: TypeScript classes encapsulating HTTP calls to backend APIs (AgentService, ChatService, ModelService, WorkflowService, BranchAndRepositoryService, minorService).
- configs/: Client‑side configuration (Firebase).
- providers/: Top‑level React providers (theme, auth, query‑client).
- public/: Static assets (images, fonts).
- .github/workflows, Dockerfile, next.config.mjs, tailwind.config.ts: CI/CD and deployment configuration targeting Vercel or Cloud Run.

##### Key Architecture and Data Flows
a. Frontend (Next.js App)
- Server Components for page‑level data fetching (SSR/SSG).
- Client Components for interactivity (chat composer, workflows graph).
b. State Management
- React Context & Zustand/Redux pattern for storing auth, chat threads, selected repos.
c. Service Layer
- HTTP/Fetch wrappers in services/ to communicate with:
– Potpie Backend API (REST or GraphQL)
– GitHub API (via backend or directly)
d. Third‑Party Integrations
- Firebase Authentication (client SDK for sign‑in/up)
- PostHog (analytics SDK)
- Formbricks (bug reporting)

##### Final Advice
- Essential data flows—chat messages, agent configuration, auth tokens, analytics events.
- Keep it up to date: reflect any new services added under services/ or new environment flags in .env.template.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Browser["User Browser"]:::client

    %% Frontend App
    subgraph "Frontend App" 
        style FrontendApp fill:#D0E8FF,stroke:#0366d6,stroke-width:2px
        FrontendApp[/"Next.js App"/]:::frontend

        subgraph "App Router"
            style AuthRoutes fill:#A6C8FF,stroke:#0366d6
            AuthRoutes["Auth Routes"]:::frontend
            subgraph "Auth Pages"
                LayoutAuth["layout.tsx"]:::frontend
                SignIn["sign-in/page.tsx"]:::frontend
                SignUp["sign-up/page.tsx"]:::frontend
                LinkGitHub["link-github/page.tsx"]:::frontend
                Onboarding["onboarding/page.tsx"]:::frontend
            end
            style MainRoutes fill:#A6C8FF,stroke:#0366d6
            MainRoutes["Main Routes"]:::frontend
            subgraph "Main Pages"
                MainLayout["layout.tsx"]:::frontend
                Dashboard["page.tsx"]:::frontend
                AgentsMain["agents/page.tsx"]:::frontend
                AllAgents["all-agents/page.tsx"]:::frontend
                ChatThread["chat/[chatId]/page.tsx"]:::frontend
                ChatRuntime["chat/[chatId]/runtime.ts"]:::frontend
                NewChat["newchat/page.tsx"]:::frontend
                Workflows["workflows/page.tsx"]:::frontend
                Repos["repositories/page.tsx"]:::frontend
                Account["account/page.tsx"]:::frontend
                KeyMgmt["key-management/page.tsx"]:::frontend
                Subscription["user-subscription/page.tsx"]:::frontend
                SharedAgent["shared-agent/page.tsx"]:::frontend
                GHSetup["github-setup-complete/page.tsx"]:::frontend
            end
        end

        subgraph "UI Components"
            Components["components/"]:::frontend
        end

        subgraph "State & Context"
            StateStore["lib/state/store.ts"]:::frontend
            AuthCtx["contexts/AuthContext.tsx"]:::frontend
        end

        subgraph "Service Layer"
            Services["services/AgentService.ts"]:::frontend
        end

        subgraph "Providers & Config"
            Providers["providers/LayoutProviders.tsx"]:::frontend
            FirebaseCfg["configs/Firebase-config.ts"]:::frontend
        end

        subgraph "Public Assets"
            Public["public/"]:::frontend
        end
    end

    %% Backend API
    PotpieAPI["Potpie Backend API"]:::backend

    %% External Services
    subgraph "External Services"
        Firebase["Firebase Auth"]:::external
        PostHog["PostHog Analytics"]:::external
        Formbricks["Formbricks"]:::external
        GitHubAPI["GitHub API"]:::external
        AIModel["AI Model Provider"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure"
        Hosting["Vercel / Cloud Run"]:::infra
        CDN["CDN"]:::infra
    end

    %% Connections
    Browser -->|"HTTP/SSR & Navigations"| FrontendApp
    FrontendApp -->|"REST via services"| PotpieAPI
    FrontendApp -->|"SDK call"| Firebase
    FrontendApp -->|"event tracking"| PostHog
    FrontendApp -->|"error reporting"| Formbricks
    PotpieAPI -->|"GitHub data"| GitHubAPI
    PotpieAPI -->|"Model calls"| AIModel
    Hosting --> FrontendApp
    CDN --> Public

    %% Click Events
    click AuthRoutes "https://github.com/potpie-ai/potpie-ui/tree/main/app/(auth)"
    click LayoutAuth "https://github.com/potpie-ai/potpie-ui/blob/main/app/(auth)/layout.tsx"
    click SignIn "https://github.com/potpie-ai/potpie-ui/blob/main/app/(auth)/sign-in/page.tsx"
    click SignUp "https://github.com/potpie-ai/potpie-ui/blob/main/app/(auth)/sign-up/page.tsx"
    click LinkGitHub "https://github.com/potpie-ai/potpie-ui/blob/main/app/(auth)/link-github/page.tsx"
    click Onboarding "https://github.com/potpie-ai/potpie-ui/blob/main/app/(auth)/onboarding/page.tsx"
    click MainRoutes "https://github.com/potpie-ai/potpie-ui/tree/main/app/(main)"
    click MainLayout "https://github.com/potpie-ai/potpie-ui/blob/main/app/(main)/layout.tsx"
    click Dashboard "https://github.com/potpie-ai/potpie-ui/blob/main/app/(main)/page.tsx"
    click AgentsMain "https://github.com/potpie-ai/potpie-ui/blob/main/app/(main)/agents/page.tsx"
    click AllAgents "https://github.com/potpie-ai/potpie-ui/blob/main/app/(main)/all-agents/page.tsx"
    click ChatThread "https://github.com/potpie-ai/potpie-ui/blob/main/app/(main)/chat/[chatId]/page.tsx"
    click ChatRuntime "https://github.com/potpie-ai/potpie-ui/blob/main/app/(main)/chat/[chatId]/runtime.ts"
    click NewChat "https://github.com/potpie-ai/potpie-ui/blob/main/app/(main)/newchat/page.tsx"
    click Workflows "https://github.com/potpie-ai/potpie-ui/blob/main/app/(main)/workflows/page.tsx"
    click Repos "https://github.com/potpie-ai/potpie-ui/blob/main/app/(main)/repositories/page.tsx"
    click Account "https://github.com/potpie-ai/potpie-ui/blob/main/app/(main)/account/page.tsx"
    click KeyMgmt "https://github.com/potpie-ai/potpie-ui/blob/main/app/(main)/key-management/page.tsx"
    click Subscription "https://github.com/potpie-ai/potpie-ui/blob/main/app/(main)/user-subscription/page.tsx"
    click SharedAgent "https://github.com/potpie-ai/potpie-ui/blob/main/app/(main)/shared-agent/page.tsx"
    click GHSetup "https://github.com/potpie-ai/potpie-ui/blob/main/app/(main)/github-setup-complete/page.tsx"
    click Components "https://github.com/potpie-ai/potpie-ui/tree/main/components/"
    click StateStore "https://github.com/potpie-ai/potpie-ui/blob/main/lib/state/store.ts"
    click AuthCtx "https://github.com/potpie-ai/potpie-ui/blob/main/contexts/AuthContext.tsx"
    click Services "https://github.com/potpie-ai/potpie-ui/blob/main/services/AgentService.ts"
    click Providers "https://github.com/potpie-ai/potpie-ui/blob/main/providers/LayoutProviders.tsx"
    click FirebaseCfg "https://github.com/potpie-ai/potpie-ui/blob/main/configs/Firebase-config.ts"
    click Public "https://github.com/potpie-ai/potpie-ui/tree/main/public/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#000
    classDef backend fill:#D0FFD6,stroke:#028A0F,color:#000
    classDef external fill:#FFE4B3,stroke:#D97706,color:#000
    classDef infra fill:#E0E0E0,stroke:#4B5563,color:#000
    classDef client fill:#FFFFFF,stroke:#2563EB,color:#000
    class FrontendApp,AuthRoutes,MainRoutes,Components,StateStore,AuthCtx,Services,Providers,FirebaseCfg,Public frontend
    class PotpieAPI backend
    class Firebase,PostHog,Formbricks,GitHubAPI,AIModel external
    class Hosting,CDN infra
```
