🐊 Croco Framework

Move fast, build robustly.
Croco는 AWS Lambda와 API Gateway를 1급 시민(First-class Citizen)으로 지원하는 Node.js 기반의 Opinionated(주견이 뚜렷한) 프레임워크입니다.
복잡한 비즈니스 로직을 다루는 엔터프라이즈 환경부터 빠른 배포가 필요한 스타트업까지, DDD(Domain-Driven Design) 패턴과 강력한 타입 안전성을 제공합니다.

---

✨ 한 줄 소개

AWS Lambda에 최적화된 Node.js 기반 Opinionated(주견이 뚜렷한) 프레임워크입니다. DDD(Domain-Driven Design) 패턴과 강력한 타입 안전성을 통해 빠르고 견고하게 서비스를 구축할 수 있습니다.

---

🎯 왜 Croco인가?

Croco는 AWS Lambda 지향 TypeScript 애플리케이션에서 HTTP 진입점, DDD 이벤트, 트랜잭션, SaaS 지표/미터링, 관찰 가능성을 하나의 일관된 데코레이터·타입 시스템으로 묶어 주는 opinionated TypeScript 프레임워크입니다.

기존의 Node.js 프레임워크들은 유연하지만, 대규모 프로젝트에서 아키텍처의 일관성을 유지하기 어렵습니다. Croco는 다음과 같은 문제를 해결합니다:

• 정형화된 5계층 구조: 팀 간 코드 일관성 유지
• AWS Lambda 환경에 최적화된 경량 실행 어댑터
• 이벤트 주도 아키텍처(EDA)와 Unit of Work 트랜잭션 관리 기본 제공
• 타입 정의만으로 REST/GraphQL API와 문서 자동 생성 지원

🧭 핵심 설계 원칙

Croco는 런타임에서 추측하게 하지 않고, 빌드타임에 의도를 명시하고 검증하며, 사람과 LLM이 모두 이해할 수 있는 실행 가능한 계약을 중심으로 동작해야 합니다.

• Shift left: route, DI, policy, runtime capability, package boundary 오류는 가능하면 runtime 예외보다 typecheck, build, lint, codegen, CI 단계에서 먼저 실패해야 합니다.
• Type is the product: public API, RPC contract, Problem code, capability, scope, middleware graph는 문서에만 남기지 않고 소비자가 볼 수 있는 타입과 stable artifact로 드러나야 합니다.
• Explicit over implicit: decorator와 reflection은 편의 계층일 뿐입니다. 최종 controller, provider, event handler, route, manifest, registration table은 검사 가능한 명시적 산출물로 설명되어야 합니다.
• Contracts over conventions alone: route contract, OpenAPI/RPC snapshot, Problem union, public package entrypoint처럼 깨지는 계약은 사람이 눈으로 맞추는 약속보다 자동 검증되는 contract로 관리합니다.
• Failure is a first-class model: 실패는 일반 Error나 silent fallback으로 숨기지 않고 Problem, retry, timeout, circuit breaker, idempotency, exhaustive handling으로 모델링합니다.
• Observable by default: request lifecycle, trace, retry, event, Problem, DI scope, telemetry flush 경계는 운영자가 원인을 추적할 수 있는 evidence를 남겨야 합니다.
• Generated, not hand-wired: client, OpenAPI/RPC spec, manifest, intent map, docs example, registration table 같은 glue code는 수동 동기화보다 생성과 drift gate를 우선합니다.
• Production path first: toy example보다 배포, runtime limitation, compatibility, migration, CI quality gate, zero-credential smoke path를 먼저 설계합니다.
• LLM-readable architecture: 안정적인 에러 코드, source location, manifest, intent map, 타입 기반 문서, deterministic generated output을 선호합니다. 사람과 LLM이 같은 구조를 읽고 같은 수정 지점을 찾을 수 있어야 합니다.
• Composable boundaries: adapter, middleware graph, policy, runtime capability, package layering 경계를 명확히 하며 core package가 provider/runtime 구현체에 오염되지 않게 합니다.

🆚 설계 철학 비교

	Croco	NestJS	Hono	tRPC
주 타겟	AWS Lambda + SaaS 도메인	엔터프라이즈 일반 서버	초경량 엣지/멀티런타임	타입 안전 RPC
아키텍처	5계층 의견있는 구조	모듈 기반 MVC	라우터 중심	스키마리스 RPC
SaaS 빌딩 블록	빌링/메트릭/멤버십/미터링 제공	별도 통합 필요	별도 통합 필요	별도 통합 필요
DDD 이벤트/트랜잭션	기본 내장	별도 통합 필요	❌	❌
Lambda 최적화	✅ lambdaHandler 내장	❌	✅ (별도 어댑터)	❌

위 표는 Croco의 설계 중심을 설명하며, 성능 수치나 경쟁사 부정평가는 포함하지 않습니다.

---

🏗 아키텍처

Croco는 관심사의 분리를 위해 5계층 구조를 따릅니다. 최신 세부 설명은 Architecture Guide를 기준으로 합니다.

flowchart TD
  frameworkContext[framework-context]
  frameworkModule[framework-module]

  frameworkContext --> frameworkModule
  frameworkContext --> protocolsRest[protocols-rest]
  frameworkContext --> protocolsGraphql[protocols-graphql]
  frameworkContext --> protocolsTrpc[protocols-trpc]

  frameworkContext --> transportsHttp[transports-http]
  frameworkContext --> transportsGraphql[transports-graphql]
  frameworkContext --> transportsWorkers[transports-cloudflare-workers]

  protocolsRest --> transportsHttp
  protocolsGraphql --> transportsGraphql
  protocolsTrpc --> transportsHttp
  transportsHttp --> presentation[presentation packages]
  transportsWorkers --> presentation

