# plandex-ai/plandex architecture

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

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

## Overview

##### Project Type and Purpose
- This is a full-stack, terminal-based AI agent split into two main processes:
a. A **CLI client** (`app/cli`) used by developers to interact via REPL or commands.
b. A **Server** (`app/server`) providing HTTP/gRPC APIs, state management, database persistence, syntax parsing, and integration with AI model providers.

##### Main Components
- CLI Client
- REPL / command parser / UI (TUI)
- Local cache and file-map modules
- Server API
- HTTP/gRPC endpoint layer (handlers, routes)
- Domain logic (plans, contexts, streams)
- Syntax & file-map service (tree-sitter)
- AI orchestration (litellm_proxy, batching, streaming)
- Email & notification service
- Shutdown / health check endpoints
- Data Store
- Relational DB (Postgres via `app/server/db`)
- Migrations
- External Services
- AI Model Providers (OpenAI, Anthropic, Google, OpenRouter, etc.)
- Email SMTP or API
- Git (for file diffs, branch management)

##### Relationships and Data Flows
- CLI → Server: REST or gRPC calls for all actions (`apply`, `plan`, `stream`, `auth`, etc.)
- Server → DB: CRUD operations, transactions, queue & locks
- Server → AI Providers: HTTP/HTTPS requests for context loading, prompts, streaming responses
- Server → Syntax Module: Local function calls for project map generation & structured edits
- Server → Email: Outbound notifications (invites, verification)
- Server → Git: File diffs, commit generation, branch operations
- Server → CLI: Server streams back events, logs, diffs, summaries

