# shorebirdtech/shorebird architecture

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

- Interactive diagram: https://gitdiagram.com/shorebirdtech/shorebird
- Repository: https://github.com/shorebirdtech/shorebird

## Overview

##### Project type and purpose
- This is a Dart monorepo (full-stack in the broad sense) hosting multiple related packages:
- shorebird_cli – a local CLI tool for developers
- shorebird_code_push_client & protocol – client-side libraries for communicating with the Shorebird CodePush API
- artifact_proxy & discord_gcp_alerts – standalone Dart servers
- jwt, redis_client, scoped_deps – utility libraries
- Its goal is to provide the shorebird developer experience: CLI orchestration, code‐push client, proxying Flutter artifacts, and forwarding GCP alerts to Discord.

##### File structure
- Top-level:
- .github/, scripts/ – CI, CD, e2e, deployment scripts
- bin/shorebird* – launcher scripts for the CLI
- packages/ – each subfolder is a standalone Dart package, grouped into:
– CLI (shorebird_cli)
– Client libraries (shorebird_code_push_client, shorebird_code_push_protocol)
– Server components (artifact_proxy, discord_gcp_alerts)
– Utility libraries (jwt, redis_client, scoped_deps)
- Each package follows the Dart “bin/”, “lib/”, “test/” pattern and has its own Dockerfile if it’s a server.

##### README
- Confirms this is a monorepo of interrelated Shorebird modules
- Describes each package’s purpose
- Points to docs and CI workflows

a. Main components to represent:
1. Developer Environment
- shorebird_cli (local binary)
- Dependencies: shorebird_code_push_client & shorebird_code_push_protocol libraries
2. Shorebird Backend Services
- (External/hosted) CodePush API – target of shorebird_code_push_client calls
3. artifact_proxy Server
- Proxies Flutter artifact downloads → Flutter artifact storage (e.g., pub.dartlang.org or GCS)
- Exposes HTTP endpoint
4. discord_gcp_alerts Server
- Subscribes to GCP Alert Pub/Sub push → forwards to Discord Webhook
5. Shared Libraries
- jwt, redis_client, scoped_deps – used as dependencies by the above components
6. CI/CD & Deployment
- GitHub Actions workflows that build, test, deploy artifact_proxy & discord_gcp_alerts

b. Relationships and interactions:
- shorebird_cli → (HTTP/HTTPS) → Shorebird CodePush API (uses shorebird_code_push_client & protocol)
- Developer’s Flutter toolchain → (HTTP) → artifact_proxy → (HTTP) → Flutter artifacts storage
- GCP Alert Pub/Sub → (push) → discord_gcp_alerts → (HTTP webhook) → Discord
- Shared libraries (jwt, redis_client, scoped_deps) are code‐level dependencies imported by CLI and servers
- CI/CD pipelines trigger Docker builds & deployments of server components

c. Architectural patterns / design principles:
- Modular monorepo: clear package boundaries, independent versioning
- CLI–Client–API separation: CLI depends on client lib, decoupled from backend
- Micro-services style: artifact_proxy and discord_gcp_alerts are self-contained servers
- Dependency injection via scoped_deps for runtime flexibility
- Use of code generation (build.yaml, *.g.dart) for protocol messages and config

d. Key technologies:
- Dart & pub for packages
- build_runner / codegen for JSON serialization (g.dart files)
- Docker + GitHub Actions for server deployment
- Zones/DI (scoped_deps) for managing scoped runtime state
- Redis client and JWT for auth/session management

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        CLI["shorebird_cli"]:::runtime
        CodePushClient["shorebird_code_push_client"]:::lib
        CodePushProtocol["shorebird_code_push_protocol"]:::lib
    end

    %% API Layer
    subgraph "API Layer"
        CP_API["Shorebird CodePush API"]:::external
    end

    %% Server Layer
    subgraph "Server Layer"
        AP["artifact_proxy"]:::runtime
        DG["discord_gcp_alerts"]:::runtime
    end

    %% External Services
    subgraph "External Services"
        FA["Flutter Artifact Storage"]:::external
        PubSub["GCP Pub/Sub"]:::external
        DiscordWeb["Discord Webhook"]:::external
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        JWT["jwt"]:::lib
        Redis["redis_client"]:::lib
        DI["scoped_deps"]:::lib
    end

    %% CI/CD
    subgraph "CI/CD & Deployment"
        GH["GitHub Actions"]:::ci
    end

    %% Relationships
    CLI -->|"uses client lib"| CodePushClient
    CLI -->|"imports protocol"| CodePushProtocol
    CodePushClient -->|"HTTP+JSON via protocol"| CP_API
    DevFT["Developer's Flutter Toolchain"]:::runtime
    DevFT -->|"HTTP"| AP
    AP -->|"HTTP"| FA
    PubSub -->|"push"| DG
    DG -->|"HTTP webhook"| DiscordWeb

    CLI -.->|imports| JWT
    CLI -.->|imports| Redis
    CLI -.->|uses DI| DI
    AP -.->|uses JWT| JWT
    AP -.->|uses Redis| Redis
    AP -.->|uses DI| DI
    DG -.->|uses JWT| JWT
    DG -.->|uses Redis| Redis
    DG -.->|uses DI| DI

    GH -->|"build & deploy"| AP
    GH -->|"build & deploy"| DG

    %% Click Events
    click CLI "https://github.com/shorebirdtech/shorebird/tree/main/packages/shorebird_cli"
    click CodePushClient "https://github.com/shorebirdtech/shorebird/blob/main/packages/shorebird_code_push_client/lib/src/code_push_client.dart"
    click CodePushProtocol "https://github.com/shorebirdtech/shorebird/tree/main/packages/shorebird_code_push_protocol/lib/src/messages"
    click AP "https://github.com/shorebirdtech/shorebird/blob/main/packages/artifact_proxy/bin/server.dart"
    click DG "https://github.com/shorebirdtech/shorebird/blob/main/packages/discord_gcp_alerts/bin/server.dart"
    click JWT "https://github.com/shorebirdtech/shorebird/blob/main/packages/jwt/lib/src/encoding.dart"
    click Redis "https://github.com/shorebirdtech/shorebird/blob/main/packages/redis_client/lib/src/redis_client.dart"
    click DI "https://github.com/shorebirdtech/shorebird/blob/main/packages/scoped_deps/lib/src/scoped_deps.dart"
    click GH "https://github.com/shorebirdtech/shorebird/blob/main/.github/workflows/deploy_artifact_proxy_dev.yaml"

    %% Styles
    classDef runtime fill:#a2d5c6,stroke:#333,stroke-width:1px
    classDef lib fill:#d3e0ea,stroke:#333,stroke-width:1px
    classDef external fill:#a0c4ff,stroke:#333,stroke-width:1px
    classDef ci fill:#ffadad,stroke:#333,stroke-width:1px
    classDef dotted stroke-dasharray: 5 5

    class CLI,AP,DG,DevFT runtime
    class CodePushClient,CodePushProtocol,JWT,Redis,DI lib
    class CP_API,FA,PubSub,DiscordWeb external
    class GH ci
    class CLI,AP,DG,DevFT,CodePushClient,CodePushProtocol,JWT,Redis,DI,CP_API,FA,PubSub,DiscordWeb,GH dotted
```