Loading

graph LR
  subgraph "💰 SaaS Business"
    billing[billing-core] --> metrics[metrics-core]
    membership[membership-core] --> invitation[invitation-core]
    tenant[tenant-core] --> membership
    metering[metering-core] --> billing
    auth[auth-core] --> access[access-core]
    onboarding[onboarding-core]
    entitlements[entitlements-core] --> metering
    entitlements --> billing
    customer-health[customer-health-core] --> metering
    impersonation[impersonation-core] --> auth
  end

Loading

1. framework (기반 계층)

프레임워크의 뿌리가 되는 계층입니다.

• framework-context: 공통 Context 인터페이스, DI 컨테이너, 데코레이터 메타데이터 저장소를 포함합니다.

2. Protocols (정의 계층)

비즈니스 로직의 인터페이스를 정의합니다.

• protocols-rest: @Controller, @Get 등 REST API 정의를 위한 데코레이터를 제공합니다.
• protocols-graphql: Yoga 런타임을 활용한 Code-first GraphQL 정의를 지원합니다.
• protocols-trpc: tRPC 스타일 RPC 계약을 정의하고 타입 안전한 API 표면을 구성할 수 있게 합니다.

3. Transports (실행 계층)

정의된 프로토콜을 실제로 실행하는 어댑터입니다.

• transports-http: Hono 기반의 고성능 실행 엔진입니다. AWS Lambda (API Gateway v2) 핸들러 생성기를 내장하고 있습니다.
• transports-graphql: GraphQL 프로토콜을 실제 런타임에 연결하는 실행 어댑터를 제공합니다.
• transports-cloudflare-workers: Cloudflare Workers 런타임에서 Croco 핸들러를 실행하는 어댑터를 제공합니다.

4. Integrations (통합 계층)

외부 시스템과의 연동을 추상화합니다.

• integrations-posthog: PostHog와 통합되어 제품 분석 이벤트 수집을 지원합니다.

5. Presentation (표현 계층)

백엔드와 프론트엔드/SSR 애플리케이션 표면을 연결합니다.

• frontend-react / frontend-vite / frontend-cloudflare / meta-vite: React, Vite, Cloudflare SSR, server actions, RSC 스트리밍 등 Presentation 계층 통합을 제공합니다.

---

🚀 Quick Start

실행 가능한 SaaS REST API 골든 패스를 빠르게 시작하세요.

첫 번째 프로젝트 생성:

npx create-croco-app@latest my-saas-api --goal saas-api --scope @myorg --no-install --no-git
cd my-saas-api && pnpm install && pnpm demo:smoke

demo:smoke validates the generated REST contracts, in-memory SaaS flow, and operational smoke without external credentials.

Route A (Scaffold): Getting Started Guide에서 scaffold부터 Auth, Metering, Lambda 배포까지 단계별로 SaaS API를 구축하세요.

Route B (Example): Quick Start Example에서 Auth와 Metering이 포함된 완성된 Lambda API를 pnpm dev로 바로 실행하세요.

패키지 성숙도 안내

Croco의 package count, group, maturity metadata는 아래 패키지 카탈로그 섹션에서 자동 생성됩니다. 사용 전 상태를 확인하세요.

• 🟢 production-ready — 안정화, 적극 사용 권장
• 🟡 beta — 기능 완성, 실사용 검증 중
• 🔴 alpha/WIP — 개발 중, 사용 시 주의 필요
• ⚠️ deprecated — 대체 패키지 존재, 마이그레이션 권장

📂 Package Grouping

