Welcome to KudosWall
Relevant source files
The following files were used as context for generating this wiki page:
KudosWall is an elite, high-performance monorepo SaaS application designed for collecting, managing, and embedding customer testimonials, including both text and video formats. Built on a fully type-safe stack, it leverages edge-compatible Next.js 16 proxies, serverless PostgreSQL connection pooling, and HMAC-signed media delivery to provide enterprise-grade reliability and speed.
The platform is architected to bridge the gap between raw web performance and robust social proof management. Key features include interactive testimonial forms, white-labeled campaigns, keyboard-driven triage for inbox management, and secure media delivery via Cloudflare R2 CDN.
Sources: README.md:1-25, AGENTS.md:73-82
System Architecture
KudosWall utilizes a decoupled Turborepo workspace architecture to separate concerns across applications and shared packages. The core application logic resides in apps/web, while business logic, database schemas, and UI components are distributed across specialized packages.
Monorepo Structure
| Package/App | Purpose |
|---|---|
apps/web | Next.js 16 Client, Dashboard, and Edge Proxy. |
packages/api | tRPC v11 routers, input validators, and business logic. |
packages/auth | Better-Auth session client and security configuration. |
packages/db | Drizzle ORM schemas and Postgres client definitions. |
packages/ui | Shared design system using Tailwind CSS v4 and Shadcn components. |
packages/env | Zod-validated environment variable configuration. |
packages/stripe | Billing integration and subscription lifecycle logic. |
Sources: README.md:43-70, AGENTS.md:73-82
Dependency Mapping
The following diagram illustrates the decoupled relationships between the monorepo's components:
The dependency graph shows how the web application consumes shared logic and UI packages while maintaining strict separation of concerns.
Sources: README.md:43-62
Core Technical Features
Edge Request Proxy & Media Delivery
KudosWall utilizes an Edge Proxy (src/proxy.ts) to handle zero-latency requests. Media assets, specifically video testimonials, are served through a secure sequence involving HMAC-SHA256 tokens and Cloudflare R2 storage.
The sequence diagram demonstrates the flow of media signing and delivery based on workspace subscription levels.
Sources: README.md:27-41, AGENTS.md:65-67
AI Intelligence Engine
The platform incorporates an advanced AI library for content analysis, sentiment detection, and automated marketing content generation. It utilizes ai-sdk-core and Zod-validated schemas to ensure structured outputs.
| AI Capability | Description |
|---|---|
| Sentiment Analysis | Detects positive, neutral, or negative tones in testimonials. |
| Enthusiasm Scoring | Provides a 1-10 scale for sorting by passion. |
| Hero Quote Extraction | Automatically generates high-impact snippets for marketing. |
| Spam/Abuse Detection | Filters out bots, crypto-spam, and toxic content. |
| Transcript Cleanup | Removes disfluencies (um, uh) from video transcripts. |
Sources: apps/web/src/lib/ai/prompts.ts:10-75
Development Standards
Type Safety & Validation
KudosWall enforces strict end-to-end type safety. Runtime validation is handled primarily by Zod, which is used for API inputs, database schemas, and environment variable loading.
// Example of Zod-validated AI analysis schema
export const analysisSchema = z.object({
sentiment: z.enum(["positive", "neutral", "negative"]),
enthusiasm_score: z.number().min(1).max(10),
themes: z.array(z.string()),
is_mismatch: z.boolean().describe("True if stars/rating does not match the text"),
summary: z.string().max(100),
});
Sources: apps/web/src/lib/ai/prompts.ts:47-57, AGENTS.md:12-18
Security Architecture
Security is integrated at the architectural level through parameterized queries (Drizzle ORM), secure session management (Better-Auth), and strict Content Security Policies (CSP).
- Authentication: Supports secure sessions, MFA, and OAuth (Google/GitHub/LinkedIn).
- Data Protection: Parameterized queries prevent SQL injection.
- Disclosure: Follows a 90-day coordinated disclosure policy for vulnerabilities.
Sources: SECURITY.md:29-41, README.md:105-120
Getting Started for Developers
Prerequisites and Installation
Developers are required to use Bun v1.3.0 or higher.
- Install dependencies:
bun install - Environment Setup: Configure
.envwithDATABASE_URL,BETTER_AUTH_SECRET, andSTRIPE_SECRET_KEY. - Database Initialisation:
- Push schema:
bun run db:push - Run migrations:
bun run db:migrate
- Push schema:
- Start Dev Server:
bun run dev
Sources: README.md:72-103, AGENTS.md:5-9
KudosWall provides a robust foundation for building social proof engines, prioritizing developer experience through its monorepo structure and high-performance edge-first architecture.