Hackathon Monorepo

Consent Flow Legal Risk Analysis monorepo built with Bun, Turborepo, Next.js, Effect, T3 Env, Drizzle, and shared workspace packages.

Requirements

• Bun 1.3.11 or newer
• Node.js 18 or newer

Getting Started

Install dependencies:

bun install

Link the Vercel project and pull development envs:

vercel link
vercel env pull apps/web/.env.local

Run the app locally:

bun run dev

Run the main quality checks:

bun run check
bun run test

Apply formatting and autofixes:

bun run fix

Available Scripts

• bun run dev runs turbo run dev
• bun run build runs turbo run build
• bun run db:generate generates Drizzle SQL migrations in packages/db/drizzle
• bun run db:migrate applies committed Drizzle migrations
• bun run lint runs turbo run lint
• bun run check-types runs turbo run check-types
• bun run check runs Ultracite checks
• bun run fix formats and applies safe fixes with Ultracite
• bun run test runs Bun tests and succeeds when the repo has no tests yet

Workspace Layout

• apps/web contains the Next.js app
• packages/env contains the shared T3 Env validation contract
• packages/ai owns the Vercel AI SDK analyzer boundary
• packages/cache owns Upstash Redis runtime config and cache helpers
• packages/db owns PlanetScale Postgres schema, migrations, and scan persistence
• packages/storage owns Vercel Blob runtime config and artifact helpers
• packages/kernel-app owns Kernel runtime config and browser integration boundary
• packages/observability owns evlog runtime config and server logging helpers
• packages/workflows owns scan orchestration
• packages/typescript-config contains shared TypeScript base configs

Vercel Environment Setup

Vercel is the source of truth for secrets and runtime configuration. Do not hand-maintain committed env files. The checked-in .env.example is documentation only.

Required services

• PlanetScale
• Upstash Redis
• Vercel Blob
• Kernel
• Vercel AI Gateway

Required Vercel env vars

Only app-managed secrets and service endpoints belong in the env contract. Model selection, logging presentation, and Kernel behavior defaults are owned by code.

Database

• DATABASE_URL

Kernel

• KERNEL_API_KEY

Vercel AI Gateway

• AI_GATEWAY_API_KEY

Upstash Redis

• KV_REST_API_URL
• KV_REST_API_TOKEN

Vercel Blob

• BLOB_READ_WRITE_TOKEN

Operator workflow

1. Run vercel link in the repo root.
2. Add the env vars above in the Vercel project for Development, Preview, and Production.
3. Keep Production complete first, then mirror the same secret names into Preview and Development with environment-appropriate values.
4. Pull local development envs with vercel env pull apps/web/.env.local.
5. Start local development with bun run dev.

Environment placement guidance

Development

• use low-risk development credentials
• use a development PlanetScale database or branch
• use a development Upstash database
• use a development Blob token if separated

Preview

• use preview-safe credentials
• keep the same env names as production
• use isolated preview services where practical

Production

• use production-only credentials
• use the production PlanetScale database
• use the production Upstash database
• use the production Blob token

Shared Env Contract

The typed runtime env contract lives in @cflra/env.

It exports:

• serverEnv
• publicEnv
• serverEnvSchema
• publicEnvSchema

Service packages consume only the env fields they own:

• @cflra/ai reads the Vercel AI Gateway key and owns the hard-coded model selection
• @cflra/kernel reads Kernel configuration
• @cflra/cache reads Upstash Redis configuration
• @cflra/storage reads Blob configuration
• @cflra/db reads PlanetScale configuration
• @cflra/db uses Drizzle ORM with committed SQL migrations
• @cflra/observability uses code-owned logging defaults
• @cflra/workflows composes the services and calls the analyzer boundary

Runtime Defaults

• The app derives its public base URL from request headers or VERCEL_URL when needed.
• The AI model is hard-coded to google/gemini-2.5-pro in @cflra/ai.
• Kernel environment mode is derived from NODE_ENV.
• evlog formatting defaults are code-owned: pretty logs in development and structured logs in production.

Git Hooks

The pre-commit hook formats staged files with Ultracite and runs the test command. In a fresh repo with no tests, the test step still passes.

Next Steps

1. Add an app under apps/
2. Add shared packages under packages/
3. Define build, lint, check-types, and test scripts in each workspace that needs them