Croco package grouping은 docs/package-catalog.json의 group metadata와 packages/*/package.json에서 생성됩니다. README의 카탈로그가 drift되면 pnpm docs:catalog:check가 실패합니다.

기여자를 위한 읽기 순서

1. framework-context — DI 컨테이너, 데코레이터 기반
2. problems-core — 에러 처리 패턴
3. protocols-* → transports-* — API 정의 및 실행
4. 도메인 패키지 (*-core) — 비즈니스 로직
5. Provider 패키지 (*-polar, *-clerk 등) — 외부 연동

---

📊 벤치마크 및 성능 측정

Croco는 Lambda 콜드스타트 및 실행 성능을 지속적으로 측정하고 있습니다.

벤치마크는 benchmarks/ 디렉토리에서 관리되며, 다음과 같은 정보를 포함합니다:

• 측정 방법론 및 시나리오 설명
• 최신 기준선(baseline) 및 임계값(threshold) 데이터
• 전용 benchmark workflow에서 최신 5회 green evidence 기반 blocking gate로 동작

자세한 내용은 benchmark-gate-transition.md를 참조하세요.

---

⚡ 주요 기능

도메인 이벤트 (DDD)

Aggregate Root에서 이벤트를 발행하고, 타입 안전한 핸들러에서 이를 처리합니다.

import { DomainEvent, RegisterEventHandler, type EventHandler } from "@croco/events-core";

class OrderPlacedEvent extends DomainEvent {
  static readonly eventName = "order.placed";

  constructor(public readonly orderId: string) {
    super();
  }
}

@RegisterEventHandler(OrderPlacedEvent)
class OrderPlacedHandler implements EventHandler<OrderPlacedEvent> {
  async handle(event: OrderPlacedEvent): Promise<void> {
    // 비즈니스 로직 처리
    console.log(`Order placed: ${event.orderId}`);
  }
}

트랜잭션 관리 (Unit of Work)

데코레이터 하나로 트랜잭션 경계를 설정하고, AsyncLocalStorage를 통해 컨텍스트를 전파합니다.

import { Component } from "@croco/framework-context";
import { Transactional } from "@croco/tx-core";

type CreateOrderDto = {
  orderId: string;
};

@Component()
class OrderService {
  @Transactional()
  async placeOrder(dto: CreateOrderDto): Promise<CreateOrderDto> {
    // 여러 리포지토리가 동일한 트랜잭션 내에서 동작합니다.
    return dto;
  }
}

문제 상세화 (Problem Details)

RFC 7807 표준을 따르는 일관된 에러 응답 형식을 제공합니다.

import { ProblemFactory } from "@croco/problems-core";

throw ProblemFactory.notFound("user/not-found", "사용자를 찾을 수 없습니다.");

실패 처리 기준은 Failure Semantics를 따릅니다. ProblemCategory는 복구 가능성, code는 패키지별 안정 식별자를 나타내며, retry-core는 기본적으로 InternalServerError와 TooManyRequests만 재시도 가능한 실패로 소비합니다.

---

🚀 시작하기

설치

# 모노레포 클론
git clone https://github.com/croco-dev/framework.git
cd framework

# 의존성 설치
pnpm install

# 빌드
pnpm build

빠른 시작 - HTTP API 서버

import { Component } from "@croco/framework-context";
import { Body, Controller, Get, Post } from "@croco/protocols-rest";
import { createApp } from "@croco/transports-http";

@Component()
@Controller("/users")
class UserController {
  @Get("/")
  async list() {
    return [{ id: 1, name: "John" }];
  }

  @Post("/")
  async create(@Body() body: { name: string }) {
    return { id: 2, name: body.name };
  }
}

const app = createApp({
  controllers: [UserController],
});

export const handler = app.lambdaHandler(); // AWS Lambda
// app.listen(3000); // Node.js 서버

핵심 패키지 사용법

1. 의존성 주입 (@croco/framework-context)

import { Component, Container } from "@croco/framework-context";

@Component()
class UserService {
  async getUser(id: string): Promise<{ id: string; name: string }> {
    return { id, name: "John" };
  }
}

// 자동 singleton 등록, 생성자 주입 지원
const service = Container.get(UserService);
void service;

2. 에러 처리 (@croco/problems-core)

import { ProblemFactory } from "@croco/problems-core";

// RFC 7807 Problem 기반 에러
throw ProblemFactory.notFound("user/not-found", "사용자를 찾을 수 없습니다.");

// 자동으로 404 + application/problem+json 응답

3. 재시도 & 서킷브레이커 (@croco/retry-core)

import { Retryable, Recover } from "@croco/retry-core";

type Data = { status: number } | { cached: true };

class ExternalApiService {
  @Retryable({ maxAttempts: 3, backoff: { delay: 100, multiplier: 2 } })
  async fetchData(): Promise<Data> {
    return { status: (await fetch("https://api.example.com/data")).status };
  }

  @Recover()
  async recoverFromFailure(error: Error): Promise<Data> {
    console.warn("All retries failed", error);
    return { cached: true };
  }
}

4. 분산 추적 (@croco/telemetry-api)

import { Trace } from "@croco/telemetry-api";

type CreateOrderDto = {
  orderId: string;
};

class OrderService {
  @Trace({ name: "order.create" })
  async createOrder(dto: CreateOrderDto): Promise<CreateOrderDto> {
    // 자동으로 OpenTelemetry Span 생성
    return dto;
  }
}

🗺️ 로드맵 — 1.0 readiness status

Croco 1.0 readiness는 날짜만 있는 phase 목록이 아니라 checked source와 gate로 추적합니다.

Current 1.0 spine status: 18 spine packages; 10 production-ready, 8 beta, 0 alpha/WIP, 0 deprecated; 8 beta promotion records.

Track	Current status	Checked source / gate
1.0 spine package scope	docs/package-catalog.json의 spine.packages가 release-critical compatibility scope를 정의합니다.	pnpm docs:catalog:check, pnpm spine-promotion:check
First-success path	Quick-start Lambda와 SaaS billing golden path가 public first-success commands로 고정되어 있습니다.	pnpm first-success:verify, pnpm quick-start-lambda:smoke, pnpm saas-billing-golden-path:smoke
Release evidence	Alpha/release smoke, provenance, spine evidence는 release docs와 CI gate에서 확인합니다.	pnpm release-docs:check, pnpm release:spine-evidence
Package maturity	production-ready, beta, alpha/WIP, deprecated 상태는 catalog metadata에서 생성됩니다.	pnpm docs:catalog:check, pnpm production-ready:check

Follow-up work is tracked in GitHub Issues and in Croco 1.0 Spine, with status rendered from checked repository metadata.

---

📦 패키지 카탈로그

이 섹션은 pnpm docs:catalog:write로 생성됩니다. 패키지 이름과 경로는 packages/*/package.json에서 읽고, 그룹/성숙도는 docs/package-catalog.json에서 관리합니다.

현재 카탈로그는 115개 public package를 추적합니다. Private package 2개는 publish 카탈로그에서 제외됩니다. 문서 커버리지 상세는 docs/package-docs-report.md를 확인하세요.

Croco 1.0 Spine

Croco 1.0 spine은 18개 package를 release-critical compatibility scope로 고정합니다. Source of truth는 docs/package-catalog.json의 spine.packages이며, 운영 가이드와 후속 release-gate issue 목록은 Croco 1.0 Spine에 있습니다.

Spine membership is not a maturity claim: production-ready packages already have the strongest evidence gates, beta spine packages are allowed while their 1.0 gates harden, and non-spine beta/alpha packages do not block 1.0 unless they are pulled into a golden path or certified adapter path.

Current 1.0 spine status: 18 spine packages; 10 production-ready, 8 beta, 0 alpha/WIP, 0 deprecated; 8 beta promotion records.

