Infrastructure
The backbone of the boilerplate. PostgreSQL, Redis, tRPC, transactional email, and structured error handling — all production-grade and ready to scale.
PostgreSQL via Drizzle ORM
21 tables defined with Drizzle ORM covering auth, organizations, chat, memories, files, connectors, AI skills, and usage tracking. Full migration support included.
- 21 tables with comprehensive relations defined at the schema level
- Type-safe queries via Drizzle ORM with automatic type inference
- 50+ query functions in the data access layer
- All functions wrapped in try/catch with ChatSDKError for structured error handling
- Organization scoping on all list/filter queries
- Migration setup with drizzle-kit: generate, push, and migrate commands
Upstash Redis
Serverless Redis for three critical functions: rate limiting, token usage tracking, and conversation compaction storage.
- Rate limiting: sliding window via @upstash/ratelimit (10 messages per 60s for paid users)
- Token budget: per-user key with set/get/increment/decrement (1M initial budget)
- Compaction cache: conversation summaries with 7-day TTL
- HTTP-based Upstash client — no persistent TCP connections needed
- Free tier users blocked (0 messages); paid tier: 10/60s
tRPC v11
Type-safe client-server communication layer with 10 routers and 82+ procedures. All calls except chat streaming go through tRPC.
- 10 routers: chat, user, usage, payments, memory, file, org, team, skills, connectors
- Public and private procedures with session-based auth middleware
- Auth middleware extracts activeOrganizationId from session
- Scope-aware analytics: org admins see all, team-admins see teams, members see own data
- Three-tier permission model on team operations
Transactional email via Resend
Five email functions with branded HTML templates for verification, password reset, org invitations, and contact forms.
- Verification link and OTP emails (adapts by type: email-verification, sign-in, forget-password)
- Organization invitation emails with branded templates
- Password reset emails with token expiration
- Contact form via React Email template
- Shared emailWrapper() for consistent header/footer across all emails
- Non-blocking sending via waitUntil() for post-signup and invitation flows
Structured error handling
A custom ChatSDKError class with type-safe error codes, HTTP status mapping, visibility policies, and a toResponse() method for consistent API errors.
- Custom ChatSDKError with type:surface error codes
- HTTP status mapping: 400, 401, 403, 429, 503
- Visibility policies: 'response' (shown to user) vs 'log' (server only)
- 12 error surfaces: chat, auth, api, stream, database, history, and more
- toResponse() method for consistent error responses
Shared utilities
Helper functions and type definitions used across the codebase. Tailwind class merging, URL helpers, message conversion, and debug logging.
- cn() for Tailwind class merging via clsx + tailwind-merge
- absoluteUrl() for generating full URLs
- convertToUIMessages() for transforming DB messages to chat UI format
- withFallback() for graceful error recovery
- generateUUID() for ID generation
- Development-only debug logging utilities
Custom React hooks
Three hooks for chat UI scroll behavior, message tracking, and responsive design.
- useMessages: combines scroll-to-bottom with message-sent tracking
- useScrollToBottom: MutationObserver + ResizeObserver with 150ms debounce
- useIsMobile: matchMedia with 768px breakpoint, SSR-safe
Database schema overview
| Group | Tables |
|---|---|
| Auth | user, session, account, verification |
| Organizations | organization, member, invitation, team, team_member |
| Chat | chat, message, vote, stream |
| AI | memory, ai_skills, ai_skills_share, chatbot_preferences |
| Files | files, file_share |
| Integrations | user_connector |
| Analytics | usage_event |
tRPC routers
| Router | Procedures | Description |
|---|---|---|
| chat | 17 | Chat CRUD, messages, votes, streams, pin/unpin, title/visibility |
| user | 9 | Profile, billing sync, sessions, preferences |
| usage | 6 | Token balance, rate limits, org analytics |
| payments | 2 | Stripe checkout & billing portal |
| memory | 7 | CRUD, full-text search, upsert (org-scoped) |
| file | 11 | CRUD, sharing, org/team scoping |
| org | 11 | Organization management, invitations, roles |
| team | 7 | Team CRUD, member management, permissions |
| skills | 8 | Owned-skill CRUD, sharing for org/team |
| connectors | 4 | List, connect, disconnect workspace connectors |
82+ procedures total across 10 routers, all type-safe end-to-end.
Production infrastructure, not a prototype.
21 tables, 82+ tRPC procedures, Redis caching, email delivery — all wired.
