Rails Architect

Rails Architect

Purpose

Design and implement backend features following Rails conventions with our specific stack: Rails + Panko + PostgreSQL/PostGIS + Redis + Sidekiq + Centrifugo.

Design Protocol

1. Data Model First

• Start with the PostgreSQL schema — tables, columns, types, constraints
• Use PostGIS types (st_point, geography) for any location data
• Design indexes upfront: foreign keys, unique constraints, partial indexes, GiST for spatial
• Plan JSONB columns for flexible/polymorphic data
• Write reversible migrations with change method

2. Model Layer

• Define associations, validations, scopes
• Use has_many through: for join tables
• Extract complex queries to scopes or query objects
• Use ActiveRecord::Enum for status fields
• Add database-level constraints alongside model validations

3. API Design

• RESTful controllers with standard 7 actions
• Panko serializers for every response — never render raw models
• Separate list and detail serializers for performance
• Use pagy for pagination with cursor support
• Consistent error responses: { error: String, code: Integer, details: Object? }

4. Service Layer

• Extract business logic to app/services/ (any wrapper directory — the tree below illustrates shape, not a path to hardcode)
• Single responsibility: CreateOrder, ProcessPayment, GeofenceCheck
• Return result objects for success/failure handling
• Inject dependencies for testability

5. Background Processing

• Jobs live in app/jobs/ (any wrapper directory — backend/ is one team's naming, not a contract)
• Anything over ~100ms of work belongs in a job, not the request
• Separate queues: default, critical, mailers, low_priority
• Pass IDs, not objects. A serialized record is a snapshot of a row that may have changed by the time the job runs; find it fresh.
• Idempotent jobs — because Sidekiq already retries 25 times over ~20 days, by default. You did not configure that; it is the default, and "no retry policy" means three weeks of them. Set sidekiq_options retry: deliberately on every job. If you use ActiveJob's retry_on, know that it does not replace Sidekiq's retries — it stacks on top, so retry_on ..., attempts: 5 runs 30 attempts, not 5. A job that dies lands in the Dead set silently: alert on it. Depth → @skills/std-error-handling/references/background-jobs.md

6. Caching Strategy

• Redis-backed Rails.cache.fetch with explicit TTLs
• Cache Panko-serialized responses at controller level
• Fragment caching for repeated computations
• Cache invalidation on model callbacks

7. Real-time (Centrifugo)

• Design channel topology: chat:room_123, user:456, location:fleet
• Publish from Rails via Centrifugo HTTP API
• Use Redis pub/sub for internal event distribution
• JWT-based channel authorization

Reference Architecture

backend/app/
├── controllers/
│   └── api/v1/           # Versioned API controllers
├── models/               # ActiveRecord models with validations
├── serializers/          # Panko::Serializer classes
├── services/             # Business logic service objects
├── jobs/                 # Sidekiq background jobs
├── policies/             # Pundit authorization policies
├── queries/              # Complex query objects
└── channels/             # Centrifugo channel helpers

Common Patterns

PostGIS Spatial Query

# Find locations within radius
Location.where(
  "ST_DWithin(coordinates, ST_MakePoint(?, ?)::geography, ?)",
  longitude, latitude, radius_meters
)

Panko Serializer with Association

class OrderSerializer < Panko::Serializer
  attributes :id, :status, :total_cents, :created_at
  has_one :customer, serializer: CustomerListSerializer
  has_many :items, serializer: OrderItemSerializer
end

Sidekiq Job with Redis Cache

class GeofenceCheckJob < ApplicationJob
  queue_as :default

  def perform(vehicle_id, lat, lng)
    vehicle = Vehicle.find(vehicle_id)
    geofences = Rails.cache.fetch("active_geofences", expires_in: 5.minutes) do
      Geofence.active.to_a
    end
    # Check and notify...
  end
end

See references/rails-patterns.md for comprehensive patterns library.

Owned elsewhere — do not duplicate

This skill designs the shape. These own the rules, are scoped to Rails work, and carry the bad/good pairs:

• Authorization — a policy that is never called is not authorization; index needs policy_scope, not authorize; devise-jwt does not revoke by default → @skills/std-rails-conventions/references/authorization.md
• Migrations, locking, lock_timeout — a migration that waits is more dangerous than one that fails, because every query queues behind it → @skills/std-database/references/locking-and-timeouts.md
• Sidekiq retries, the Dead set, ActiveJob vs Sidekiq::Job → @skills/std-error-handling/references/background-jobs.md
• The API error envelope (error, code, status, details, requestId — exactly one shape) → @skills/std-api-design/references/errors-rails.md
• Pagination — cursor is the default, 25/100, pagy → @skills/std-api-design/references/pagination-rails.md
• Request tracing across the async boundary → @skills/std-monitoring/references/request-tracing.md