Generated status	Count	Source
Spine packages	18	docs/package-catalog.json spine.packages
Production-ready spine packages	10	maturity.production.packages
Beta spine packages	8	maturity.beta.packages
Alpha/WIP spine packages	0	maturity.alpha.packages
Deprecated spine packages	0	maturity.deprecated.packages
Beta promotion records	8	spine.promotion.packages

Package	Group	Maturity	Directory
@croco/framework-context	Core	🟢 production-ready	packages/framework-context
@croco/problems-core	Core	🟢 production-ready	packages/problems-core
@croco/protocols-core	Protocol	🟡 beta	packages/protocols-core
@croco/protocols-rest	Protocol	🟢 production-ready	packages/protocols-rest
@croco/openapi-spec	Protocol	🟡 beta	packages/openapi-spec
@croco/rpc-codegen	Protocol	🟡 beta	packages/rpc-codegen
@croco/transports-http	Transport	🟢 production-ready	packages/transports-http
@croco/telemetry-api	Integration	🟢 production-ready	packages/telemetry-api
@croco/telemetry-sdk-node	Integration	🟢 production-ready	packages/telemetry-sdk-node
@croco/tx-core	Core	🟢 production-ready	packages/tx-core
@croco/tx-drizzle	Core	🟢 production-ready	packages/tx-drizzle
@croco/events-core	Core	🟢 production-ready	packages/events-core
@croco/events-tx	Core	🟡 beta	packages/events-tx
@croco/retry-core	Core	🟢 production-ready	packages/retry-core
@croco/idempotency-core	Core	🟡 beta	packages/idempotency-core
@croco/testing	Tooling	🟡 beta	packages/testing
create-croco-app	Tooling	🟡 beta	packages/create-croco-app
@croco/cli	Tooling	🟡 beta	packages/cli

Package Groups

그룹	역할	패키지 수
Core	Framework primitives, context, reliability, transactions, and cross-cutting core utilities	24
Domain	Business-domain APIs and package-level abstractions	30
Provider	Concrete datastore, SaaS provider, and external service adapters	27
Integration	Analytics, feature-flag, and observability integrations	5
Protocol	API protocol definitions and code generation	8
Transport	Runtime adapters that execute protocol routes	3
Presentation	Frontend, SSR, and presentation-layer adapters	8
Tooling	CLIs, scaffolds, presets, migration tools, and build-time helpers	10

Maturity Guide

Adapter 경계와 공식 우선순위, compatibility certification checklist는 Adapter Ecosystem에 정의되어 있습니다. 성숙도 승급 기준은 Provider Maturity Gates와 Presentation Runtime Support에 정의되어 있으며, package test 존재 여부만으로 production-ready나 certified compatibility를 의미하지 않습니다. 1.0 spine은 release scope이고, production-ready는 package evidence state이며, certified adapter는 adapter/runtime/contract별 evidence state입니다.

상태	의미	전체 public 패키지 수
🟢 production-ready	안정화, 적극 사용 권장	24
🟡 beta	기능 완성, 실사용 검증 중	76
🔴 alpha/WIP	개발 중, 사용 시 주의 필요	15
⚠️ deprecated	대체 패키지 존재, 마이그레이션 권장	0

Extension & Adapter Matrix

이 섹션은 docs/package-catalog.json의 extensionMatrix metadata에서 생성됩니다. 성숙도와 package test 존재 여부는 별도 열로 표시합니다.

Adapter category definitions, official priorities, package naming rules, minimum compatibility criteria, and the certification checklist live in Adapter Ecosystem. Certification state is rendered from docs/package-catalog.json certification.records and is scoped to package, contract, runtime, package version, and evidence status.

Certification policy: extension packages in Provider, Integration, Transport, Presentation require a certified record when maturity is production or when public docs make a Croco compatibility claim; candidate records require present liveSmoke evidence, and extension packages without those triggers render as not-applicable until candidate evidence is recorded.

Runtime columns: Node는 장기 실행 서버/CLI, Lambda는 서버리스 함수, Workers는 Cloudflare Workers, Frontend는 browser/SSR frontend integration을 의미합니다.

Provider

