# withgraphite/docs architecture

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

- Interactive diagram: https://gitdiagram.com/withgraphite/docs
- Repository: https://github.com/withgraphite/docs

## Overview

##### Project type and purpose
- From the README and file tree, this repository is the documentation site for **Graphite**, a **full-stack code-review platform** comprised of:
- A local command-line tool (“graphite cli”) that you install to manage and submit stacked changes
- A SaaS backend and web dashboard (“graphite dashboard”) that hosts the review queue, visualizes stacks, and integrates with GitHub
- The guides are split into two primary feature areas: `guides/graphite-cli` and `guides/graphite-dashboard`, indicating two core components.

##### File structure
- Top-level folders and files:
- `.gitbook/` + `SUMMARY.md`, `README.md` — documentation build config
- `getting-started/` — high-level concepts (privacy, workflow)
- `guides/graphite-cli/` — CLI usage, auth, commands, configuration
- `guides/graphite-dashboard/` — web UI workflows, review queue, customizing dashboard
- `reference/` — deeper technical references (e.g. PAT permissions)
- No source code here, but the structure reflects two delivery clients (CLI + Web) talking to the same backend.

##### README for additional insights
- Key workflows:
- CLI automates recursive rebases, stack management, and GitHub PR creation/updates
- Dashboard shows pull-request inboxes, visualizes PR stacks, and offers customizable queues
- External integration: GitHub for code hosting and PRs

##### Components
a. Main components
1. **Developer Environment**
- Graphite CLI (local binary)
- Git (local repo)
2. **External Service**
- GitHub API & GitHub repository hosting
3. **Graphite Backend**
- API Gateway (GraphQL or REST)
- Business-logic microservices (stack management, PR orchestration, notification)
- Authentication & Authorization service (PAT handling, session tokens)
4. **Datastore Layer**
- Primary database (e.g. PostgreSQL) for users, stacks, reviews, metadata
- Cache layer (e.g. Redis) for session data, rate-limiting
- Message queue (e.g. Kafka or RabbitMQ) for async tasks (webhooks, email, webhook delivery)
5. **Graphite Web Dashboard**
- Frontend SPA (React/Vue) served via CDN or web server
- Static asset host (S3 / CloudFront)
6. **Supporting Infrastructure**
- CI/CD pipeline (build, test, deploy)
- Monitoring & Logging (Prometheus, Grafana, ELK)

b. Relationships and interactions
- **CLI ↔ GitHub API**: fetch branches, push commits, create/update PRs
- **CLI ↔ Graphite API**: auth, fetch user config, register stacks, retrieve review metadata
- **Web Dashboard ↔ Graphite API**: pull inbox data, post comments, render stack graph
- **Graphite API ↔ GitHub API**: mirror GitHub events, webhook listeners, sync PR statuses
- **Graphite API ↔ Datastore**: read/write user, stack, review data
- **Async Tasks**: Graphite backend publishes events to message queue → worker services handle notifications, webhook retries

c. Architectural patterns and design principles
- **Client-Server** separation: CLI and Web are thin clients that communicate over REST/GraphQL
- **Microservices** for scaling distinct areas (stack logic vs. auth vs. notifications)
- **Event-Driven** asynchronous workflows for high-latency operations (webhook processing, email)
- **Caching** at API layer to reduce GitHub API rate usage and speed up UI

d. Key technologies / frameworks
- CLI: Go or Node.js binary, uses Git plumbing & Octokit (GitHub SDK)
- API: Node.js/Express or Go/Gin, GraphQL or REST framework
- DB: PostgreSQL, Redis
- Messaging: RabbitMQ/Kafka
- Frontend: React or Vue, Webpack, served via CDN

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Documentation Site
    subgraph "Documentation Site"
        DS1[".gitbook/"]:::service
        DS2["README.md"]:::service
        DS3["SUMMARY.md"]:::service
        DS4["Getting Started"]:::service
        DS5["Reference (PAT Permissions)"]:::service
        DS6["Auth Guide"]:::service
    end

    %% Developer Environment
    subgraph "Developer Environment"
        CLI["Graphite CLI"]:::client
        Git["Git (Local Repo)"]:::service
    end

    %% External Service
    GH["GitHub API & Hosting"]:::external

    %% Graphite Backend
    subgraph "Graphite Backend"
        APIGW["API Gateway (GraphQL/REST)"]:::service
        subgraph "Microservices"
            SM["Stack Management Service"]:::service
            PR["PR Orchestration Service"]:::service
            NOTIF["Notification Service"]:::service
            AUTH["Auth & Authorization Service"]:::service
        end
    end

    %% Datastore Layer
    subgraph "Datastore Layer"
        PG["PostgreSQL DB"]:::datastore
        REDIS["Redis Cache"]:::datastore
        MQ["Message Queue (Kafka/RabbitMQ)"]:::datastore
    end

    %% Web Dashboard
    subgraph "Web Dashboard"
        DASH["Graphite Dashboard SPA"]:::client
        ASSETS["Static Asset Host (CDN)"]:::service
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        CICD["CI/CD Pipeline"]:::infra
        MON["Monitoring & Logging"]:::infra
    end

    %% Connections
    CLI -->|"uses Git plumbing"| Git
    CLI -->|"fetch/create PRs"| GH
    CLI -->|"auth, config, stacks"| APIGW
    DASH -->|"API calls"| APIGW
    DASH -->|"serves assets"| ASSETS
    ASSETS -->|"CDN delivery"| DASH

    APIGW -->|"read/write users & stacks"| PG
    APIGW -->|"cache sessions & rate limit"| REDIS
    APIGW -->|"publish events"| MQ
    APIGW -->|"sync PR status"| GH
    APIGW -->|"handles auth"| AUTH

    MQ -.->|"async tasks"| NOTIF
    MQ -.->|"async tasks"| PR
    MQ -.->|"async tasks"| SM

    CICD -->|"deploy services"| APIGW
    CICD -->|"deploy dashboard"| DASH
    MON -->|"monitor metrics/logs"| APIGW
    MON -->|"monitor metrics/logs"| DASH
    MON -->|"monitor metrics/logs"| MQ

    %% Documentation Site to components
    DS4 --> CLI
    DS4 --> DASH

    %% Click Events
    click CLI "https://github.com/withgraphite/docs/tree/main/guides/graphite-cli/"
    click DASH "https://github.com/withgraphite/docs/tree/main/guides/graphite-dashboard/"
    click DS4 "https://github.com/withgraphite/docs/tree/main/getting-started/"
    click DS6 "https://github.com/withgraphite/docs/blob/main/guides/graphite-cli/authenticating-the-cli/using-a-github-personal-access-token.md"
    click DS5 "https://github.com/withgraphite/docs/blob/main/reference/pat-permissions.md"
    click DS1 "https://github.com/withgraphite/docs/tree/main/.gitbook/"
    click DS2 "https://github.com/withgraphite/docs/blob/main/README.md"
    click DS3 "https://github.com/withgraphite/docs/blob/main/SUMMARY.md"

    %% Styles
    classDef client fill:#bbdefb,stroke:#000
    classDef service fill:#c8e6c9,stroke:#000
    classDef datastore fill:#ffe0b2,stroke:#000
    classDef external fill:#e0e0e0,stroke:#000
    classDef infra fill:#d1c4e9,stroke:#000
```
