Skip to content

Latest commit

 

History

History
182 lines (133 loc) · 9.61 KB

README.md

File metadata and controls

182 lines (133 loc) · 9.61 KB

Smalruby インフラ全体

Smalruby のバックエンドは AWS CDK で管理される独立したプロジェクトから構成される。すべて ap-northeast-1 (東京) リージョンにデプロイされ、共通の .env symlink パターンで stage 切替を行う。

プロジェクト一覧

プロジェクト 用途 主要 AWS サービス カスタムドメイン (prod) 統合ドキュメント
infra/smalruby-mesh-v2/ Mesh v2 リアルタイム通信 AppSync (GraphQL) + DynamoDB graphql.api.smalruby.app docs/mesh-v2/
infra/smalruby-rubytee-relay/ Rubytee (AI チャット) リレー API Gateway HTTP API + Lambda + DynamoDB rubytee.api.smalruby.app docs/rubytee/
infra/smalruby-classroom/ クラスルーム機能 API Gateway HTTP API + Lambda + DynamoDB + S3 classroom.api.smalruby.app docs/classroom/
infra/smalruby-api/ 共通 API (CORS proxy / Mesh zone / Scratch proxy) API Gateway HTTP API + Lambda api.smalruby.app smalruby-api.md
infra/smalruby-studuino-hex/ Studuino モードの hex を作る(arduino-cli でコンパイル) API Gateway HTTP API + Lambda(コンテナ)+ DynamoDB なし(execute-api のエンドポイント) smalruby-studuino-hex.md・docs/studuino-mode/
infra/smalruby-web-hosting/ Web 配信基盤(stg: ブランチプレビュー preview.smalruby.app/<slug>/・prod: 本番 smalruby.app) Route 53, S3, CloudFront, ACM, IAM (OIDC) preview.smalruby.app(stg)。prod は本番 smalruby.app の配信基盤(独自ドメインは切り替え時に付ける・docs/hosting/) smalruby-web-hosting.md

共通パターン

AWS 基本

項目 値
リージョン ap-northeast-1 (東京)
CDK バージョン aws-cdk-lib 2.275.0 / CLI aws-cdk 2.1147.0(全プロジェクト同一)
Lambda ランタイム Node.js 22.x(mesh-v2 のみ Ruby も使用)
DynamoDB 課金 PAY_PER_REQUEST (オンデマンド)
TTL 属性 全テーブル ttl フィールドで自動削除
ログ保持 prod: 1 ヶ月 / stg: 1 週間
CORS preflight キャッシュ 24 時間

Stage 管理 (.env symlink パターン)

すべての CDK プロジェクトは .env symlink で stage を切り替える:

cd infra/smalruby-mesh-v2

# stg に切り替え
rm .env && ln -s .env.stg .env

# prod に切り替え
rm .env && ln -s .env.prod .env
  • コマンドラインで env vars を上書きしない (.env symlink を必ず使う)
  • 詳細は .claude/rules/infra/development.md を参照

Stage suffix の命名規則

CloudFormation スタック名・Lambda 関数名・DynamoDB テーブル名等に付く suffix:

const stageSuffix = stage === 'prod' ? '' : `-${stage}`;

例: RubyteeRelayHandler (prod) / RubyteeRelayHandler-stg (stg)

カスタムドメイン

すべて api.smalruby.app を Route53 親ゾーンとして以下のサブドメインを使う:

Stage パターン
prod <service>.api.smalruby.app
stg stg.<service>.api.smalruby.app

例外: smalruby-api は api.smalruby.app 直下 (旧 SAM スタックからの移行で既存ドメインをインポート)。

CORS

Stage 許可オリジン (デフォルト)
stg https://smalruby.app, https://smalruby.jp, http://localhost:8601〜8610(classroom / bug-report / admin。api / rubytee-relay は 8601 だけ), https://preview.smalruby.app
prod https://smalruby.app, https://smalruby.jp (localhost・プレビュー除外)

→ ローカル開発は stg エンドポイント を使う。prod は CORS で localhost を弾く。