Package	Domain	Adapter	Node	Lambda	Workers	Frontend	Required env/config	Peer deps	Features	Maturity	Package tests	Certification
@croco/access-drizzle	Access control	Drizzle repository	yes	yes	-	-	database connection supplied by app	drizzle-orm	permission checks policy storage	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/audit-drizzle	Audit	Drizzle repository	yes	yes	-	-	database connection supplied by app	-	audit event persistence tenant audit lookup	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/auth-better-auth	Auth	Better Auth + Drizzle provider	yes	yes	-	-	BETTER_AUTH_URL BETTER_AUTH_SECRET BETTER_AUTH_WEBHOOK_SECRET optional	-	session auth webhooks Drizzle schema shared auth conformance readiness diagnostics optional live smoke	🔴 alpha/WIP	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/auth-clerk	Auth	Clerk Backend provider	yes	yes	-	-	CLERK_SECRET_KEY CLERK_PUBLISHABLE_KEY optional CLERK_WEBHOOK_SECRET optional	-	token auth session management organizations webhooks shared auth conformance readiness diagnostics optional live smoke	🔴 alpha/WIP	has package tests	uncertified (0.0.4) @croco/auth-core/AuthProvider node lambda missing: liveSmoke
@croco/auth-drizzle	Auth	Drizzle store	yes	yes	-	-	database connection supplied by app	drizzle-orm	API key store role registry	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/batch-qstash	Batch	QStash chunk executor	yes	yes	-	-	QSTASH_TOKEN public webhook URL	-	chunk scheduling checkpoint resume idempotent publish shared conformance redacted upstream Problems	🔴 alpha/WIP	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/billing-polar	Billing	Polar billing gateway	yes	yes	-	-	POLAR_ACCESS_TOKEN POLAR_WEBHOOK_SECRET POLAR_ORGANIZATION_ID optional	-	checkout webhooks subscription lifecycle customer portal explicit licensed-quantity unsupported diagnostic	🟡 beta	has package tests	uncertified (0.0.4) @croco/billing-core/BillingGateway node lambda missing: liveSmoke
@croco/credits-drizzle	Credits	Transactional Drizzle credit ledger	yes	yes	-	-	PostgreSQL connection supplied by app	drizzle-orm	atomic credit ledger persistence concurrent overdraft prevention durable idempotency bounded grant expiry deterministic ledger history	🔴 alpha/WIP	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/customer-health-drizzle	Customer health	Drizzle repository	yes	yes	-	-	database connection supplied by app	drizzle-orm	health score persistence customer health lookup	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/entitlements-drizzle	Entitlements	Drizzle repository	yes	yes	-	-	database connection supplied by app	drizzle-orm	entitlement persistence billing entitlement lookup	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/execution-drizzle	Execution	Drizzle execution store	yes	yes	-	-	database connection supplied by app	drizzle-orm	execution state persistence retryable failure records	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/invitation-drizzle	Invitation	Drizzle repository	yes	yes	-	-	database connection supplied by app	-	invitation persistence transaction-aware repository	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/llm-openai	LLM	OpenAI Responses provider	yes	yes	-	-	OPENAI_API_KEY	@croco/llm-core @croco/problems-core @croco/telemetry-api	Responses text generation SSE streaming JSON Schema structured output function tool calls single and batch embeddings usage and telemetry mapping Problem normalization	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/membership-drizzle	Membership	Drizzle repository	yes	yes	-	-	database connection supplied by app	-	membership persistence transaction-aware repository	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/metering-drizzle	Metering	Drizzle usage store	yes	yes	-	-	database connection supplied by app	-	usage persistence quota lookup migration scripts	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/metering-upstash	Metering	Upstash Redis client adapter	yes	yes	-	-	UPSTASH_REDIS_REST_URL UPSTASH_REDIS_REST_TOKEN	-	Redis command adapter serverless usage storage shared conformance redacted upstream Problems	🔴 alpha/WIP	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/metrics-billing	Metrics	Billing metrics bridge	yes	yes	yes	-	none	-	billing event metrics usage aggregation bridge tenant propagation event identity idempotency dropped metric Problems	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/notifications-resend	Notifications	Resend email provider	yes	yes	-	-	RESEND_API_KEY default from address	-	email send rendered template send retry idempotency key safe diagnostics redacted upstream Problems optional live smoke	🔴 alpha/WIP	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/onboarding-drizzle	Onboarding	Drizzle repository	yes	yes	-	-	database connection supplied by app	-	onboarding state persistence step completion storage	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/ratelimit-upstash	Rate limiting	Upstash Redis rate-limit store	yes	yes	-	-	UPSTASH_REDIS_REST_URL UPSTASH_REDIS_REST_TOKEN	@upstash/redis	sliding window token bucket fixed window Lua atomicity shared conformance redacted upstream Problems	🔴 alpha/WIP	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/search-drizzle	Search	Drizzle search index	yes	yes	-	-	database connection supplied by app	drizzle-orm	search document persistence tenant-aware lookup	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/search-meilisearch	Search	Meilisearch engine	yes	yes	-	-	MEILISEARCH_HOST MEILISEARCH_API_KEY	-	indexing search tenant tokens search conformance safe diagnostics env-gated live smoke	🟡 beta	has package tests	uncertified (0.0.4) @croco/search-core/SearchEngine node lambda missing: liveSmoke
@croco/storage-cloudflare	Storage	Cloudflare Images provider	yes	yes	-	-	CLOUDFLARE_ACCOUNT_ID CLOUDFLARE_API_TOKEN CLOUDFLARE_ACCOUNT_HASH	-	image upload transform URLs upload intents signed URLs storage conformance diagnostics optional live smoke	🔴 alpha/WIP	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/storage-cloudinary	Storage	Cloudinary provider	yes	yes	-	-	CLOUDINARY_CLOUD_NAME CLOUDINARY_API_KEY CLOUDINARY_API_SECRET	-	file upload transform URLs upload intents retry storage conformance diagnostics optional live smoke	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/storage-r2	Storage	Cloudflare R2 S3-compatible provider	yes	yes	-	-	R2_ACCOUNT_ID R2_ACCESS_KEY_ID R2_SECRET_ACCESS_KEY R2_BUCKET	-	put/get/delete signed URLs stream reads retry safe diagnostics env-gated live smoke	🟡 beta	has package tests	uncertified (0.0.4) @croco/storage-core/StorageProvider node lambda missing: liveSmoke
@croco/tasks-qstash	Tasks	QStash task runner	yes	yes	-	-	UPSTASH_QSTASH_TOKEN UPSTASH_QSTASH_DESTINATION_URL	-	task publish delay override custom headers deduplication id shared conformance redacted upstream Problems	🔴 alpha/WIP	has package tests	uncertified (0.0.4) @croco/tasks-core/TaskRunner node lambda missing: liveSmoke
@croco/triggers-qstash	Triggers	QStash scheduler and webhook handler	yes	yes	-	-	QSTASH_TOKEN public webhook URL	-	schedule publish webhook verification trigger dispatch shared conformance redacted schedule diagnostics diagnostic-coded webhook failures	🔴 alpha/WIP	has package tests	not-applicable not required until production-ready or compatibility claim

