# phasehq/console architecture

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

- Interactive diagram: https://gitdiagram.com/phasehq/console
- Repository: https://github.com/phasehq/console

## Overview

##### Main Components
a. Frontend (Next.js + Apollo)
b. API Gateway / Reverse Proxy (Nginx)
c. Backend (Django REST + Graphene GraphQL)
d. Relational Database (PostgreSQL)
e. Cache / Queue (Redis for RQ workers)
f. Background Workers (RQ)
g. Logging Service (DynamoDB via `backend/logs`)
h. External Integrations (GitHub, GitLab, AWS Secrets Manager, Cloudflare, Vercel, Nomad, Railway, Vault, Kubernetes)
i. CLI (Phase CLI communicating over REST/GraphQL)
j. Self-hosting Orchestration (Docker Compose, Kubernetes)

- Gray clouds for “External Services & Integrations”

##### External Integrations (Gray Clouds, placed around the periphery)
- OAuth Providers: GitHub, GitLab, Google (via `backend/api/authentication/adapters`)
- Sync Targets: AWS, Cloudflare, Vault, Vercel, Nomad, Railway (via `backend/api/utils/syncing/*`)
- Kubernetes (Phase Secrets Operator)
- Email (SMTP) for invites & notifications (`backend/api/emails.py`)

- Docker Compose services: nginx, frontend, backend, db, redis, worker
- Kubernetes (optional self-hosted)

That all internal components are packaged as Docker containers managed by Compose / Kubernetes.

##### Architectural Patterns & Design Principles
- API-First & GraphQL (schema in `frontend/apollo/schema.graphql` & `backend/backend/schema.py`)
- Modular Authentication Adapters for SSO / OAuth
- Background Processing via RQ to off-load long-running sync tasks
- Layered separation: Presentation (Next.js) → API (GraphQL/REST) → Business Logic (Django Services) → Data Layer (ORM, DB, Cache)
- Open-Core model: feature-flagged `ee/` modules loaded conditionally

##### Final Checklist
[ ] Frontend → Nginx → Backend
[ ] Backend → PostgreSQL & Redis
[ ] RQ Workers → External Integrations & DynamoDB Logs
[ ] CLI communication path to Nginx/Backend
[ ] Deployment context (Docker Compose / Kubernetes)
[ ] External OAuth & sync target clouds

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Entry
    User["User Browser / Phase CLI"]:::frontend
    User -->|"HTTPS / REST/GraphQL"| Nginx

    %% API Gateway
    subgraph "API Gateway / Reverse Proxy"
        Nginx["Nginx (Ingress)"]:::proxy
    end

    %% Frontend & UI
    subgraph "Frontend & User Interfaces"
        Frontend["Next.js Frontend (SSR/CSR)"]:::frontend
        Apollo["Apollo Client"]:::frontend
        CLI["Phase CLI"]:::frontend
        Frontend --> Apollo
    end

    %% Backend Services
    subgraph "Backend Services"
        Django["Django GraphQL/REST API"]:::backend
        Crypto["Encryption & Crypto Services"]:::backend
        AuthAdapters["Auth Adapters (OAuth SSO)"]:::backend
    end

    %% Background Workers & Queue
    subgraph "Background Processing"
        Redis["Redis (Cache & RQ Queue)"]:::db
        Workers["RQ Workers"]:::backend
    end

    %% Datastores
    subgraph "Datastores"
        Postgres["PostgreSQL"]:::db
        DynamoDB["DynamoDB (Audit & Logs)"]:::db
    end

    %% External Integrations
    subgraph "External Services & Integrations"
        GitHub["GitHub"]:::external
        GitLab["GitLab"]:::external
        Google["Google OAuth"]:::external
        AWS["AWS Secrets Manager"]:::external
        Cloudflare["Cloudflare"]:::external
        Vault["Vault"]:::external
        Vercel["Vercel"]:::external
        Nomad["Nomad"]:::external
        Railway["Railway"]:::external
    end

    %% Deployment
    subgraph "Deployment / Orchestration"
        Compose["Docker Compose / Kubernetes"]:::deployment
    end

    %% Connections
    Nginx --> Frontend
    Nginx --> Django
    Django -->|read/write| Postgres
    Django -->|cache & enqueue| Redis
    Django --> Crypto
    Redis --> Workers
    Workers -->|writes logs| DynamoDB
    Workers --> GitHub
    Workers --> GitLab
    Workers --> AWS
    Workers --> Cloudflare
    Workers --> Vault
    Workers --> Vercel
    Workers --> Nomad
    Workers --> Railway
    Workers --> Google
    AuthAdapters --> GitHub
    AuthAdapters --> GitLab
    AuthAdapters --> Google
    Crypto -->|uses| DynamoDB
    Compose --> Frontend
    Compose --> Django
    Compose --> Postgres
    Compose --> Redis
    Compose --> Workers
    Compose --> Nginx

    %% Click Events
    click Frontend "https://github.com/phasehq/console/tree/main/frontend/"
    click Apollo "https://github.com/phasehq/console/tree/main/frontend/apollo/"
    click CLI "https://github.com/phasehq/console/blob/main/frontend/scripts/start.sh"
    click Nginx "https://github.com/phasehq/console/tree/main/nginx/"
    click Django "https://github.com/phasehq/console/tree/main/backend/api/"
    click Crypto "https://github.com/phasehq/console/blob/main/backend/api/utils/crypto.py"
    click AuthAdapters "https://github.com/phasehq/console/tree/main/backend/api/authentication/adapters/"
    click Redis "https://github.com/phasehq/console/blob/main/backend/api/tasks.py"
    click Workers "https://github.com/phasehq/console/blob/main/backend/api/management/commands/rqworker.py"
    click Postgres "https://github.com/phasehq/console/tree/main/backend/api/migrations/"
    click DynamoDB "https://github.com/phasehq/console/tree/main/backend/logs/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#ffe5b4,stroke:#8a4b00,color:#8a4b00;
    classDef db fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef deployment fill:#f3e5f5,stroke:#4a148c,color:#4a148c;
    classDef proxy fill:#ffe5b4,stroke:#8a4b00,color:#8a4b00;
```
