このリポジトリについて（免責） 開発中の SaaS「忘ランス (wasulance)」のモノレポから API レイヤ (
apps/api) のみを議論用に抜き出したスナップショットです。
- 単体ではビルド／型チェックは通りません（
@wasulance/db/@wasulance/sharedなどワークスペース内パッケージや Prisma schema は親モノレポ側にあります）。- ドキュメント内の
../../docs/...等の相対リンクや Issue 番号は親リポジトリ向けで、ここでは行き止まりになります。- 機密情報（
.env/ 鍵 / 接続文字列）は含みません。Git 管理対象ファイルのみを抽出しています。- 読みどころは「設計判断の意図」です。動かすためではなく、コードの構造と判断の跡を見ていただく目的のリポジトリです。
/api/* を担う Hono ベースの API レイヤ。AI 駆動開発で構築・運用しています。
忘ランス (wasulance) は、フリーランス・個人事業主向けの「請求書の送り忘れ防止」リマインダー SaaS。
請求書の送付タイミングを Excel やカレンダーで管理していると「送り忘れ」が起きやすく、請求が遅れれば入金が遅れるだけでなく、取引先からの信用にも関わる。これを「忘れない仕組み」で解決する。
| 機能 | 概要 |
|---|---|
| 請求スケジュール登録 | クライアントごとに請求日 / 通知タイミングを登録 |
| リマインド通知 | Email / Slack / LINE / Discord / Chatwork / WebPush で「請求書を送る日」を通知 |
| 請求済みチェック | 月次でクライアント別に「請求書を送ったか（請求済み / 未請求）」をチェックリスト管理 |
| サブスクリプション | Free（3 件まで）/ Pro（無制限 + 外部通知チャネル）。Stripe Subscriptions |
狙うのは、取引先と直接取引していて、取引先ごとに請求期日がバラバラで送り忘れてしまうフリーランス——多くはないが確実にいる層。だから請求書の発行・送付・入金確認といった「重い」機能は外部 SaaS に任せ、本プロダクトは 「指定したチャネルに『請求書を送る時が来た』と通知する」一点だけに特化している。
本リポジトリはこのプロダクトの API レイヤ（バックエンド） 部分。本番環境は AWS 上に構築済み（Hono API Lambda・公開前）。
このリポジトリで特に見ていただきたいのは、**「AI に書かせても破綻しないための型と構造のガードレール」**です。
- 依存方向を一方向に固定したレイヤリング —
domain → usecases → interface-adapters → framework。domainはどのワークスペース・ライブラリにも依存しない（実装規約:CLAUDE.md§1）。 - インターフェースに依存させたテスタブルな構成 — interactor はドメインのインターフェース（port）をコンストラクタ注入で受けるため、テストは
vi.fn()をインターフェース型で固めて注入し DB / Prisma なしで業務ロジックを検証できる。テストは具体実装を一切 import しない。 例:tests/usecases/schedules/schedules.test.ts - AI 駆動開発を規約とガードレールで縛る — 実装規約（
CLAUDE.md）に加え、.claude/に開発規律・実行ガードレール・専門サブエージェント・ワークフローを整備している（下記「AI 駆動開発の仕組み」）。
AI に書かせても品質と安全を落とさないための、規律・ガードレール・自動化を .claude/ に置いている。
.claude/settings.json— AI が実行できない操作を機械的に deny（破壊的コマンド / 保護ブランチへの直 push /.env等の機密読み取り /curlでの外部送信）。AI に過剰な権限を渡さない（OWASP LLM06 対策）。.claude/rules/— 開発規律（agent-behavior.md）とセキュリティ指針（security.md）。.claude/agents/— code-reviewer / security-auditor / test-writer / docs-writer の専門サブエージェント定義。.claude/skills/— 開発ワークフローをスキル化（ship / clean-sync / commit-push / fix-review-comments / review-pr / deploy）。
.claude/rules/はプロジェクト横断の規約をこのリポジトリ用に抜粋したもの。絶対パス等はサニタイズ済み。
品質ゲートと本番デプロイを CI から手元に寄せ、コミット/デプロイのたびの CI 消費を削減している（hook・スクリプトはモノレポ root 側）。
- pre-commit hook（Husky）でコミット時に品質ゲートを強制：
pnpm exec lint-staged # prettier で format pnpm turbo run lint typecheck test:cov # lint + 型チェック + テスト(カバレッジ)
set -eで 1 つでも落ちればコミット不可。 - 本番デプロイはローカルスクリプト（
deploy-prod.sh+ 事前チェックpreflight-deploy-check.sh）。 - 結果、コミットごとの lint/test/build や deploy の CI ワークフローは無効化（
ci.yml.disabled等）。
これは CI の代替ではない。hook は
--no-verifyでバイパス可能で、ローカル（macOS）で通っても Linux/Lambda で壊れる差（例: ファイル名の case-sensitivity）は捕まえられない。チーム開発や本番の厳密性が要る場面ではバイパス不能な CI ゲートを置くべき——と理解した上での、一人開発のコスト最適化。
git worktree で複数のブランチを別ディレクトリに同時チェックアウトし、独立した機能/Issue を並列で進める。ブランチ切り替えや stash が不要で、worktree ごとに別の AI エージェントセッションを走らせて同時進行できる。
- 隔離: worktree ごとに作業が独立（変更が混ざらない・それぞれ独立してビルド/テスト可能）
- 並列: 独立したタスクを同時進行（依存のない複数 Issue に有効）
- 運用フロー: worktree 作成 → develop を各 worktree に取り込み → マージ済みは掃除（スキル化）
効くのは独立したタスクの並列化。相互依存する作業や同じファイルを触る変更はマージ調整が必要。
- 認証 (signup / login / refresh / logout / email 認証 / パスワードリセット) を JWT HS256 + bcrypt で提供
- ドメイン use case (
auth/clients/schedules/subscriptions/calendar/line/users/invoices/contact/admin等) を Hono ルートにマッピング - Prisma / jose / bcryptjs / Stripe / SES 等のインフラ依存は
interface-adapters/だけが触れる（唯一の seam） - 配信形態: localhost dev は
@hono/node-server、prod は AWS Lambda（apps/webから CloudFront 経由）
src/
├── domain/ entities / value-objects / repositories / services / exceptions
├── usecases/ auth / clients / schedules / subscriptions / calendar ...
│ ── 各 verb ごとに input-port.ts / interactor.ts / output-port.ts
├── interface-adapters/ PrismaXRepository / JoseTokenService / BcryptPasswordHashService 等
└── framework/
├── controllers/ *.controller.ts （output → HTTP 写像 + exhaustive check）
├── middleware/ auth / rate-limit / error-handler
├── di/ container.ts
└── app.ts buildApp()
tests/ src とミラー構造（domain / usecases / interface-adapters / framework / integration）
144 本。具体実装を import せず、ドメインの port を mock して DB なしで検証
実装規約の正本は CLAUDE.md。層構成 / 命名 / use case の書き方 / DI / テスト方針はそちらが正です（テスト方針は §8）。