# supabase/cli architecture

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

- Interactive diagram: https://gitdiagram.com/supabase/cli
- Repository: https://github.com/supabase/cli

## Overview

##### Core CLI Interface Layer
- Root Command Handler (cmd/root.go)
- Command Groups (organized in cmd/ directory)
- User Interface Components (internal/utils/console.go, internal/utils/tea.go)

##### Service Management Layer
- Project Management (internal/projects/)
- Database Operations (internal/db/)
- Functions Management (internal/functions/)
- Authentication & SSO (internal/sso/)
- Storage Management (internal/storage/)

##### Infrastructure Layer
- Docker Integration (internal/utils/docker.go)
- Database Connections (pkg/pgxv5/)
- API Clients (pkg/api/)
- Configuration Management (pkg/config/)

##### Development Tools
- Migration Management (internal/migration/)
- Testing Framework (internal/testing/)
- Code Generation (internal/gen/)

##### Use a top-down layered architecture approach
- [User Input Layer]
- ↓
- [Command Processing Layer]
- ↓
- [Service Management Layer]
- ↓
- [Infrastructure Layer]

##### External Integration Points
- Supabase Platform API
- Docker Engine
- PostgreSQL Database
- Local File System
- Cloud Storage

Key Interactions to Highlight:

##### Command Flow
- User Input → Command Parser → Service Manager → Infrastructure Layer → External Services

##### Configuration Management
- Config Files ↔ Config Manager ↔ Service Modules

##### Database Operations
- Migration Commands → Database Manager → PostgreSQL Client → Database Instance

Special Considerations:

##### Cross-Platform Support
- Platform-specific components (indicated by _darwin.go, _linux.go, _windows.go files)
- Common interfaces for platform-agnostic operations

##### Plugin Architecture
- How different commands are organized as plugins
- Extension points for future functionality

##### Security Flow
- Authentication paths
- Token management
- Encryption handling

**Components:**
**□ Command Handler**
**○ Service Module**
**◇ Infrastructure Component**
**△ External Service**

**Connections:**
**→ Direct Dependency**
**⟶ Optional Dependency**
**↔ Bidirectional Flow**

**🔵 Core CLI**
**🟢 Service Management**
**🟠 Infrastructure**
**🟣 Development Tools**
**⚫ External Services**

Level of Detail:
- Keep high-level components visible at first glance
- Use expandable/collapsible sections for detailed subcomponents
- Version compatibility notes
- Annotations for critical paths and important workflows

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef core fill:#3498db,stroke:#2980b9,color:white
    classDef service fill:#2ecc71,stroke:#27ae60,color:white
    classDef infra fill:#e67e22,stroke:#d35400,color:white
    classDef devtools fill:#9b59b6,stroke:#8e44ad,color:white
    classDef external fill:#95a5a6,stroke:#7f8c8d,color:white

    %% Core CLI Interface Layer
    subgraph CLI
        Root["Root Command Handler"]:::core
        CmdGroups["Command Groups"]:::core
        UI["User Interface"]:::core
    end

    %% Service Management Layer
    subgraph Services
        PM["Project Management"]:::service
        DB["Database Operations"]:::service
        FM["Functions Management"]:::service
        SSO["Authentication & SSO"]:::service
        SM["Storage Management"]:::service
    end

    %% Infrastructure Layer
    subgraph Infrastructure
        Docker["Docker Integration"]:::infra
        DBConn["Database Connections"]:::infra
        APIClient["API Clients"]:::infra
        Config["Configuration Management"]:::infra
    end

    %% Development Tools Layer
    subgraph DevTools
        Migration["Migration Management"]:::devtools
        Testing["Testing Framework"]:::devtools
        CodeGen["Code Generation"]:::devtools
    end

    %% External Services
    subgraph External
        SupabaseAPI["Supabase Platform API"]:::external
        DockerEngine["Docker Engine"]:::external
        Postgres["PostgreSQL Database"]:::external
        Storage["Cloud Storage"]:::external
    end

    %% Relationships
    Root --> CmdGroups
    Root --> UI
    CmdGroups --> Services
    Services --> Infrastructure
    Infrastructure --> External
    DevTools --> Services
    DevTools --> Infrastructure

    %% Click Events
    click Root "https://github.com/supabase/cli/blob/develop/cmd/root.go"
    click CmdGroups "https://github.com/supabase/cli/tree/develop/cmd/"
    click UI "https://github.com/supabase/cli/blob/develop/internal/utils/console.go"
    click PM "https://github.com/supabase/cli/tree/develop/internal/projects/"
    click DB "https://github.com/supabase/cli/tree/develop/internal/db/"
    click FM "https://github.com/supabase/cli/tree/develop/internal/functions/"
    click SSO "https://github.com/supabase/cli/tree/develop/internal/sso/"
    click SM "https://github.com/supabase/cli/tree/develop/internal/storage/"
    click Docker "https://github.com/supabase/cli/blob/develop/internal/utils/docker.go"
    click DBConn "https://github.com/supabase/cli/tree/develop/pkg/pgxv5/"
    click APIClient "https://github.com/supabase/cli/tree/develop/pkg/api/"
    click Config "https://github.com/supabase/cli/tree/develop/pkg/config/"
    click Migration "https://github.com/supabase/cli/tree/develop/internal/migration/"
    click Testing "https://github.com/supabase/cli/tree/develop/internal/testing/"
    click CodeGen "https://github.com/supabase/cli/tree/develop/internal/gen/"

    %% Legend
    subgraph Legend
        L1["Core CLI"]:::core
        L2["Service Management"]:::service
        L3["Infrastructure"]:::infra
        L4["Development Tools"]:::devtools
        L5["External Services"]:::external
    end
```
