API Layer

The API layer uses tRPC v11 for type-safe internal APIs. All server-side business logic runs through tRPC procedures, which form a middleware chain that progressively adds session authentication, tenant-scoped database access (via RLS), and CASL authorization to the request context.

How a Request Flows

React component (trpc.widget.list.useQuery())
  |
  v
httpBatchLink --> POST /api/trpc/widget.list
  |
  v
Next.js route handler (apps/web/src/app/api/trpc/[trpc]/route.ts)
  |
  v
fetchRequestHandler --> createContext(headers)
  |   Session lookup, logger creation
  v
Procedure middleware chain:
  1. publicProcedure  -- request logging (path, type, duration)
  2. protectedProcedure -- session validated (ctx.session guaranteed)
  3. tenantProcedure  -- withTenantContext called (ctx.db = RLS transaction)
  4. authorizedProcedure -- member lookup, CASL ability, AI helper
       |
       v
     Router handler (business logic)
       |
       v
     Response --> TanStack Query cache --> React component re-render

Key Files

File	Purpose
packages/api/src/trpc.ts	Procedure definitions (public, protected, tenant, authorized)
packages/api/src/context.ts	Context creation from request headers
packages/api/src/router.ts	Root appRouter -- merges all feature routers
packages/api/src/routers/	Feature routers (one file per domain entity)
packages/api/src/index.ts	Package barrel -- exports appRouter, createContext, procedures
apps/web/src/lib/trpc-react.ts	tRPC + TanStack Query client for React components
apps/web/src/components/providers.tsx	QueryClient + tRPC provider wrapper
apps/web/src/app/api/trpc/[trpc]/route.ts	Next.js API route handler

Current Routers

The appRouter in packages/api/src/router.ts merges these routers:

Router	Procedure	Domain
health	publicProcedure	System health check
organization	authorizedProcedure	Org detail, update
member	authorizedProcedure	Member list, role update, removal
pat	protectedProcedure	Personal access token CRUD (user-scoped, not org-scoped)
researchPlan	authorizedProcedure	Plan list/detail, steps, audit log, health summary
researchArtifact	authorizedProcedure	Artifact list/detail/search, stats
hybridSearch	authorizedProcedure	Hybrid search (BM25 + pgvector), type-ahead, debug
aiLogs	authorizedProcedure	AI usage summary, logs, model distribution, playground
skillExecution	authorizedProcedure	Skill execution list/detail/summary

Related Pages

• tRPC Server Setup -- procedure definitions, context creation, error formatter
• Router Patterns -- standard patterns for queries, mutations, pagination, and filtering
• Error Handling -- error codes, Zod validation, Sentry integration
• Client Configuration -- React Query hooks, provider tree, using tRPC from components

Cross-Domain References

• Data & Storage -- Procedure Chain -- how the procedure chain builds the tenant-scoped database context
• Identity & Access -- Router Enforcement -- how CASL integrates with routers and the architecture test
• Identity & Access -- Ability Definitions -- the defineAbilityFor() function and role permission matrix