Architecture and operations
This section explains how the fitness application is structured, how it runs on-premises, and how the different services talk to each other. It also links to the deployment, Kubernetes, and webhook details so I can come back later and repeat the setup.
Purpose
Describe the moving parts, the runtime stack, and the operational shape so it is easy to deploy on my own hardware and keep it running.
Audience
- Me.
- Future contributors who need to see the structure before making changes.
- Anyone reviewing the app for security, privacy, or performance.
What this covers
- High-level application architecture.
- Operational choices for a local-first, on-premises environment.
- Links to deployment and Kubernetes notes.
- Integration pattern for Strava webhooks.
How this page fits in
This is the parent page for the architecture documents.
- Technical context (
/applications/fit/architecture/technical). Short stack overview and why I chose it. - System services (
/applications/fit/architecture/services). High-level services and how they communicate. - Data models (
/applications/fit/architecture/models). Stage 1 data model for the personal coach use case. - Strava webhooks implementation (
/applications/fit/architecture/webhooks). How real-time Strava activity sync works. - Deployment and setup guide (
/applications/fit/architecture/deployment). Production-style setup for self-hosted environments. - Kubernetes deployment (
/applications/fit/architecture/kubernetes). Notes for running Fit on a Kubernetes cluster.
Principles and assumptions
- Local-first and runs on-premises.
- Favour simple components that are observable.
- GitOps for repeatable deployments.
- Privacy and data locality are important.
- Use Kubernetes only where it adds value.
Operational outcomes
- Deploy the app the same way every time.
- See what each service does and where it runs.
- Update the app without breaking webhooks.
- Move from development to production with the same structure.