Architecture

Document your system architecture, tech stack decisions, and infrastructure design.

System Overview

High-Level Architecture

Describe the overall system architecture:

Tech Stack

Frontend

• Framework: TanStack Start
• Styling: TailwindCSS v4
• State Management: TanStack Start loaders/actions
• UI Components: shadcn/ui
• Icons: Lucide React, Tabler Icons

Backend

• Database: Convex (real-time, serverless)
• Authentication: BetterAuth (free, open-source)
• Payments: Polar.sh
• Email: Resend (via Convex)
• AI: OpenAI (if enabled)

Infrastructure

• Frontend Hosting: Cloudflare Workers (edge computing)
• Backend: Convex (serverless, real-time)
• CDN: Cloudflare global network
• Monitoring: Sentry (via Convex Pro)

Data Flow

Authentication Flow

1. User clicks "Sign In"
2. BetterAuth authentication flow initiates
3. User authenticates (email/OAuth)
4. BetterAuth redirects with session token
5. Convex validates session
6. User data synced to Convex

Payment Flow

1. User selects subscription plan
2. Polar checkout initiated
3. User completes payment
4. Polar webhook sent to Convex
5. Subscription status updated
6. User access granted

API Design

Convex Functions

Queries (Read Operations)

// Example query structure
export const getUser = query({
  args: { userId: v.id("users") },
  returns: v.object({ ... }),
  handler: async (ctx, args) => {
    // Query logic
  },
});

Mutations (Write Operations)

// Example mutation structure
export const updateProfile = mutation({
  args: { name: v.string() },
  returns: v.null(),
  handler: async (ctx, args) => {
    // Mutation logic
  },
});

Actions (External APIs)

// Example action structure
export const sendEmail = action({
  args: { to: v.string(), subject: v.string() },
  returns: v.null(),
  handler: async (ctx, args) => {
    // Action logic with external API calls
  },
});

Security Considerations

Authentication & Authorization

• Session-based authentication via BetterAuth (free, open-source)
• Role-based access control (if applicable)
• Session management
• API route protection

Data Protection

• HTTPS everywhere
• Environment variable encryption
• Input validation and sanitization
• Rate limiting on sensitive endpoints

Performance Optimization

Frontend

• Code splitting
• Lazy loading
• Image optimization
• Caching strategy

Backend

• Database indexing
• Query optimization
• Caching layer
• Connection pooling

Scalability Plan

Current Capacity

• Expected concurrent users: X
• Database size limit: X
• API request limit: X

Scaling Strategy

• Vertical: Upgrade Convex plans
• Horizontal: Cloudflare Workers auto-scales globally, caching layers
• Database: Convex automatically scales

Deployment Architecture

Development Environment

• Local development server
• Test database (Convex dev deployment)
• Test payment environment (Polar test mode)

Production Environment

• Cloudflare Workers production deployment (frontend)
• Production Convex deployment (backend)
• Production BetterAuth configuration
• Production Polar organization

Monitoring & Logging

Error Tracking

• Sentry integration via Convex Pro
• Frontend error boundaries
• API error logging

Analytics

• User behavior tracking
• Performance monitoring
• Conversion funnel analysis

Disaster Recovery

Backup Strategy

• Convex automatic backups
• Export/import capabilities
• Point-in-time recovery

Incident Response

1. Detect issue (monitoring alerts)
2. Assess impact
3. Implement fix or rollback
4. Post-mortem documentation