Backend Project Structure

Understanding the organization and architecture of Ryva’s Go backend

Overview

The Ryva backend is built with Go 1.25 and follows a clean, modular architecture with clear separation of concerns. The codebase is organized into distinct layers and domains, making it easy to navigate and extend.

Directory Structure

apps/api/
├── cmd/                    # Application entry points
├── internal/              # Private application code
│   ├── config/           # Configuration management
│   ├── db/               # Generated SQLC database code
│   ├── modules/          # Business logic modules
│   ├── router/           # HTTP routing
│   └── shared/           # Shared utilities and middleware
├── db/                   # Database files
│   ├── schema/          # SQL schema definitions
│   └── queries/         # SQL query definitions
├── sqlc.yml             # SQLC configuration
└── go.mod               # Go module dependencies

Internal Directory

The internal/ directory contains all private application code that cannot be imported by other projects.

Configuration Layer (internal/config/)

Contains environment-based configuration for different services:

• config.go - Main configuration struct
• auth.go - Authentication settings (JWT, Supabase)
• database.go - Database connection settings
• email.go - Email service configuration (Resend)
• server.go - HTTP server settings
• stripe.go - Payment processing configuration
• sentry.go - Error tracking configuration

Database Layer (internal/db/)

Contains SQLC-generated Go code organized by domain:

internal/db/
├── db.go              # Central database manager
├── auth/             # User authentication queries
├── billing/          # Subscription and payment queries
├── organizations/    # Organization management queries
└── waitlist/         # Waitlist queries

Each domain package includes:

• db.go - Database connection wrapper
• models.go - Generated model structs
• querier.go - Query interface
• *.sql.go - Generated query implementations

Modules Layer (internal/modules/)

Contains business logic organized by domain:

internal/modules/
├── auth/             # User authentication and profile
├── billing/          # Payment and subscription management
├── organizations/    # Organization CRUD and invitations
├── stripe/           # Stripe integration
└── waitlist/         # Waitlist management

Each module follows the Handler → Service → Repository pattern (see Module Architecture).

Router Layer (internal/router/)

HTTP routing using Chi router:

• router.go - Main router configuration
• handlers.go - Handler registration
• types.go - Router-specific types

Routes are versioned (e.g., /v1/auth/me) and grouped by domain.

Shared Layer (internal/shared/)

Reusable utilities and middleware:

• appcontext/ - Context management (user ID, request ID)
• apperrors/ - Standardized error handling
• database/ - Database connection utilities
• email/ - Email sending and templates
• httputil/ - HTTP response helpers
• logger/ - Structured logging
• middleware/ - HTTP middleware (auth, logging, recovery)
• stringutil/ - String manipulation helpers
• validator/ - Input validation

Database Files

The db/ directory contains raw SQL that gets compiled into Go code:

1. Schema Definitions (db/schema/)

   SQL schema files define database structure:

   • auth.sql - Users table
   • organizations.sql - Organizations, members, invitations
   • billing.sql - Subscriptions, payment methods, Stripe events
   • waitlist.sql - Waitlist entries

   Example from auth.sql:

   CREATE TABLE public.users (
       id UUID PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
       email TEXT NOT NULL UNIQUE,
       full_name TEXT,
       avatar_url TEXT,
       onboarding_completed BOOLEAN NOT NULL DEFAULT false,
       preferences JSONB NOT NULL DEFAULT '{}',
       created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
       updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
   );
   
2. Query Definitions (db/queries/)

   SQL queries organized by domain:

   • auth/users.sql - User queries
   • organizations/*.sql - Organization queries
   • billing/*.sql - Billing queries
   • waitlist/waitlist.sql - Waitlist queries

   Example query:

   -- name: GetUserByID :one
   SELECT * FROM public.users
   WHERE id = $1 LIMIT 1;
   

Key Dependencies

From go.mod:

Core Dependencies

• github.com/go-chi/chi/v5 - HTTP router
• github.com/jackc/pgx/v5 - PostgreSQL driver
• github.com/golang-jwt/jwt/v5 - JWT authentication
• github.com/stripe/stripe-go/v84 - Payment processing
• github.com/resend/resend-go/v2 - Email delivery
• github.com/getsentry/sentry-go - Error tracking

Design Principles

1. Domain-Driven Design

   Code is organized by business domain (auth, billing, organizations) rather than technical layers.

2. Separation of Concerns

   Clear boundaries between HTTP handling, business logic, and data access.

3. Type Safety

   SQLC generates type-safe Go code from SQL, eliminating runtime query errors.

4. Dependency Injection

   Services receive dependencies through constructors, making code testable.

Next Steps

Module Architecture

Learn about the Handler → Service → Repository pattern

Database Setup

Configure database and write SQL queries