How potpie-ai/potpie-ui works
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.