How withgraphite/docs works
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