Heart

Heart of Yours

Heart of Yours フィットネスアプリのバックエンドです。API Gateway の背後にある AWS Lambda 上で動作する Dart サーバー、Supabase 経由の Postgres、CDN／ストレージはすべて AWS を使用しています。

リポジトリの構成

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)

コンポーネント別のドキュメント：

• api/README.md — サーバーアーキテクチャ、ルーティング／DB／AWS の規約、テスト
• database/README.md — マイグレーション＋pgtap
• infrastructure/README.md — Terraform スタック＋デプロイ

技術スタック

レイヤー	技術
サーバーランタイム	Dart 3.10＋relic、ネイティブ形式にコンパイル＋Lambda Web Adapter
ストレージ	Postgres（Supabase）、ORM なし — 生の SQL
オブジェクトストレージ／CDN	S3＋CloudFront
認証	Firebase OIDC トークンの検証
非同期処理	EventBridge S3-rules → SQS → /events（Lambda がイベントを自身にルーティング）
スケジュールジョブ	EventBridge Scheduler → SQS → /events
サイドサービス	uv ワークスペース内の Python 3.13 Lambdas：firebase/（プッシュ通知、認証クリーンアップ）、assets/（メディア）
IaC	Terraform（Supabase プロバイダーを使用）
CI/CD	GitHub Actions、AWS 用 OIDC ロール
テスト	アプリコードには Dart test＋mockito、データベースには pgtap、Python サービスには pytest

ローカル開発

make bootstrap   # dart pub get + mocks for all packages, uv sync, git hooks
make db-up       # containerized Postgres 17 + pgtap (skip if you run a native one)
make test        # the full matrix: Dart x3, migrations + pgtap, pytest x3
make lint        # dart analyze x3 + ruff

各テストスイートは個別に実行することもできます — make test-dart / test-db / test-python、 または下層のコマンドを直接実行してください（Makefile と各コンポーネントの README を参照）。

api パッケージは、任意の Postgres＋AWS プロファイルを使ってローカルで実行できます — api/README.md を参照してください。

デプロイ

ワークフローの各系統は、再利用可能なワークフローと薄い -dev／-prod ラッパーで構成されています。Dev は main へのプッシュでデプロイされます。Prod：api と exercise-library は v* タグでデプロイされます。assets と firebase の本番 デプロイは現在手動です（workflow_dispatch）。プルリクエストではテストジョブのみが実行されます — デプロイジョブはイベント種別によって制御されます。

deploy-api.yml（api／共有／データベースの変更）：

1. Lint、フォーマットチェック、解析
2. 3 つすべてのパッケージで Dart テストを実行
3. scripts/db_tests.sh を使って一時的な Postgres＋pgtap でデータベーステストを実行し、その後、カバレッジの最低基準を満たした状態で api スイート全体（db タグ付きの統合テストを含む）を実行
4. 未適用のマイグレーションを Supabase に適用
5. Lambda バイナリをビルドし、関数を更新して、/version のスモークテストを実行

deploy-firebase.yml／deploy-assets.yml（Python の変更）：pytest を実行し、その後、関数コードをパッケージ化して更新します。

exercise-library.yml（コンテンツの変更）：ライブラリの YAML を JSON スキーマと同期パーサーに対して検証し、その後、Postgres にエクササイズと翻訳を同期します（大量アーカイブを防止するガード付き）。

規約

• マイグレーションは前進のみです。 ダウンマイグレーションはありません。スキーマに誤りがある場合は、それを修正する新しいマイグレーションを作成してください。
• WHY が自明でない場合を除き、コメントは付けません — WHAT は命名で表します。
• データ形状の単一の信頼できる情報源を設けます。 クライアントに見えるものはすべて heart_models に置き、サーバー専用の型は api/lib/models に置きます。
• Boto3 形式の AWS パッケージ — 汎用的なものとし、heart_aws にドメイン知識を持たせません。

ライセンス

サーバーおよびこのリポジトリ内のその他すべては、 GNU AGPL v3.0 の下で公開されています。共有パッケージ（shared/heart_models、shared/heart_aws、 shared/heart_design）は Apache License 2.0 の下で、エクササイズライブラリおよび content/ 内のその他のコンテンツは CC BY 4.0 の下で公開されています。 名称とロゴはいずれのライセンスの対象にもなりません。NOTICE に、リポジトリ内の当社所有ではないものも含めた 全体の内訳が記載されています。その理由については docs/2026-10-24.licence.md をご覧ください。

コントリビューション

コントリビューションには、変更するディレクトリのライセンスが適用されます（受け入れ時と公開時のライセンスは同一です）。サーバーには AGPL、 共有パッケージには Apache-2.0、content/ には CC BY 4.0 が適用されます。プルリクエストを開くことで、 その条件に同意し、提出する成果物が自身のものであることを表明したものとみなされます。CLA はありません。