Relevant source files

The following files were used as context for generating this wiki page: - [README.md](https://github.com/Zeeeepa/codegen-ai/blob/main/README.md) - [PLAN.md](https://github.com/Zeeeepa/codegen-ai/blob/main/PLAN.md) - [App.tsx](https://github.com/Zeeeepa/codegen-ai/blob/main/App.tsx) - [components/ProjectCard.tsx](https://github.com/Zeeeepa/codegen-ai/blob/main/components/ProjectCard.tsx) - [services/codegen_library.ts](https://github.com/Zeeeepa/codegen-ai/blob/main/services/codegen_library.ts) - [services/api.ts](https://github.com/Zeeeepa/codegen-ai/blob/main/services/api.ts) - [types.ts](https://github.com/Zeeeepa/codegen-ai/blob/main/types.ts) - [components/modals/SettingsModal.tsx](https://github.com/Zeeeepa/codegen-ai/blob/main/components/modals/SettingsModal.tsx) - [components/modals/MarkdownViewerModal.tsx](https://github.com/Zeeeepa/codegen-ai/blob/main/components/modals/MarkdownViewerModal.tsx) - [index.html](https://github.com/Zeeeepa/codegen-ai/blob/main/index.html) - [package.json](https://github.com/Zeeeepa/codegen-ai/blob/main/package.json)

# Frontend Architecture The CodeGen AI Project Orchestrator is a web-based command center for managing and automating the lifecycle of GitHub projects. The frontend is a single-page application built with React and TypeScript, designed to provide a persistent dashboard for interacting with AI agents, configuring project-specific rules, and orchestrating a conceptual CI/CD workflow for pull request validation. It serves as the user interface for a suite of backend services, which are mocked or simulated within the frontend's service layer for a self-contained experience. The architecture emphasizes a clear separation of concerns between UI components, state management, and service interactions. It uses a component-based structure, with a main `App` component managing the overall state and rendering `ProjectCard` components for each repository. State persistence is handled via `localStorage`, ensuring the user's dashboard configuration is saved across sessions. *Sources: [README.md:3-12](), [PLAN.md:5-7](), [App.tsx:13-15]()* ## Technology Stack The frontend is built using modern web technologies, focusing on a clean, single-page application design without a router. | Technology | Description | Source File(s) - | |-----------------|--------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **React 18+** | Used for building the user interface with TypeScript. | *[README.md:31](), [package.json:13]()* - | | **Tailwind CSS**| Provides utility-first classes for styling the application. | *[README.md:32](), [index.html:6]()* - | | **Vite** | Serves as the build tool and development server. | *[package.json:8]()* - | *Sources: [README.md:30-33](), [package.json](), [index.html]()* ## Application Structure ### Entry Point The application's entry point is `index.html`, which sets up the basic HTML document structure, includes Tailwind CSS, and defines a root div (`

`). It then loads the main application logic via ``. The `index.tsx` file (which is not provided in the context but its role is implied) would typically use `ReactDOM.createRoot` to render the main `App` component into the root div. *Sources: [index.html:5-30]()* ### Component Hierarchy The application is structured around a main `App` component that orchestrates the entire UI. It manages the list of projects and global settings, passing data down to child components as props. This diagram illustrates the primary component hierarchy. ```mermaid graph TD App[App.tsx] --> Header[Header.tsx] App --> ProjectGrid{Project Grid} ProjectGrid --> ProjectCard[components/ProjectCard.tsx] App --> GlobalSettingsModal[modals/GlobalSettingsModal.tsx] ProjectCard --> SettingsModal[modals/SettingsModal.tsx] ProjectCard --> AgentRunModal[modals/AgentRunModal.tsx] ProjectCard --> PullRequestModal[modals/PullRequestModal.tsx] ProjectCard --> MarkdownViewerModal[modals/MarkdownViewerModal.tsx] ``` *Sources: [App.tsx:205-221](), [components/ProjectCard.tsx:343-384]()* ### Core Components - **`App.tsx`**: The root component. It fetches and manages the list of projects and global settings using the `useLocalStorage` hook. It is responsible for adding/removing projects and polling for pull request updates. - **`ProjectCard.tsx`**: The most complex component, representing a single GitHub project on the dashboard. It manages its own state for modals, displays agent run status and logs, and handles user interactions like running an agent, confirming a plan, or viewing settings. - **Modal Components**: A suite of modals are used for various functions: - `SettingsModal.tsx`: Configures project-specific settings like repository rules, setup commands, and secrets. - `GlobalSettingsModal.tsx`: Configures global API keys and tokens. - `MarkdownViewerModal.tsx`: A reusable modal to view, edit, and create `README.md` and `PLAN.md` files for a project. - `EnhancedSettingsModal.tsx`: Provides a detailed view of system health, including Cloudflare worker status and GitHub webhook configurations for selected repositories. *Sources: [App.tsx](), [components/ProjectCard.tsx](), [components/modals/SettingsModal.tsx](), [components/modals/MarkdownViewerModal.tsx](), [components/modals/EnhancedSettingsModal.tsx]()* ## State Management State is managed primarily through React's built-in hooks (`useState`, `useEffect`) and a custom `useLocalStorage` hook for persistence. ### Local State Components like `ProjectCard.tsx` manage their own UI state, such as the visibility of modals (`isSettingsOpen`, `isAgentRunOpen`). *Sources: [components/ProjectCard.tsx:43-51]()* ### Global and Persistent State The main `App` component manages the two most critical pieces of state, which are persisted to the browser's `localStorage`: 1. **`projects`**: An array of `Project` objects. This ensures the user's dashboard is preserved between sessions. 2. **`globalSettings`**: A `GlobalSettings` object containing API tokens and other global configurations. This state is passed down to child components (e.g., `ProjectCard`) via props. Updates are handled by callback functions (`onUpdate`, `onRemove`) passed down from `App.tsx`. The diagram below shows the flow of persistent state. ```mermaid graph TD subgraph Browser LocalStorage["localStorage('dashboard-projects', 'global-settings')"] end subgraph React Application useLocalStorage[hooks/useLocalStorage.ts] App[App.tsx State] ProjectCard[ProjectCard.tsx Props] end LocalStorage <--> useLocalStorage useLocalStorage <--> App App -- projects, globalSettings --> ProjectCard ``` *Sources: [App.tsx:13-14](), [PLAN.md:29-31]()* ## Data Models The application's data structures are defined in `types.ts`. These interfaces ensure type safety and a clear data contract throughout the application. ### Key Interfaces | Interface | Description | Fields - | |-------------------|---------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Project` | Extends `GithubRepo` and represents a project on the dashboard. | `id`, `name`, `full_name`, `settings`, `agentRun`, `pullRequests`, `webhookStatus` - | | `GlobalSettings` | Stores all global API keys and configuration details. | `CODEGEN_ORG_ID`, `CODEGEN_API_TOKEN`, `GITHUB_TOKEN`, etc. - | | `ProjectSettings` | Contains all per-project configurations for the AI agent and automation. | `rules`, `planningStatement`, `setupCommands`, `branch`, `secrets`, `autoConfirmPlan`, etc. - | | `AgentRun` | Tracks the state and history of an AI agent's execution. | `runId`, `status` (enum), `history` (array), `currentPlan` - | | `AgentRunStatus` | An enum defining the possible states of an agent run. | `IDLE`, `RUNNING`, `PLAN_PROPOSED`, `RESPONSE_DEFAULT`, `PR_CREATED`, `VALIDATING_PR`, `ERROR` - | This ER diagram shows the relationships between the main data entities. ```mermaid erDiagram Project ||--|{ ProjectSettings : "has" Project ||--o{ AgentRun : "has" Project ||--|{ PullRequest : "has" GlobalSettings ||..|| App : "configures" Project { int id string full_name string webhookStatus } ProjectSettings { string rules string planningStatement string setupCommands string branch object secrets bool autoConfirmPlan bool autoMergePR bool autoValidatePRs } AgentRun { int runId AgentRunStatus status array history } PullRequest { int id int number string title string validationStatus } ``` *Sources: [types.ts]()* ## Service Layer and API Interaction All external communication is handled through a service layer, abstracting the implementation details from the UI components. The primary services are `services/codegen_library.ts` and `services/api.ts`. ### Codegen Service (`codegen_library.ts`) This file contains a comprehensive `CodegenClient` class designed to interact with the Codegen API. It includes features like: - Request/response logging - Automatic retries with exponential backoff - Rate limiting - Caching for GET requests - A CORS proxy fallback mechanism The library exposes simplified functions like `startAgentRun`, `continueAgentRun`, `confirmAgentPlan`, and `pollAgentRunStatus` for use in the UI. These functions instantiate and use the `CodegenClient` to perform the actual API calls. *Sources: [services/codegen_library.ts:1-10847]()* ### Agent Run Flow The following sequence diagram illustrates the process of starting an AI agent run from the `ProjectCard`. ```mermaid sequenceDiagram participant User participant ProjectCard as "ProjectCard.tsx" participant CodegenLib as "codegen_library.ts" participant CodegenClient as "CodegenClient" participant CodegenAPI as "Codegen API" User->>ProjectCard: Clicks "Run Agent" and confirms target ProjectCard->>CodegenLib: handleStartRun(target) CodegenLib->>CodegenClient: startAgentRun(project, target, settings) Note over CodegenLib,CodegenClient: Constructs full prompt with rules CodegenClient->>CodegenAPI: POST /agent/run (prompt) CodegenAPI-->>CodegenClient: { runId: 123, status: 'pending' } CodegenClient->>CodegenClient: waitForCompletion(runId) loop Polling CodegenClient->>CodegenAPI: GET /agent/run/123 CodegenAPI-->>CodegenClient: { status: 'running' } CodegenClient->>CodegenAPI: GET /agent/run/123 CodegenAPI-->>CodegenClient: { status: 'completed', result: '...' } end CodegenClient-->>CodegenLib: Final AgentRun object CodegenLib-->>ProjectCard: AgentRun result ProjectCard->>ProjectCard: updateAgentRun(result) ``` *Sources: [components/ProjectCard.tsx:150-154](), [services/codegen_library.ts:1018-1043](), [services/api.ts:311-333]()* ## Agent Lifecycle and Status Management The `AgentRunStatus` enum is central to managing the UI's state and interactivity. The `ProjectCard` component dynamically changes its appearance and available actions based on the current status of the `agentRun`. *Sources: [types.ts:70-78](), [components/ProjectCard.tsx:21-34]()* ### State Machine The agent's lifecycle can be visualized as a state machine. The `ProjectCard` component polls for status updates when the agent is in a `RUNNING` state and updates the UI accordingly. ```mermaid stateDiagram-v2 [*] --> IDLE IDLE --> RUNNING: User starts run RUNNING --> PLAN_PROPOSED: Agent proposes plan RUNNING --> RESPONSE_DEFAULT: Agent asks for input RUNNING --> PR_CREATED: Agent creates PR RUNNING --> ERROR: Run fails RUNNING --> IDLE: Run completes successfully PLAN_PROPOSED --> RUNNING: User confirms/modifies plan RESPONSE_DEFAULT --> RUNNING: User continues conversation IDLE --> VALIDATING_PR: User or auto-trigger starts validation VALIDATING_PR --> IDLE: Validation completes VALIDATING_PR --> ERROR: Validation fails ``` *Sources: [components/ProjectCard.tsx:22-34](), [components/ProjectCard.tsx:93-126](), [types.ts:70-78]()* ### Polling Mechanism When an agent run is in the `RUNNING` state, a `useEffect` hook in `ProjectCard.tsx` initiates a polling mechanism. It calls `pollAgentRunStatus` every 5 seconds to fetch the latest status from the backend, updating the project's state only when the status changes. This ensures the UI reflects the agent's progress without constant re-rendering. *Sources: [components/ProjectCard.tsx:93-126](), [services/codegen_library.ts:989-1016]()* ## Mocked CI/CD and Validation Flow The application simulates a full CI/CD pipeline for pull request validation. This flow is conceptual and its steps are orchestrated on the frontend, using mocked services to represent backend systems. ### Validation Pipeline The validation process is initiated either manually by the user or automatically if `autoValidatePRs` is enabled for a project. The `runValidationPipeline` function in `grainchain_library.ts` simulates the entire flow. This flowchart shows the steps in the simulated validation pipeline. ```mermaid flowchart TD A[PR Detected / Validation Triggered] --> B[Set Status to 'VALIDATING_PR'] B --> C[runValidationPipeline in grainchain_library.ts] subgraph C direction LR C1[Create Sandbox] --> C2[Clone PR Code] C2 --> C3[Run Setup Commands] C3 --> C4[Deploy to Staging URL] C4 --> C5[Analyze Code Quality with graph-sitter] C5 --> C6[Run E2E Tests with web-eval-agent] end C --> D{Tests Passed?} D -- Yes --> E[Update PR Status to 'Success'] D -- No --> F[Update PR Status to 'Failed'] E --> G[Set Agent Status to 'IDLE'] F --> G ``` *Sources: [README.md:92-101](), [services/grainchain_library.ts:8-41](), [App.tsx:142-184]()* ## Conclusion The frontend architecture of the CodeGen AI Project Orchestrator is a robust and well-structured single-page application. It effectively uses React's component model and hooks for a reactive UI, while abstracting complex business logic and API communication into a dedicated service layer. State persistence via `localStorage` provides a seamless user experience, and the clear data models in `types.ts` ensure type safety and maintainability. The application successfully simulates a complex backend environment, making it a powerful and self-contained tool for demonstrating AI-driven development workflows. *Sources: [README.md:3-12](), [PLAN.md:3-31]()*