FitGlue Server
FitGlue is a fitness data aggregation and routing platform built on Google Cloud Platform. It ingests workout data from multiple sources (Hevy, Fitbit, Strava, Intervals.icu, GitHub, parkrun), enriches it through configurable pipelines, and routes it to connected services.
Architecture
FitGlue uses a domain-service architecture: 11 Go Cloud Run services communicating via gRPC, with a thin API gateway layer for HTTP clients.
┌─────────────────┐ ┌──────────────────────┐
│ Data Sources │─────▶│ service.api.webhook │
│ (Hevy/Strava/ │ │ (HMAC / OAuth auth) │
│ Fitbit / etc.) │ └──────────┬────────────┘
└─────────────────┘ │ Pub/Sub
▼
┌──────────────────────┐
│ service.pipeline │
│ (enrich, split, │
│ route) │
└──────────┬────────────┘
│ Pub/Sub
▼
┌──────────────────────┐
│ service.destination │
│ (upload to Strava, │
│ TrainingPeaks, etc.)│
└──────────────────────┘
API gateways sit in front for HTTP clients:
service.api.client — the owner's tools: Jarvis, fitgluectl, fitglue-mcp (static bearer token, see Security)service.api.public — Unauthenticated (showcase)
Domain services own their Firestore data and expose gRPC interfaces:
service.user, service.pipeline, service.activity
Worker services consume Pub/Sub topics:
service.destination — uploads to Strava, TrainingPeaks, Fitbit, etc.
See Architecture Overview for the full system diagram.
Tech Stack
| Component | Technology |
|---|
| Language | Go 1.25+ |
| Compute | Cloud Run (Docker containers) |
| Messaging | Cloud Pub/Sub |
| Database | Cloud Firestore |
| Storage | Cloud Storage (FIT files, GCS payloads) |
| Inter-service | gRPC (protobuf) |
| CI/CD | GitHub Actions on PRs; CircleCI deploy on main until F4 (see CI/CD) |
| Infrastructure | Terraform |
| Observability | structured slog; Sentry optional via a single SENTRY_DSN |
Quick Start
Prerequisites
- Go 1.25+
- Docker + Docker Compose
protoc (Protocol Buffers compiler)- Google Cloud SDK
Setup
# Install Go dependencies and generate proto stubs
make setup
make generate
# Build all services
make build
# Run unit tests
make test
# Start local development stack (all 11 services)
make local
See Local Development for detailed instructions.
Project Structure
fitglue-server/
├── src/
│ ├── go/ # Go monorepo
│ │ ├── services/ # 11 Cloud Run services (main.go per service)
│ │ ├── internal/ # Domain logic (owned by services)
│ │ ├── pkg/ # Shared packages (proto stubs, integrations)
│ │ ├── cmd/ # CLI tools (fit-gen, fit-inspect)
│ │ └── tests/e2e/ # Cucumber/godog E2E tests
│ └── proto/ # Protocol Buffer definitions
├── terraform/ # Infrastructure as Code
├── docs/ # Documentation
│ ├── api/ # OpenAPI spec (auto-generated)
│ ├── architecture/ # Architecture guides
│ ├── decisions/ # ADRs + history
│ ├── development/ # Dev guides
│ ├── guides/ # How-to guides
│ ├── infrastructure/ # CI/CD, Terraform
│ └── reference/ # Errors
├── scripts/ # Dev and CI scripts
└── Makefile # Build, test, generate, deploy commands
Documentation
Getting Started
Architecture
Development
Troubleshooting
Infrastructure
- CI/CD — PR checks on GitHub Actions; the
main deploy that F4 retires
Decisions
Contributing
This is a personal project, but suggestions and feedback are welcome via issues.
License
MIT