ブランチプレビュー(https://preview.smalruby.app)は stg の API を見るので、非 prod ではどの API も このオリジンを許可する。stg の CORS_ALLOWED_ORIGINS は GitHub secrets(.env.stg)で明示されて いるため、env を指定していても非 prod ではコード側で足す(classroom / bug-report / admin は lib/cors-origins.ts の resolveCorsOrigins、api / rubytee-relay は同じファイルの withPreviewOrigins)。lib/cors-origins.ts は全プロジェクトで同じ内容で、正本は infra/shared/cors-origins.ts(直すときは正本を直して node infra/shared/sync.js。 .claude/rules/infra/development.md の「共有コード(infra/shared)」)。prod の許可オリジンは変えない。 mesh-v2(AppSync)はオリジンを問わずプリフライトに応答し API キーで認可するため、CORS の設定を持たない。

デプロイコマンド

# 共通: docker compose で infra service を使う
docker compose run --rm -w /app/infra/<project> infra npm install
docker compose run --rm -w /app/infra/<project> infra npx cdk synth
docker compose run --rm -w /app/infra/<project> infra npx cdk diff
docker compose run --rm -w /app/infra/<project> infra npx cdk deploy

# 例: rubytee-relay の stg デプロイ
cd infra/smalruby-rubytee-relay
rm .env && ln -s .env.stg .env
docker compose run --rm -w /app/infra/smalruby-rubytee-relay infra npx cdk deploy

環境変数の .env.example

各プロジェクトに .env.example がある。新しい stage を作るときは:

cp .env.example .env.<stage>
# シークレット (MESH_SECRET_KEY 等) を埋める
ln -sf .env.<stage> .env

プロジェクト相関図

                          ┌───────────────────────┐
                          │  smalruby-gui (web)    │
                          │  smalruby.app          │
                          └──────────┬─────────────┘
                                     │
                ┌──────────┬─────────┼─────────┬──────────┐
                ▼          ▼         ▼         ▼          ▼
        smalruby-api  rubytee-   classroom  mesh-v2  (Google Drive,
        (api)         relay      (classroom (graphql  各種 OAuth)
        - cors-proxy  (rubytee)  .api)      .api)
        - mesh-zone               POST /...  AppSync
        - scratch-                                    subscription
        api-proxy                                     + polling

各 infra プロジェクトは独立して deploy される。スタック間に CFN export/import の依存はない (環境変数や Route53 経由でのみ繋がる)。

per-project ドキュメント

mesh-v2 (最も詳細)

充実したドキュメント群あり:

rubytee-relay

Rubytee の統合ドキュメントは docs/rubytee/ を参照。インフラ実装の詳細は .claude/rules/infra/smalruby-rubytee-relay.md を参照。

主要構成:

  • Lambda (Node.js 22, lambda/handler.ts) が Anthropic Claude API を中継
  • DynamoDB (RubyteeRelayRateLimit) で IP ベースのレート制限 (デフォルト 35 分窓 40 リクエスト)
  • Prompt caching (cache_control: ephemeral) でコスト削減
  • 子供向けの安全策 (年齢チェック、メッセージ長制限、CORS)

classroom

クラスルーム機能の統合ドキュメントは docs/classroom/architecture.md を参照。

主要構成:

  • Lambda (Node.js 22, lambda/handler.ts) で 13+ エンドポイント
  • 3 テーブル: Classrooms, ClassroomMemberships, ClassroomSubmissions
  • S3 (smalruby-classroom-submissions) で .sb3 提出物保管 (presigned URL)
  • Google Classroom 連携 (Course / Assignment import)
  • 認証: Google OAuth + Microsoft Entra ID
  • レート制限: 200 req/s (prod) / /classrooms/join /classrooms/lookup のみ 10 req/s

smalruby-api

→ smalruby-api.md を参照(本 docs/infra/ の専用ファイル)。

smalruby-web-hosting

→ smalruby-web-hosting.md を参照。

関連ドキュメント

  • claude-api-wif.md — Claude API を Workload Identity Federation で呼ぶための AWS と Claude Console の設定(作り直しの手順)
  • stg-prod-differences.md — stg と prod の違いの一覧(意図した違いと直すべき違い・GUI ビルド値の stg 版の有無)
  • .claude/rules/infra/ 配下の各プロジェクトルール
  • CLAUDE.md の "infra/" セクション
  • docs/_template.md — 機能 docs テンプレート
  • docs/scratch-vm/ — VM 内部仕様 (クライアント側)