Heart of Yours
Backend for the Heart of Yours fitness app. Dart server on AWS Lambda behind API Gateway, Postgres via Supabase, all CDN/storage on AWS.
Repository layout
heart-go/
βββ api/ # Dart server (Lambda entrypoint)
βββ shared/
β βββ heart_models/ # Data classes + service interfaces (used by api + the Flutter client)
β βββ heart_aws/ # Boto3-shaped AWS clients (S3, SQS, SNS, Scheduler) on aws_signature_v4
βββ database/
β βββ migrations/ # Forward-only SQL migrations
β βββ tests/ # pgtap suite β public/{tables,functions}, archive/...
β βββ test_utils/ # Test helpers (builders + JSON validators)
βββ firebase/ # Python Lambda: FCM push + Firebase auth cleanup (uv workspace member)
βββ assets/ # Python Lambda: exercise media processing pipeline (uv workspace member)
βββ infrastructure/ # Terraform stacks (api, assets, cdn, content, firebase, monitoring)
β # + environments/{dev,prod} β see infrastructure/README.md
βββ content/ # Exercise library YAML + schema + sample templates JSON, synced to CDN
βββ scripts/ # Migration runner, db test runner, library sync/validation
βββ site/ # Static marketing/legal pages
βββ docs/ # Dated design docs; handoff.md is the definition of done, style.md the house style
βββ agents/ # Autonomous agent launchers + guard hook (see agents/README.md)
βββ .github/workflows/ # CI: deploy-api, deploy-assets, deploy-firebase, exercise-library
# (each split into a reusable workflow + dev/prod wrappers)
Per-component docs:
Stack
| Layer | Tech |
|---|
| Server runtime | Dart 3.10 + relic, compiled to native + Lambda Web Adapter |
| Storage | Postgres (Supabase), no ORM β raw SQL |
| Object storage / CDN | S3 + CloudFront |
| Auth | Firebase OIDC token verification |
| Async | EventBridge S3-rules β SQS β /events (Lambda routes events back to itself) |
| Scheduled jobs | EventBridge Scheduler β SQS β /events |
| Side services | Python 3.13 Lambdas in a uv workspace: firebase/ (push, auth cleanup), assets/ (media) |
| IaC | Terraform (with Supabase provider) |
| CI/CD | GitHub Actions, OIDC role for AWS |
| Tests | Dart test + mockito for app code, pgtap for the database, pytest for the Python services |
Local development
make bootstrap
make db-up
make test
make lint
Each suite can also run individually β make test-dart / test-db / test-python,
or the underlying commands directly (see the Makefile and per-component READMEs).
The api package can be run locally against any Postgres + AWS profile β see api/README.md.
Deployment
Every workflow family is a reusable workflow plus thin -dev / -prod wrappers. Dev ships from
main pushes. Prod: api and exercise-library ship from v* tags; assets and firebase prod
deploys are currently manual (workflow_dispatch). Pull requests run the test jobs only β the
deploy jobs are gated on the event type.
deploy-api.yml (api/shared/database changes):
- Lint, format check, analyze
- Dart tests across all three packages
- Database tests: ephemeral Postgres + pgtap via
scripts/db_tests.sh, then the full api suite
(including db-tagged integration tests) with a coverage floor
- Apply unapplied migrations to Supabase
- Build Lambda binary, update function, smoke-test
/version
deploy-firebase.yml / deploy-assets.yml (Python changes): pytest, then package and update the
function code.
exercise-library.yml (content changes): validate the library YAML against its JSON schema plus
the sync parser, then sync exercises + translations to Postgres (guarded against mass-archiving).
Conventions
- Migrations are forward-only. No down migrations. Wrong schema β write a new migration that fixes it.
- No comments unless the WHY is non-obvious β naming carries the WHAT.
- Single source of truth for shapes. Anything the client sees lives in
heart_models; server-only types stay in api/lib/models.
- Boto3-shaped AWS package β generic, no domain knowledge in
heart_aws.
Licence
The server and everything else in this repository is under the
GNU AGPL v3.0. The shared packages (shared/heart_models, shared/heart_aws,
shared/heart_design) are under the Apache License 2.0, and the
exercise library and other content in content/ under CC BY 4.0.
The name and logo aren't covered by any of them. NOTICE has the full map, including
what in the repository isn't ours. The reasons are in
docs/2026-10-24.licence.md.
Contributing
Contributions come in under the licence of the directory they change (inbound = outbound): AGPL
for the server, Apache-2.0 for the shared packages, CC BY 4.0 for content/. Opening a pull
request means you agree to that and that the work is yours to give. There is no CLA.