Architecture Overview

High-level architecture and design principles of the Ryva platform

Architecture Overview

Ryva is a modern SaaS workspace platform built with a clean separation between frontend and backend, following industry best practices for scalability, maintainability, and developer experience.

Technology Stack

Frontend

• Framework: Next.js 16 (App Router)
• UI Library: React 19
• Language: TypeScript
• Styling: Tailwind CSS v4
• State: TanStack Query + Zustand

Backend

• Language: Go 1.25
• Router: Chi v5
• Database: PostgreSQL (via pgx/v5)
• Auth: Supabase + JWT
• Payments: Stripe

Infrastructure

• Containerization: Docker
• Reverse Proxy: Caddy
• Database: PostgreSQL
• Monitoring: Sentry
• Email: Resend

Development

• Hot Reload: Air (Go) + Next.js Fast Refresh
• Testing: Vitest, Playwright, Go testing
• CI/CD: GitHub Actions
• Code Quality: pre-commit hooks

Architecture Principles

Ryva follows these core architectural principles:

1. Clean Architecture

Both frontend and backend follow clean architecture patterns with clear separation of concerns.

Backend (Go):

• Handler → Service → Repository pattern
• Handlers process HTTP requests/responses
• Services contain business logic
• Repositories handle data access

Frontend (React/Next.js):

• Components → Hooks → API Client pattern
• Components focus on UI presentation
• Hooks manage data fetching and state
• API client handles HTTP communication

2. Modular Design

The codebase is organized into feature modules for better maintainability:

Backend Modules

• auth - User authentication and profile management
• organizations - Organization and team management
• billing - Stripe integration and subscription handling
• waitlist - Waitlist signup and email notifications
• shared - Common utilities (database, email, errors)

Frontend Modules

• modules/auth - Authentication forms and hooks
• modules/organizations - Organization management UI
• modules/billing - Subscription and checkout flows
• modules/waitlist - Waitlist signup components
• modules/blog - Content management via Sanity

3. Type Safety

Strict type safety is enforced across the entire stack:

• TypeScript: No any types allowed, strict mode enabled
• Go: Explicit types, comprehensive error handling

4. API-First Design

The backend exposes a versioned REST API (/v1) that the frontend consumes:

