Croco SaaS Golden Path Kit

[kang-heewon]

Summary

croco create app --preset saas가 생성 직후 실행 가능한 멀티테넌트 SaaS baseline을 만들도록 한다.

이 기능은 Croco의 시장-facing demo이자 golden path다. 목표는 모든 SaaS 기능을 완성하는 것이 아니라, Croco가 tenant/auth/access/billing/metering/entitlements를 일관된 framework 경험으로 연결할 수 있음을 보여주는 것이다.

Product Narrative

새 사용자는 다음 경험을 기대한다.

1. croco create app --preset saas를 실행한다.
2. 패키지 누락이나 타입 오류 없이 install/typecheck/build/test가 통과한다.
3. demo seed를 실행하면 tenant가 생성된다.
4. 사용자를 초대하고 membership을 만든다.
5. 권한 체크가 동작한다.
6. usage를 기록하고 entitlement/billing 상태를 확인한다.
7. 운영 endpoint로 앱 상태를 확인할 수 있다.

Why This Matters

• Croco의 가치를 가장 쉽게 설명하는 feature다.
• 개별 패키지의 존재 이유를 하나의 앱 경험으로 증명한다.
• Runtime Contract Matrix, Contract Graph, Operations Plane의 성과를 실제 사용자 flow로 묶는다.

MVP Scope

Generated app

• tenant/membership/invitation wiring.
• auth/access integration.
• billing/metering/entitlements minimal flow.
• Problem error shape와 contract-first API/client integration.
• health/diagnostics endpoint 포함.

Demo flow

• tenant creation.
• invitation and membership creation.
• permission check.
• usage record.
• entitlement check.
• generated client 또는 CLI를 통한 smoke flow.

Quality gates

• 생성 앱 typecheck.
• 생성 앱 build.
• 생성 앱 unit/integration smoke.
• dependency manifest sanity check.

Non-Goals

• 첫 버전에서 full admin UI를 만들지 않는다.
• 모든 auth provider와 payment provider 조합을 지원하지 않는다.
• production-grade billing policy 전체를 구현하지 않는다.
• multi-region deployment automation은 별도 후속으로 둔다.

Design Constraints

• template이 존재하지 않는 export나 transitive dependency에 의존하면 안 된다.
• generated app은 가능한 적은 수의 명시적 선택지만 요구해야 한다.
• demo flow는 문서와 테스트에서 같은 순서로 재현 가능해야 한다.
• 각 도메인 패키지는 loose demo wiring이 아니라 public API를 통해 연결되어야 한다.

Suggested Breakdown

1. 현재 create-croco-app 템플릿의 package/install/typecheck 실패 지점을 먼저 정리한다.
2. SaaS preset의 package set과 runtime target을 결정한다.
3. tenant/membership/invitation/auth/access minimal flow를 연결한다.
4. billing/metering/entitlements minimal flow를 연결한다.
5. Contract Graph 기반 API/client generation을 연결한다.
6. Operations Plane endpoints를 기본 활성화한다.
7. seed/demo command를 추가한다.
8. generated app smoke test를 CI에 추가한다.
9. README quickstart를 generated app 기준으로 작성한다.

Acceptance Criteria

• croco create app --preset saas 결과물이 manual package fix 없이 install/typecheck/build/test를 통과한다.
• demo flow가 end-to-end로 동작한다.
• 생성 앱의 API/client contract가 drift 없이 생성된다.
• health/diagnostics endpoint가 기본으로 동작한다.
• unsupported provider 조합은 명시적으로 막거나 문서화된다.

Validation Strategy

• pnpm test --filter=create-croco-app
• generated app install/typecheck/build smoke
• generated app demo flow e2e smoke
• package entrypoint/dependency smoke
• runtime target smoke, 최소 Node + 하나의 deployment target

Related Issues

Seed issues:

• [create-croco-app] SSR 라우트 템플릿이 컴포넌트 값을 잘못 연결함 #694
• [metering-core] RedisUsageStorage.resetBillingCycle이 tenant-wide reset에서 KEYS를 사용함 #703
• [metering-core] RedisUsageStorage의 로컬 idempotency 캐시가 장기 프로세스에서 커질 수 있음 #704
• [metering-core] fetchUsageRecords가 Redis sorted set score의 원래 timestamp를 버림 #705

Done When

새 사용자가 Croco SaaS preset을 생성하고, 문서에 적힌 demo flow를 그대로 실행해 멀티테넌트 SaaS baseline이 작동함을 확인할 수 있을 때 완료로 본다.