Getting Started & Local Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• AGENTS.md
• apps/web/src/app/wall/[slug]/page.tsx
• apps/web/src/app/(marketing)/dpa/page.tsx/dpa/page.tsx)
• SECURITY.md
• apps/web/src/lib/ai/prompts.ts

KudosWall is an elite, high-performance monorepo SaaS application designed for collecting, managing, and embedding customer testimonials. It is built on a type-safe stack featuring Next.js 16, Turborepo, Bun, and Drizzle ORM. This guide outlines the architectural requirements and steps necessary to initialize the development environment and launch the local server.

The system bridges the gap between raw web speed and enterprise reliability by leveraging edge-compatible proxies, serverless PostgreSQL connection pooling, and HMAC-signed media delivery.

Sources: README.md:1-24, AGENTS.md:112-118

System Architecture

KudosWall uses a decoupled workspace layer managed by Turborepo. This structure ensures that business logic, database schemas, and UI components are isolated into specific packages, maintaining a unidirectional dependency flow.

Dependency Mapping

The following diagram illustrates the relationship between the main application and its supporting packages.

Infrastructure Stack

The application relies on several third-party sub-processors for cloud hosting, data storage, and transactional services.

Component	Provider	Purpose
Hosting	Vercel	Cloud Hosting & Edge Functions
Database	Neon	Serverless PostgreSQL Hosting
Storage	Cloudflare R2	HMAC-signed Video Asset Storage
Authentication	Better-Auth	Secure sessions and OAuth
Email	Resend	Transactional system emails
Rate Limiting	Upstash	Redis-based rate limiting

Sources: README.md:12-24, apps/web/src/app/(marketing)/dpa/page.tsx:112-138, SECURITY.md:27-35

Local Development Setup

Prerequisites

The project requires Bun v1.3.0 or higher as the primary runtime and package manager.

Sources: README.md:95-97

Installation & Configuration

1. Clone and Install:

   bun install
   

2. Environment Variables: Create a .env file in the root directory. All variables are strictly validated at compilation time using Zod via @my-better-t-app/env.

Variable	Required	Purpose
DATABASE_URL	Yes	Neon serverless PostgreSQL connection string
BETTER_AUTH_SECRET	Yes	Encryption token for Better-Auth sessions
R2_SIGNING_SECRET	Yes	HMAC-SHA256 seed for signed media URLs
STRIPE_SECRET_KEY	Yes	Backend Stripe API key
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY	Yes	Client-side Stripe SDK key

Sources: README.md:100-128, AGENTS.md:103-107

Database Initialization

KudosWall uses Drizzle ORM to manage database structures. Developers must push the schema and generate migrations before starting the server.

To initialize the database for the first time or after schema changes:

• Push Schema: bun run db:push pushes changes directly to the database instance.
• Generate Migrations: bun run db:generate creates SQL migration scripts.
• Run Migrations: bun run db:migrate executes pending scripts.
• Drizzle Studio: bun run db:studio launches a visual database explorer.

Sources: README.md:130-147, AGENTS.md:124-125

Development Workflow

Launching the Server

Once configured, start the Turborepo development tasks:

bun run dev

The main web dashboard launches at http://localhost:3000.

Sources: README.md:149-155

Code Quality Standards

Before committing changes, the following scripts ensure adherence to project standards:

• Formatting: bun run format (Uses Prettier with Tailwind CSS integration).
• Type Checking: bun run check-types (Strict TypeScript compiler checking).
• Build Verification: bun run build (Compiles edge bundles).
• Testing: bun run test:e2e (Launches Playwright E2E browser tests).

Sources: README.md:179-186, AGENTS.md:5-10

Feature Implementation Sequence

When adding new functionality, follow the established unidirectional flow:

1. Schema: Update packages/db/src/schema/app.ts and run bun run db:push.
2. API: Define tRPC procedures in packages/api/src/router.
3. UI: Create reusable components in packages/ui.
4. App Logic: Implement the page in apps/web using the created API and UI components.

Sources: AGENTS.md:123-128

Media & Request Flow

The application uses an Edge Proxy (src/proxy.ts) instead of standard Next.js middleware to ensure stable execution on Cloudflare. This is critical for media signing and request routing.

KudosWall's local setup is designed to mirror its production "Privacy by Design" architecture, utilizing anonymized hashing for tracking and AES-256 encryption for data at rest. This ensures that the development environment maintains the same security rigor as the live platform.

Sources: apps/web/src/app/(marketing)/dpa/page.tsx:64-83, SECURITY.md:27-35