##### Key Architectural Patterns
- **Separation of Concerns**: CLI and Server are distinct processes, communicate over an API.
- **Hexagonal Architecture**: Handlers → Domain → Adapters (DB, AI providers, syntax).
- **Event / Stream Processing**: Plans and build executions are streamed to the CLI.
- **Plugin-style Model Providers**: Shared interfaces for models; concrete implementations in `app/shared/ai_models_*`.
- **Cumulative Diff Sandbox**: All file edits are staged until approved, enabling rollbacks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Client
    subgraph "CLI Client" 
        direction TB
        CLI_Core["CLI Core\n(app/cli)"]:::frontend
        CLI_REPL["REPL / TUI\n(app/cli/cmd/repl.go)"]:::frontend
        CLI_CMD["Command Parser\n(app/cli/cmd)"]:::frontend
        CLI_TERM["Terminal UI\n(app/cli/term)"]:::frontend
        CLI_TUI["Stream TUI\n(app/cli/stream_tui)"]:::frontend
        CLI_FS["Local Cache & File-Map\n(app/cli/fs)"]:::frontend
        CLI_LIB["Lib\n(app/cli/lib)"]:::frontend
        CLI_GIT_CLI["Git Module\n(app/cli/lib/git.go)"]:::frontend
        CLI_Core --> CLI_CMD
        CLI_CMD --> CLI_REPL
        CLI_REPL --> CLI_TERM
        CLI_TERM --> CLI_TUI
        CLI_Core --> CLI_FS
        CLI_FS --> CLI_LIB
        CLI_LIB --> CLI_GIT_CLI
    end

    %% Server API
    subgraph "Server API" 
        direction TB
        Handlers["HTTP/gRPC Handlers\n(app/server/handlers)"]:::server
        Routes["Routes\n(app/server/routes/routes.go)"]:::server
        Domain["Domain Logic"]:::server
        Plan["Plan Model\n(app/server/model/plan)"]:::server
        Parse["Parse Model\n(app/server/model/parse)"]:::server
        Types["Types\n(app/server/types)"]:::server
        Streams["Stream Helpers\n(app/server/db/stream_helpers.go)"]:::server
        SyntaxSvc["Syntax Service\n(app/server/syntax)"]:::server
        FileMap["File-Map\n(app/server/syntax/file_map)"]:::server
        StructEdit["Structured Edits\n(app/server/syntax/structured_edits_tree_sitter.go)"]:::server
        AI_Proxy["LiteLLM Proxy\n(app/server/litellm_proxy.py)"]:::server
        LitellmMod["LiteLLM Model\n(app/server/model/litellm.go)"]:::server
        SharedAI["Shared AI Models\n(app/shared/ai_models_available.go)"]:::server
        StreamShared["Stream Utilities\n(app/shared/stream.go)"]:::server
        EmailSvc["Email Service\n(app/server/email)"]:::server
        Notify["Notification\n(app/server/notify)"]:::server
        SharedEmail["Shared Email\n(app/shared/email.go)"]:::server
        Shutdown["Shutdown & Health\n(app/server/shutdown/shutdown.go)"]:::server

        Handlers --> Routes
        Routes --> Domain
        Domain --> Plan
        Domain --> Parse
        Domain --> Types
        Domain --> Streams
        Routes --> SyntaxSvc
        SyntaxSvc --> FileMap
        SyntaxSvc --> StructEdit
        Domain --> AI_Proxy
        AI_Proxy --> LitellmMod
        LitellmMod --> SharedAI
        LitellmMod --> StreamShared
        Domain --> EmailSvc
        Domain --> Notify
        EmailSvc --> SharedEmail
        Routes --> Shutdown
    end

    %% Data Store
    subgraph "Data Store" 
        direction TB
        DB["Postgres DB\n(app/server/db)"]:::db
        Models["DB Models\n(app/server/db/models.go)"]:::db
        Migrations["Migrations\n(app/server/migrations)"]:::db
        DB --> Models
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AI_Prov["AI Model Providers\n(app/shared/ai_models_providers.go)"]:::external
        SMTP["Email SMTP/API\n(app/server/email/email.go)"]:::external
        Git_Ext["Git Integration\n(app/server/db/git.go)"]:::external
    end

    %% Connections
    CLI_Core -->|HTTP/gRPC Calls| Handlers
    Handlers -->|SQL CRUD| DB
    DB -->|SQL SELECT/INSERT| Models
    Handlers -->|Stream Tokens| CLI_TUI
    AI_Proxy -->|HTTP Requests| AI_Prov
    EmailSvc -->|SMTP/API Calls| SMTP
    CLI_FS -->|Git Diffs| Git_Ext
    Domain -->|Git Commits| Git_Ext

    %% Click Events
    click CLI_Core "https://github.com/plandex-ai/plandex/tree/main/app/cli"
    click CLI_REPL "https://github.com/plandex-ai/plandex/blob/main/app/cli/cmd/repl.go"
    click CLI_CMD "https://github.com/plandex-ai/plandex/tree/main/app/cli/cmd"
    click CLI_TERM "https://github.com/plandex-ai/plandex/tree/main/app/cli/term"
    click CLI_TUI "https://github.com/plandex-ai/plandex/tree/main/app/cli/stream_tui"
    click CLI_FS "https://github.com/plandex-ai/plandex/tree/main/app/cli/fs"
    click CLI_LIB "https://github.com/plandex-ai/plandex/tree/main/app/cli/lib"
    click CLI_GIT_CLI "https://github.com/plandex-ai/plandex/blob/main/app/cli/lib/git.go"
    click Handlers "https://github.com/plandex-ai/plandex/tree/main/app/server/handlers"
    click Routes "https://github.com/plandex-ai/plandex/blob/main/app/server/routes/routes.go"
    click Plan "https://github.com/plandex-ai/plandex/tree/main/app/server/model/plan"
    click Parse "https://github.com/plandex-ai/plandex/tree/main/app/server/model/parse"
    click Types "https://github.com/plandex-ai/plandex/tree/main/app/server/types"
    click Streams "https://github.com/plandex-ai/plandex/blob/main/app/server/db/stream_helpers.go"
    click SyntaxSvc "https://github.com/plandex-ai/plandex/tree/main/app/server/syntax"
    click FileMap "https://github.com/plandex-ai/plandex/tree/main/app/server/syntax/file_map"
    click StructEdit "https://github.com/plandex-ai/plandex/blob/main/app/server/syntax/structured_edits_tree_sitter.go"
    click AI_Proxy "https://github.com/plandex-ai/plandex/blob/main/app/server/litellm_proxy.py"
    click LitellmMod "https://github.com/plandex-ai/plandex/blob/main/app/server/model/litellm.go"
    click SharedAI "https://github.com/plandex-ai/plandex/blob/main/app/shared/ai_models_available.go"
    click StreamShared "https://github.com/plandex-ai/plandex/blob/main/app/shared/stream.go"
    click EmailSvc "https://github.com/plandex-ai/plandex/tree/main/app/server/email"
    click Notify "https://github.com/plandex-ai/plandex/tree/main/app/server/notify"
    click SharedEmail "https://github.com/plandex-ai/plandex/blob/main/app/shared/email.go"
    click Shutdown "https://github.com/plandex-ai/plandex/blob/main/app/server/shutdown/shutdown.go"
    click DB "https://github.com/plandex-ai/plandex/tree/main/app/server/db"
    click Models "https://github.com/plandex-ai/plandex/blob/main/app/server/db/models.go"
    click Migrations "https://github.com/plandex-ai/plandex/tree/main/app/server/migrations"
    click AI_Prov "https://github.com/plandex-ai/plandex/blob/main/app/shared/ai_models_providers.go"
    click SMTP "https://github.com/plandex-ai/plandex/blob/main/app/server/email/email.go"
    click Git_Ext "https://github.com/plandex-ai/plandex/blob/main/app/server/db/git.go"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef server fill:#d4edda,stroke:#333,stroke-width:1px
    classDef db fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef external fill:#e5ccff,stroke:#333,stroke-width:1px
```
