Monorepo Architecture (Turborepo)
Relevant source files
The following files were used as context for generating this wiki page:
KudosWall is built as a high-performance monorepo SaaS application utilizing Turborepo (v2.9) to manage its decoupled workspace layers. The architecture is designed to provide a fully type-safe stack, spanning from database columns via Drizzle ORM to tRPC API procedures and React Server Components (RSC) in the Next.js 16 frontend.
Sources: README.md:16, README.md:32, AGENTS.md:5-7
Workspace Structure
The repository is organized into apps and packages, ensuring a clean separation of concerns and clear dependency boundaries.
Core Applications and Packages
| Directory | Type | Description |
|---|---|---|
apps/web | App | Next.js 16 application handling the dashboard, marketing, and edge proxies. |
packages/api | Package | tRPC v11 routers, input validators (Zod), and business logic. |
packages/db | Package | Drizzle ORM schemas, migrations, and Neon PostgreSQL client. |
packages/ui | Package | Shared design system based on Shadcn/ui and Tailwind CSS v4. |
packages/auth | Package | Better-Auth configuration and session management utilities. |
packages/env | Package | Zod-validated environment variable management. |
packages/stripe | Package | Stripe billing integration and subscription lifecycle logic. |
Sources: README.md:83-93, AGENTS.md:104-110
Dependency Flow
The monorepo enforces strict unidirectional dependency rules:
- Packages must never import from
apps. - Higher-level packages (e.g.,
api) can import from lower-level utility packages (db,env). - Internal package imports use the
@my-better-t-app/*scope withworkspace:*versioning.
Sources: AGENTS.md:31-35
The diagram above illustrates the clean, decoupled workspace layer governed by Turborepo.
Sources: README.md:41-65
Development Workflow and Standards
The architecture leverages Bun (v1.3+) for execution and script management. Automated git hooks via Lefthook ensure that code quality standards are met before commits.
Key Development Scripts
- Format:
bun run format(Prettier with Tailwind CSS plugin). - Type Check:
bun run check-types(Strict TypeScript compiler). - Build:
bun run build(Turborepo pipeline for edge bundles). - Database:
bun run db:push(Drizzle schema sync).
Sources: AGENTS.md:11-15, README.md:183-195
Feature Implementation Pipeline
Implementing a new feature follows a structured flow across the monorepo:
- Schema: Update
packages/db/src/schema/app.ts. - API: Define tRPC procedures in
packages/api/src/router. - UI: Build reusable primitives in
packages/ui. - Logic: Implement the page in
apps/webusing API callers.
Sources: AGENTS.md:113-118
Integration and Third-Party Services
KudosWall integrates with various edge-compatible and serverless services to maintain performance.
Service Providers
| Service | Purpose | Implementation Location |
|---|---|---|
| Neon | PostgreSQL Database | packages/db |
| Cloudflare R2 | Media Storage | apps/web/src/proxy.ts |
| Loops.so | Marketing Emails | packages/email/src/loops.ts |
| Better-Auth | Authentication | packages/auth |
| Resend | Transactional Email | packages/email |
Sources: README.md:106-121, loops-email-collection.md:27-38
Loops.so Sync Integration
The monorepo implements real-time event syncing to Loops.so for automated campaigns.
This diagram shows how events are dispatched from different workspace layers to the marketing service.
Sources: loops-email-collection.md:43-55
SEO and Performance Architecture
Performance is optimized using Next.js 16 features and Turborepo build caching.
Edge Proxy and Metadata
KudosWall uses src/proxy.ts instead of standard middleware for stable edge execution on Cloudflare. For public "Wall of Love" pages, the system utilizes unstable_cache for project data and generates structured JSON-LD (Product and Review schemas) to enhance search visibility.
Sources: AGENTS.md:82-84, apps/web/src/app/wall/[slug]/page.tsx:64-70, apps/web/src/app/wall/[slug]/page.tsx:112-140
Technical Standards
- Type Safety: Strict
no-anyrule; use ofunknownand Zod for runtime validation. - Data Fetching: Preference for fetching in Server Components via tRPC callers or direct DB access.
- Naming:
snake_casefor database columns andcamelCasefor TypeScript fields.
Sources: AGENTS.md:21-27, AGENTS.md:43-46, AGENTS.md:58-60
Conclusion
The monorepo architecture of KudosWall, powered by Turborepo, provides a robust foundation for scaling a SaaS product. By strictly separating concerns into specialized packages and enforcing type-safety across the entire stack, the project ensures high performance and maintainability.