Integration

Package	Domain	Adapter	Node	Lambda	Workers	Frontend	Required env/config	Peer deps	Features	Maturity	Package tests	Certification
@croco/analytics-posthog	Analytics	PostHog analytics provider	yes	yes	-	-	POSTHOG_API_KEY POSTHOG_HOST optional	-	event capture user/group analytics flush lifecycle disabled-mode skip evidence safe readiness diagnostics	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/features-posthog	Feature flags	PostHog feature provider	yes	yes	-	-	POSTHOG_API_KEY POSTHOG_HOST optional	-	feature flag lookup PostHog client reuse	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/integrations-posthog	PostHog	Shared PostHog client	yes	yes	-	-	POSTHOG_API_KEY POSTHOG_HOST optional	-	client lifecycle capture flush diagnostics	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/telemetry-api	Telemetry	OpenTelemetry application API	yes	yes	yes	yes	none	-	Trace decorator withSpan recordError trace context lookup browser RPC correlation bridge	🟢 production-ready	has package tests	certified (0.1.0) @croco/telemetry-api/Trace node lambda cloudflare-workers browser evidence complete
@croco/telemetry-sdk-node	Telemetry	OpenTelemetry Node SDK runtime	yes	yes	-	-	OTEL_EXPORTER_OTLP_TRACES_ENDPOINT or OTEL_EXPORTER_OTLP_ENDPOINT TELEMETRY_ENABLED optional	-	SDK init Lambda preset OTLP export forceFlush	🟢 production-ready	has package tests	certified (0.0.4) @croco/telemetry-sdk-node/TelemetryRuntime node lambda evidence complete

Transport

Package	Domain	Adapter	Node	Lambda	Workers	Frontend	Required env/config	Peer deps	Features	Maturity	Package tests	Certification
@croco/transports-graphql	GraphQL transport	GraphQL Yoga transport	yes	yes	-	-	none	-	GraphQL server resolver execution Problem mapping	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/transports-cloudflare-workers	HTTP transport	Cloudflare Workers adapter	-	-	yes	-	Cloudflare Worker env object supplied by platform	-	Worker fetch adapter request context bridge	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/transports-http	HTTP transport	Hono HTTP/Lambda transport	yes	yes	-	-	CROCO_DIAGNOSTICS_TOKEN optional CROCO_HTTP_DI_VALIDATION optional CROCO_HTTP_SECURITY_VALIDATION optional	-	REST route execution Lambda adapter operational endpoints diagnostics	🟢 production-ready	has package tests	certified (0.0.4) @croco/transports-http/HttpTransport node lambda evidence complete

Presentation

Package	Domain	Adapter	Node	Lambda	Workers	Frontend	Required env/config	Peer deps	Features	Maturity	Package tests	Certification
@croco/admin-react	Admin React	Tenant and cross-domain business workspace primitives	yes	-	-	yes	none	react react-dom	billing panel contract contract-aware DataTable entitlement status primitives pagination and search adapters usage quota meters provider failure state tenant switcher impersonation banner permission inspector append-only credit operations ledger allocation and reservation evidence audited grant, refund, release, and adjustment controls Tenant 360 source workspace partial-source state and refresh permission-aware action launcher structural extension slots Problem-preserving console failures	🔴 alpha/WIP	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/ui-astryx	Astryx UI	Croco-aware Astryx React presentation adapter	yes	-	-	yes	none	react react-dom	Astryx neutral theme provider application shell Problem recovery display auth and session states prebuilt StyleX CSS consumer path generated Vite SPA smoke	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/frontend-problems	Frontend Problems	Problem-aware client runtime	-	-	yes	yes	none	-	Problem Details parsing Problem-aware fetch results declared Problem unions form Problem mapping	🔴 alpha/WIP	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/frontend-react	Frontend React	React integration helpers	yes	-	-	yes	none	@croco/meta-vite react react-dom	React bindings meta-vite integration browser hydration smoke page data hydration flow generated meta-vite fullstack smoke auth gate primitives tenant and entitlement bridge	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/meta-vite	Frontend routing	Meta Vite runtime	yes	yes	yes	yes	optional Redis-compatible ISR adapter config Worker-safe IsrCacheStore required for durable Workers ISR	ioredis react react-dom vite zod	route registry server actions SSR/RSC streaming ISR v1 exact-key TTL Node/Lambda durable ISR smoke Workers ISR boundary smoke generated page/API/action/ISR smoke	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/frontend-cloudflare	Frontend SSR	Cloudflare SSR handler	-	-	yes	-	API_WORKER binding optional ASSETS binding optional	-	Worker SSR request handling service binding API routing ASSETS fallback streaming Response preservation RuntimeContext env propagation generated Worker smoke	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/frontend-vite	Frontend Vite	Vite integration helpers	yes	-	yes	yes	none	@cloudflare/vite-plugin vite	Vite config helpers Cloudflare Vite compatibility optional Cloudflare peer diagnostics SPA browser build smoke meta-vite generated build smoke	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim
@croco/presentation-preset	Presentation preset	Backend/frontend preset composition	yes	yes	yes	yes	none	-	preset composition contract wiring generated app support output contract validation	🟡 beta	has package tests	not-applicable not required until production-ready or compatibility claim

🟢 production-ready

