Architecture

Solo Kit is built with a modern, scalable architecture that emphasizes code sharing, type safety, and developer experience.

Monorepo Structure

The project uses a monorepo structure powered by pnpm workspaces:

solo-kit/
├── apps/
│   ├── web/          # Next.js web application
│   └── mobile/       # Expo mobile application
├── packages/
│   ├── ui/           # Shared UI components (shadcn/ui)
│   ├── utils/        # Platform-agnostic utilities
│   ├── database/     # Database layer (Drizzle ORM)
│   └── eslint-config/# Shared ESLint configuration
└── docs/             # Documentation

Technology Stack

Web Application (apps/web)

• Next.js 15 with App Router
• React 18 with Server Components
• TypeScript for type safety
• Tailwind CSS for styling
• shadcn/ui for UI components

Mobile Application (apps/mobile)

• Expo with React Native
• Shared UI components from packages/ui
• Shared utilities from packages/utils

Shared Packages

UI Package (packages/ui)

• Based on shadcn/ui components
• Platform-agnostic React components
• Consistent design system
• TypeScript definitions

Utils Package (packages/utils)

• Platform-agnostic utility functions
• Constants and configuration
• Type definitions
• Helper functions

Database Package (packages/database)

• Drizzle ORM for type-safe database operations
• Schema definitions
• Migration system
• Seed data

Feature Flag System

Solo Kit uses a sophisticated feature flag system for seamless development:

Build-Time Feature Flags

Feature flags are resolved at build time for optimal performance:

// config/features.ts
export const FEATURES = {
  DATABASE: process.env.DATABASE_URL ? 'postgresql' : 'unconfigured',
  AUTH: 'enabled', // Always enabled with BetterAuth
  EMAIL: process.env.RESEND_API_KEY ? 'resend' : 'console',
  PAYMENTS: process.env.STRIPE_SECRET_KEY ? 'stripe' : 'mock',
} as const;

Production-Ready Architecture

Each feature is designed for production from day one:

• Database: PostgreSQL with free tier providers (Neon, Supabase, Railway)
• Email: Console logging → Resend/SendGrid/Postmark
• Payments: Mock responses → Stripe integration
• Auth: BetterAuth with secure defaults

Authentication Architecture

BetterAuth Integration

• JWT-based authentication
• Multiple OAuth providers
• Secure session management
• Type-safe auth state

Security Features

• CSRF protection
• Rate limiting
• Secure headers
• Environment variable validation

Database Architecture

Drizzle ORM

• Type-safe database operations
• Automatic migration generation
• Schema-first approach
• Multi-database support

Schema Organization

packages/database/src/schema/
├── users.ts          # User tables
├── auth.ts           # Authentication tables
├── subscriptions.ts  # Payment/subscription tables
└── index.ts          # Schema exports

State Management

Server State

• React Query (TanStack Query) for server state caching
• Server Actions for mutations
• Optimistic updates for better UX

Client State

• React Hook Form for form state
• Zustand for global client state
• React Context for theme and auth

Styling Architecture

Tailwind CSS

• Utility-first CSS framework
• Custom design system
• Dark mode support
• Mobile-first responsive design

Component Styling

• shadcn/ui base components
• CSS-in-JS for complex components
• Tailwind classes for layout and spacing

Build System

Next.js Configuration

• App Router with TypeScript
• MDX support for documentation
• Image optimization
• Bundle analysis

Development Tools

• ESLint with custom rules
• Prettier for code formatting
• TypeScript for type checking
• Vitest for testing

Deployment Architecture

Vercel (Recommended)

• Zero-config deployment
• Edge functions
• Automatic HTTPS
• Preview deployments

Docker Support

• Multi-stage builds
• Production-optimized images
• Environment variable handling
• Health checks

Performance Considerations

Code Splitting

• Route-based code splitting
• Component lazy loading
• Dynamic imports

Caching Strategy

• Static generation where possible
• Incremental Static Regeneration
• Client-side caching with React Query

Bundle Optimization

• Tree shaking
• Dead code elimination
• Modern ES modules
• Compression

This architecture provides a solid foundation for building scalable SaaS applications while maintaining developer productivity and code quality.