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 |
| 項目 | 値 |
|---|---|
| リージョン | 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 時間 |
すべての 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 を上書きしない (
.envsymlink を必ず使う) - 詳細は
.claude/rules/infra/development.mdを参照
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 スタックからの移行で既存ドメインをインポート)。
| 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 がある。新しい 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 経由でのみ繋がる)。
充実したドキュメント群あり:
docs/mesh-v2/— クライアント + サーバ統合infra/smalruby-mesh-v2/docs/architecture.md— システムアーキテクチャinfra/smalruby-mesh-v2/docs/api-reference.md— GraphQL スキーマinfra/smalruby-mesh-v2/docs/deployment.md— デプロイ手順infra/smalruby-mesh-v2/docs/development.md— 開発ガイドinfra/smalruby-mesh-v2/docs/operations.md— モニタリング・コスト.claude/rules/infra/smalruby-mesh-v2.md— 開発ルール
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)
クラスルーム機能の統合ドキュメントは 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.md を参照(本 docs/infra/ の専用ファイル)。
→ 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 内部仕様 (クライアント側)