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 Overview — System topology and data flow
• Go Services — Service structure, IoC pattern, directory map
• Local Development — Running the stack locally

Architecture

• API Layers — The three HTTP gateways
• Service Communication — gRPC inter-service RPC
• Services & Stores — Domain service patterns
• Plugin System — Sources, enrichers, destinations
• Security — Auth and access control

Development

• Testing Guide — Unit, E2E, and integration tests
• Enricher Testing — Testing enrichment providers
• OAuth Integration — Strava and Fitbit OAuth setup
• Connecting sources from the box — fitgluectl connect / connections, per-provider webhook notes

Troubleshooting

• Troubleshooting Guide — Start here when debugging any issue
• Error Codes Reference — All error codes and retryability

Infrastructure

• CI/CD — PR checks on GitHub Actions; the main deploy that F4 retires

Decisions

• Architecture Decisions (ADR) — Key design choices
• Go Migration Proposal — Historical migration rationale

Contributing

This is a personal project, but suggestions and feedback are welcome via issues.

License

MIT