패키지	그룹	디렉터리	문서
@croco/dataloader-core	Core	packages/dataloader-core	README, API, tests
@croco/events-core	Core	packages/events-core	README, API, tests
@croco/framework-context	Core	packages/framework-context	README, API, tests
@croco/problems-core	Core	packages/problems-core	README, API, tests
@croco/repository-core	Core	packages/repository-core	README, API, tests
@croco/retry-core	Core	packages/retry-core	README, API, tests
@croco/tx-core	Core	packages/tx-core	README, API, tests
@croco/tx-drizzle	Core	packages/tx-drizzle	README, API, tests
@croco/audit-core	Domain	packages/audit-core	README, API, tests
@croco/auth-core	Domain	packages/auth-core	README, API, tests
@croco/billing-core	Domain	packages/billing-core	README, API, tests
@croco/invitation-core	Domain	packages/invitation-core	README, API, tests
@croco/llm-core	Domain	packages/llm-core	README, API, tests
@croco/llm-metering	Domain	packages/llm-metering	README, API, tests
@croco/membership-core	Domain	packages/membership-core	README, API, tests
@croco/metering-core	Domain	packages/metering-core	README, API, tests
@croco/metrics-core	Domain	packages/metrics-core	README, API, tests
@croco/ratelimit-core	Domain	packages/ratelimit-core	README, API, tests
@croco/search-core	Domain	packages/search-core	README, API, tests
@croco/telemetry-api	Integration	packages/telemetry-api	README, API, tests
@croco/telemetry-sdk-node	Integration	packages/telemetry-sdk-node	README, API, tests
@croco/protocols-rest	Protocol	packages/protocols-rest	README, API, tests
@croco/migration-runner	Tooling	packages/migration-runner	README, API, tests
@croco/transports-http	Transport	packages/transports-http	README, API, tests

🟡 beta

패키지	그룹	디렉터리	문서
@croco/cache-core	Core	packages/cache-core	README, API, tests
@croco/diagnostics-core	Core	packages/diagnostics-core	README, API, tests
@croco/events-inmemory	Core	packages/events-inmemory	README, API, tests
@croco/events-tx	Core	packages/events-tx	README, API, tests
@croco/framework-config	Core	packages/framework-config	README, API, tests
@croco/framework-logger	Core	packages/framework-logger	README, API, tests
@croco/framework-module	Core	packages/framework-module	README, API, tests
@croco/framework-preset	Core	packages/framework-preset	README, API, tests
@croco/framework-routes	Core	packages/framework-routes	README, API, tests
@croco/gid-core	Core	packages/gid-core	README, API, tests
@croco/health-core	Core	packages/health-core	README, API, tests
@croco/idempotency-core	Core	packages/idempotency-core	README, API, tests
@croco/outbox-core	Core	packages/outbox-core	README, API, tests
@croco/pagination-core	Core	packages/pagination-core	README, API, tests
@croco/tenant-core	Core	packages/tenant-core	README, API, tests
@croco/webhooks-core	Core	packages/webhooks-core	README, API, tests
@croco/access-core	Domain	packages/access-core	README, API, tests
@croco/admin-core	Domain	packages/admin-core	README, API, tests
@croco/admin-ops	Domain	packages/admin-ops	README, API, tests
@croco/analytics-core	Domain	packages/analytics-core	README, API, tests
@croco/batch-core	Domain	packages/batch-core	README, API, tests
@croco/customer-health-core	Domain	packages/customer-health-core	README, API, tests
@croco/entitlements-core	Domain	packages/entitlements-core	README, API, tests
@croco/execution-core	Domain	packages/execution-core	README, API, tests
@croco/features-core	Domain	packages/features-core	README, API, tests
@croco/governance-core	Domain	packages/governance-core	README, API, tests
@croco/impersonation-core	Domain	packages/impersonation-core	README, API, tests
@croco/lifecycle-core	Domain	packages/lifecycle-core	README, API, tests
@croco/notifications-core	Domain	packages/notifications-core	README, API, tests
@croco/onboarding-core	Domain	packages/onboarding-core	README, API, tests
@croco/storage-core	Domain	packages/storage-core	README, API, tests
@croco/tasks-core	Domain	packages/tasks-core	README, API, tests
@croco/triggers-core	Domain	packages/triggers-core	README, API, tests
@croco/workflow-core	Domain	packages/workflow-core	README, API, tests
@croco/analytics-posthog	Integration	packages/analytics-posthog	README, API, tests
@croco/features-posthog	Integration	packages/features-posthog	README, API, tests
@croco/integrations-posthog	Integration	packages/integrations-posthog	README, API, tests
@croco/frontend-cloudflare	Presentation	packages/frontend-cloudflare	README, API, tests
@croco/frontend-react	Presentation	packages/frontend-react	README, API, tests
@croco/frontend-vite	Presentation	packages/frontend-vite	README, API, tests
@croco/meta-vite	Presentation	packages/meta-vite	README, API, tests
@croco/presentation-preset	Presentation	packages/presentation-preset	README, API, tests
@croco/ui-astryx	Presentation	packages/ui-astryx	README, API, tests
@croco/openapi-spec	Protocol	packages/openapi-spec	README, API, tests
@croco/protocols-core	Protocol	packages/protocols-core	README, API, tests
@croco/protocols-graphql	Protocol	packages/protocols-graphql	README, API, tests
@croco/protocols-trpc	Protocol	packages/protocols-trpc	README, API, tests
@croco/rpc-codegen	Protocol	packages/rpc-codegen	README, API, tests
@croco/access-drizzle	Provider	packages/access-drizzle	README, API, tests
@croco/audit-drizzle	Provider	packages/audit-drizzle	README, API, tests
@croco/auth-drizzle	Provider	packages/auth-drizzle	README, API, tests
@croco/billing-polar	Provider	packages/billing-polar	README, API, tests
@croco/customer-health-drizzle	Provider	packages/customer-health-drizzle	README, API, tests
@croco/entitlements-drizzle	Provider	packages/entitlements-drizzle	README, API, tests
@croco/execution-drizzle	Provider	packages/execution-drizzle	README, API, tests
@croco/invitation-drizzle	Provider	packages/invitation-drizzle	README, API, tests
@croco/llm-openai	Provider	packages/llm-openai	README, API, tests
@croco/membership-drizzle	Provider	packages/membership-drizzle	README, API, tests
@croco/metering-drizzle	Provider	packages/metering-drizzle	README, API, tests
@croco/metrics-billing	Provider	packages/metrics-billing	README, API, tests
@croco/onboarding-drizzle	Provider	packages/onboarding-drizzle	README, API, tests
@croco/search-drizzle	Provider	packages/search-drizzle	README, API, tests
@croco/search-meilisearch	Provider	packages/search-meilisearch	README, API, tests
@croco/storage-cloudinary	Provider	packages/storage-cloudinary	README, API, tests
@croco/storage-r2	Provider	packages/storage-r2	README, API, tests
@croco/architecture-policy	Tooling	packages/architecture-policy	README, API, tests
@croco/cli	Tooling	packages/cli	README, API, tests
create-croco-app	Tooling	packages/create-croco-app	README, API, tests
@croco/esbuild-plugin	Tooling	packages/esbuild-plugin	README, API, tests
@croco/preset-cloudflare	Tooling	packages/preset-cloudflare	README, API, tests
@croco/preset-lambda	Tooling	packages/preset-lambda	README, API, tests
@croco/preset-node	Tooling	packages/preset-node	README, API, tests
@croco/testing	Tooling	packages/testing	README, API, tests
@croco/testing-resources	Tooling	packages/testing-resources	README, API, tests
@croco/transports-cloudflare-workers	Transport	packages/transports-cloudflare-workers	README, API, tests
@croco/transports-graphql	Transport	packages/transports-graphql	README, API, tests

