Development

This section covers everything you need to contribute to Rack Gateway development, from setting up your local environment to understanding the codebase architecture.

Getting Started

Local SetupSet up your development environment with all prerequisites.

TestingRun unit tests, integration tests, and E2E tests.

ContributingContribution guidelines and code standards.

API ReferenceOpenAPI specification and API documentation.

Architecture Overview

Rack Gateway is split into three main components:

Component Responsibilities

Component	Location	Purpose
Gateway Server	`internal/gateway/`	API server with OAuth, RBAC, proxying, and audit logging
CLI Client	`cmd/rack-gateway/`, `internal/cli/`	Multi-rack aware CLI that authenticates via gateway
Web UI	`web/`	React SPA for admin interface
Mock OAuth	`mock-oauth/`	Mock Google OAuth server for testing

Project Structure

rack-gateway/
├── cmd/
│   ├── gateway/          # Gateway server entrypoint
│   ├── rack-gateway/     # CLI client entrypoint
│   ├── mock-convox/      # Mock Convox API for testing
│   └── totp-gen/         # TOTP codes for development and tests
├── internal/
│   ├── gateway/          # Gateway server packages
│   │   ├── app/          # Application setup
│   │   ├── auth/         # OAuth + sessions + MFA
│   │   ├── rbac/         # Role-based access control
│   │   ├── proxy/        # Convox API proxy
│   │   ├── audit/        # Audit logging + redaction
│   │   ├── handlers/     # HTTP handlers
│   │   ├── middleware/   # HTTP middleware
│   │   ├── jobs/         # Background jobs (River)
│   │   └── db/           # Database layer and SQL migrations
│   ├── cli/              # CLI implementation
│   └── integration/      # Integration tests
├── web/                  # React SPA frontend
│   ├── src/
│   │   ├── api/          # Generated API client
│   │   ├── components/   # React components
│   │   └── pages/        # Page components
│   └── e2e/              # Playwright E2E tests
├── mock-oauth/           # Mock OAuth server
├── docs/                 # This documentation site
└── taskfiles/            # Task runner configuration

Development Workflow

Daily Development

# Start the development environment (Overmind; for people, not scripts or AI agents)
task dev

# This starts:
# - Gateway API on port 8447
# - Web UI on port 5223
# - Mock OAuth on port 3345
# - Mock Convox on port 5443
# - PostgreSQL database

Making Changes

Create a branch for your changes
Make your changes in the appropriate package

Run tests to verify:

task go:test:unit   # Go unit tests (task go:test adds the integration tests)
task web:test       # Web unit tests

Run linters to check code quality:
Terminal window
```
task lint:fix   # Fix linting issues
```
Commit and push. The pre-commit hook formats, lints and checks duplication and file lengths. CI runs the full suite (task ci: lint, unit and integration tests, E2E tests and builds) on every push; run it locally only when you need to (it takes about 15 minutes)

Code Generation

Several files are auto-generated:

OpenAPI spec (server): internal/gateway/openapi/generated/swagger.json
OpenAPI spec (web): web/src/api/openapi.json
API client and schema types (orval): web/src/api/generated.ts and web/src/api/schemas/

Regenerate with:

task generate

Key Technologies

Backend (Go)

Go (version pinned in mise.toml) - Primary backend language
Gin - HTTP framework
pgx / database/sql - PostgreSQL access, with plain SQL migrations
River - Background jobs in PostgreSQL
golangci-lint - Linting with 20+ linters enabled

Frontend (TypeScript)

React 19 - UI framework
Vite - Build tool
TanStack Router and Query - Routing and data fetching
Tailwind CSS - Styling
Biome - Linting and formatting

Testing

Go testing - Unit and integration tests
Vitest - Web unit tests
Playwright - E2E tests

Infrastructure

PostgreSQL - Primary database
Docker - Container builds
Task - Task runner (like Make, but better)
mise - Environment variable management

Quick Reference

Common Task Commands

Command	Description
`task dev`	Start development environment
`task ci`	Run full CI suite (lint, test, build)
`task lint:fix`	Fix linting issues
`task go:test:unit`	Run Go unit tests
`task go:test`	Run Go unit and integration tests
`task web:test`	Run web tests
`task web:e2e`	Run Playwright E2E tests
`task build`	Build all binaries
`task generate`	Regenerate code

Development Ports

Service	Port	URL
Gateway API	8447	`http://localhost:8447`
Web UI	5223	`http://localhost:5223`
Mock OAuth	3345	`http://localhost:3345`
Mock Convox	5443	`http://localhost:5443`
PostgreSQL	55432	`localhost:55432`

Health Check URLs

# Gateway health
curl http://localhost:8447/api/v1/health

# Mock OAuth health
curl http://localhost:3345/health

# Mock Convox health
curl http://localhost:5443/health