How shorebirdtech/shorebird works
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