API Architecture:
├── /health (health check)
├── /v1/auth/* (authentication)
├── /v1/organizations/* (organization management)
├── /v1/billing/* (subscription management)
└── /v1/waitlist (waitlist signup)

5. Security by Default

• Authentication: JWT tokens via Supabase Auth
• Authorization: Middleware-based auth checks
• CORS: Configured in Caddy reverse proxy
• Rate Limiting: Per-endpoint rate limits in Caddy
• Security Headers: HSTS, CSP, X-Frame-Options, etc.

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Client Layer                         │
│  (Next.js App Router - Server & Client Components)         │
└─────────────────┬───────────────────────────────────────────┘
                  │
                  │ HTTPS
                  │
┌─────────────────▼───────────────────────────────────────────┐
│                    Caddy Reverse Proxy                      │
│  - SSL Termination                                          │
│  - Rate Limiting (per endpoint)                             │
│  - Load Balancing (round-robin)                             │
│  - Health Checks                                            │
│  - Security Headers                                         │
└─────────────────┬───────────────────────────────────────────┘
                  │
                  │ HTTP
                  │
┌─────────────────▼───────────────────────────────────────────┐
│                      Go API Server                          │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐  │
│  │              Router (Chi)                           │  │
│  │  - CORS Middleware                                  │  │
│  │  - Auth Middleware (JWT validation)                 │  │
│  │  - Logging & Recovery                               │  │
│  └──────────────┬──────────────────────────────────────┘  │
│                 │                                          │
│  ┌──────────────▼──────────────────────────────────────┐  │
│  │              Handlers                               │  │
│  │  - Request validation                               │  │
│  │  - Response formatting                              │  │
│  └──────────────┬──────────────────────────────────────┘  │
│                 │                                          │
│  ┌──────────────▼──────────────────────────────────────┐  │
│  │              Services                               │  │
│  │  - Business logic                                   │  │
│  │  - Input validation                                 │  │
│  │  - Error handling                                   │  │
│  └──────────────┬──────────────────────────────────────┘  │
│                 │                                          │
│  ┌──────────────▼──────────────────────────────────────┐  │
│  │              Repositories                           │  │
│  │  - Database queries                                 │  │
│  │  - Data mapping                                     │  │
│  └──────────────┬──────────────────────────────────────┘  │
│                 │                                          │
└─────────────────┼──────────────────────────────────────────┘
                  │
                  │ pgx/v5
                  │
┌─────────────────▼───────────────────────────────────────────┐
│                    PostgreSQL Database                      │
│  - Connection pooling                                       │
│  - Automatic migrations                                     │
│  - Prepared statements (production)                         │
└─────────────────────────────────────────────────────────────┘

                External Services
                ─────────────────
                │  Supabase Auth
                │  Stripe Payments
                │  Resend Email
                │  Sentry Monitoring

Data Flow

Request Flow (Read)

1. Client makes GET request to /v1/auth/me
2. Caddy performs health check, rate limiting, adds security headers
3. Router applies CORS and logging middleware
4. Auth Middleware validates JWT token from Authorization header
5. Handler extracts user ID from request context
6. Service applies business logic (if any)
7. Repository queries database using pgx
8. Database returns user data
9. Response flows back through the stack with proper JSON formatting

Request Flow (Write)

1. Client makes POST request with JSON body
2. Caddy checks rate limits and body size (max 10MB)
3. Router applies middleware stack
4. Auth Middleware validates authentication
5. Handler validates request body (DTO validation)
6. Service performs business logic validation
7. Repository executes database transaction
8. Database persists changes
9. Response returns created/updated resource

Error Handling

Ryva implements comprehensive error handling at every layer.

Backend Error Types (internal/shared/apperrors):

• NotFound - Resource not found (404)
• InvalidInput - Validation errors (400)
• Unauthorized - Authentication required (401)
• Forbidden - Insufficient permissions (403)
• BusinessRuleViolation - Business logic errors (400)
• Internal - Server errors (500)

Frontend Error Handling:

• TanStack Query handles API errors with retry logic
• Toast notifications for user-facing errors
• Sentry captures and reports client-side errors
• Graceful fallbacks for network issues

Database Strategy

Connection Pooling

• Uses pgx/v5 connection pool
• Configurable pool size and timeout
• Automatic connection health checks
• Prepared statements in production (disabled in development for compatibility)

Migrations

• SQL migrations in apps/api/db/migrations/
• Automatic execution on API startup
• Timestamped migration files
• Both .up.sql and .down.sql for rollback support

Query Generation

• Uses sqlc for type-safe query generation
• Queries defined in apps/api/db/queries/
• Generated code in internal/db/*

Development Workflow

Hot Reload

• Frontend: Next.js Fast Refresh for instant updates
• Backend: Air monitors Go files and rebuilds automatically

Makefile Commands

make dev          # Start both frontend and backend
make test         # Run all tests
make lint         # Lint all code
make docker-up    # Start with Docker

Deployment Architecture

Production

• Images: Published to GitHub Container Registry (GHCR)
• Orchestration: Docker Compose
• Reverse Proxy: Caddy with automatic HTTPS
• Database: PostgreSQL (Supabase or self-hosted)
• Monitoring: Sentry for error tracking

CI/CD Pipeline

1. Lint & Type Check: ESLint, TypeScript, golangci-lint
2. Test: 80% coverage enforcement
3. Security: Gosec, govulncheck, pnpm audit
4. Build: Multi-stage Docker builds
5. Deploy: Automated deployment to production

Performance Optimizations

Frontend

• Server Components by default
• Code splitting via Next.js App Router
• Image optimization with next/image
• TanStack Query caching and deduplication

Backend

• Connection pooling (pgx)
• Prepared statements in production
• Efficient JSON encoding
• Context-based request cancellation

Infrastructure

• Caddy HTTP/2 and HTTP/3 support
• Gzip and Zstandard compression
• Edge-level rate limiting
• Load balancing with health checks

Database

• Indexed queries
• Connection pooling
• Minimal over-fetching
• Efficient JOIN operations

Next Steps

Frontend Architecture

Learn about Next.js structure, state management, and routing

Backend Architecture

Explore Go API structure, modules, and clean architecture

Infrastructure

Understand Docker, Caddy, and deployment infrastructure