🔴 alpha/WIP

패키지	그룹	디렉터리	문서
@croco/credits-core	Domain	packages/credits-core	README, API, tests
@croco/admin-react	Presentation	packages/admin-react	README, API, tests
@croco/frontend-problems	Presentation	packages/frontend-problems	README, API, tests
@croco/admin-generated	Protocol	packages/admin-generated	README, API, tests
@croco/protocols-desktop	Protocol	packages/protocols-desktop	README, API, tests
@croco/auth-better-auth	Provider	packages/auth-better-auth	README, API, tests
@croco/auth-clerk	Provider	packages/auth-clerk	README, API, tests
@croco/batch-qstash	Provider	packages/batch-qstash	README, API, tests
@croco/credits-drizzle	Provider	packages/credits-drizzle	README, API, tests
@croco/metering-upstash	Provider	packages/metering-upstash	README, API, tests
@croco/notifications-resend	Provider	packages/notifications-resend	README, API, tests
@croco/ratelimit-upstash	Provider	packages/ratelimit-upstash	README, API, tests
@croco/storage-cloudflare	Provider	packages/storage-cloudflare	README, API, tests
@croco/tasks-qstash	Provider	packages/tasks-qstash	README, API, tests
@croco/triggers-qstash	Provider	packages/triggers-qstash	README, API, tests

Documentation Gate

• pnpm docs:catalog:check는 README 카탈로그, extension matrix reference 문서, 문서 커버리지 리포트 drift를 검증합니다.
• 신규 public package는 docs/package-catalog.json에 그룹/성숙도 metadata가 있어야 합니다.
• 신규 public package의 README, API docs, tests 누락은 docs/package-docs-baseline.json에 없는 한 실패합니다.
• production-ready package의 API docs 누락은 legacy baseline으로 숨길 수 없고, 생성하거나 짧은 사유가 있는 temporaryProductionApiDocExceptions에만 임시로 둘 수 있습니다.

---

🛠 개발 환경

코드 품질 도구

• Oxlint / Oxfmt: root quality gate와 pre-commit hook에서 lint와 format을 확인합니다.
• TypeScript: 엄격 모드 + 데코레이터 지원
• Vitest / Turbo: package test와 repo-wide task orchestration을 담당합니다.
• Catalog / release drift gates: README package catalog, first-success docs, release docs, package manifests, public API, static misuse를 checked scripts로 검증합니다.

주요 명령어

pnpm install          # 의존성 설치
pnpm build            # turbo build
pnpm lint             # turbo lint
pnpm format           # oxfmt write
pnpm check            # repository policy, docs/catalog/release drift, lint, format, static gates
pnpm docs:catalog:check      # README package catalog and package docs drift
pnpm first-success:verify    # README, getting-started, examples, and first-success command drift
pnpm release-docs:check      # release guide and Changesets config drift
pnpm release:spine-evidence  # consolidated release spine evidence gate
pnpm test             # 테스트 실행
pnpm typecheck        # TypeScript 타입 검사

Git Hooks (Lefthook)

• Pre-commit: oxlint/oxfmt 자동 수정
• Pre-push: auto-changeset, 테스트, 타입 검사

---

🚢 배포 전략

Croco는 AWS Lambda를 최우선으로 고려합니다.

• Fast Startup: 불필요한 의존성을 배제하고 트리쉐이킹에 최적화된 빌드를 제공합니다.
• API Gateway v2 Support: 고성능 HTTP API를 위한 어댑터를 기본 제공합니다.
• pnpm + Turbo: 고성능 빌드 파이프라인을 통해 배포 속도를 극대화합니다.

pnpm run deploy -- --otp <otp>

---

🤝 기여하기

기여 방법, 개발 환경 설정, 코드 스타일, Git 워크플로우는 CONTRIBUTING.md를 참고하세요.

---

📄 라이선스

MIT License. Copyright (c) 2026 Croco Team.