tRPC API Implementation
Relevant source files
The following files were used as context for generating this wiki page:
The tRPC API implementation in KudosWall provides a type-safe communication layer between the client application and the server-side business logic. It serves as the backbone for data fetching and mutations, ensuring end-to-end type safety from database columns through server routers down to the UI client.
This implementation is centralized within the packages/api workspace and consumed by the apps/web application. It leverages zod for runtime validation of inputs and Better-Auth for secure session management within its procedures.
Sources: README.md:14-18, AGENTS.md:31-37, README.md:65-75
Architecture and Monorepo Structure
The API is structured as a standalone package within a Turborepo monorepo. It follows a unidirectional data flow where the api package can import from lower-level packages like db (Drizzle ORM) and env (environment variables), but cannot import from high-level applications like apps/web.
The diagram shows the dependency flow where the Web app consumes the API, which in turn depends on the Database and Environment packages.
Sources: README.md:65-75, AGENTS.md:25-30
Core Components
The tRPC implementation consists of three primary layers: Context creation, Router definition, and the HTTP handler.
API Context
The context is created for every request and provides the necessary resources for tRPC procedures, including the database client and authentication session data. This ensures that every operation has access to the current user's state and the data persistence layer.
Sources: AGENTS.md:38-40, README.md:118-125
Router Structure
Business logic is organized into sub-routers (e.g., widget router) which are combined into a root router. The project follows strict rules for procedure definitions:
- Separation of Concerns: Business logic lives in
packages/api, while UI and routing live inapps/web. - Procedure Types:
protectedProcedureis used for any action requiring authentication, ensuring unauthorized users cannot access sensitive endpoints. - Validation: All inputs are validated using
zodschemas.
API Integration Table
| Component | Location | Description |
|---|---|---|
| Root Router | packages/api/src/routers/index.ts | The central entry point combining all sub-routers. |
| Context Creator | packages/api/src/context.ts | Generates the ctx object for procedures (DB, Auth). |
| HTTP Handler | apps/web/src/app/api/trpc/[trpc]/route.ts | Next.js App Router endpoint for tRPC requests. |
| Widget Router | packages/api/src/routers/widget.ts | Handles widget creation and management. |
| Sources: AGENTS.md:88-95, loops-email-collection.md:28-36 |
Data Flow and Procedure Execution
When a client initiates a request, it passes through the Next.js edge-compatible proxy or direct tRPC handler before hitting the specific procedure.
The sequence diagram illustrates the request lifecycle from the client through validation and database access back to the client.
Sources: README.md:83-99, AGENTS.md:31-37
Implementation Standards
KudosWall enforces several coding standards to maintain API quality:
- No
any: Procedures must use strict typing, preferringunknownif a type is uncertain. - Explicit Returns: Public API and tRPC procedures must have explicit return types for clarity and type safety.
- Audit Logging: Critical operations (CRUD) performed through the API are logged to an
audit_logtable for traceability. - Error Handling: The API uses type-safe error classes or standard result objects for expected failures.
Sources: AGENTS.md:14-23, AGENTS.md:78-81
Conclusion
The tRPC API implementation in KudosWall provides a robust, type-safe framework for modern SaaS development. By strictly separating business logic from UI concerns and enforcing rigorous validation and authentication at the procedure level, the architecture ensures both developer productivity and system security across the monorepo.