Rails API Agent Guidelines

Project Structure

This is the main Rails API application that serves as the host for bounded context engines.

Key Concepts

1. Bounded Contexts as Rails Engines - Each bounded context lives in engines/ as a mountable Rails engine
2. Schema Isolation - Each engine uses its own PostgreSQL schema with restricted search_path
3. Supabase for Schema Management - All database schemas/tables are created by Supabase migrations
4. Pure Domain/Application Layers - Domain and application code must be pure Ruby (no Rails)
5. Infrastructure Only in Rails - Only infrastructure layer (controllers, repos, adapters) uses Rails

Database Configuration

The app uses local Supabase with PostgreSQL schema isolation:

• Primary Database: Uses public schema for app-level tables
• Engine Databases: Each engine uses its own schema (e.g., cat_content)
• Schema Creation: Handled by Supabase migrations in supabase/migrations/
• Search Path Restriction: Each connection only sees its designated schema

Multi-Database Setup

Each engine has its own database configuration in config/database.yml:

development:
  primary:
    # Primary app database
    schema_search_path: public
  
  cat_content:
    # Cat & Content engine database
    schema_search_path: cat_content

Working with Engines

Database Setup for New Bounded Context

Note: Engine generation and initial setup is handled by rampart init. See Rampart Features for details.

After generating a new bounded context engine, configure the database:

1. Create Supabase migration in supabase/migrations/:

   CREATE SCHEMA IF NOT EXISTS context_name;
   
   -- Create tables in the schema
   CREATE TABLE context_name.your_table (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     -- columns...
   );
   
   GRANT USAGE ON SCHEMA context_name TO postgres;
   GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA context_name TO postgres;
   

2. Add database config:

   context_name:
     <<: *supabase_local
     schema_search_path: context_name
   

Common Tasks

# Start Supabase (creates all schemas)
supabase start

# Reset database (recreates from migrations)
supabase db reset

# Start Rails server
rails server

Architecture Rules

1. Domain Layer - Pure Ruby, no Rails dependencies

   • Aggregates, Entities, Value Objects
   • Domain Events, Domain Services
   • Repository Interfaces (Ports)

2. Application Layer - Pure Ruby, orchestrates domain

   • Application Services (Use Cases)
   • Commands, Queries
   • No Rails, no database, no HTTP

3. Infrastructure Layer - Rails-specific implementations

   • Controllers (Primary Adapters)
   • ActiveRecord Models (Secondary Adapters)
   • Repository Implementations
   • External Service Adapters

Conventions

• Engine models inherit from engine-specific BaseRecord
• Database schemas are managed by Supabase (not Rails migrations)
• All domain/application code is pure Ruby
• Infrastructure code can use Rails
• Each engine is completely isolated from others

Health Check Endpoints

The API provides health check endpoints for troubleshooting connectivity issues:

Main Health Endpoint

Route: GET /health

Purpose: Comprehensive health check that aggregates status from all components

Checks:

• API service status
• Primary database connectivity
• All mounted engine health statuses