Backend overview

The EVO Dialed backend is a Rails 8 API-only application that powers all platform functionality. It manages commercial relationships between brands and content creators.

Technology stack

Component	Technology	Purpose
Framework	Ruby on Rails 8	API and business logic
Database	MySQL 8	Primary data store
Cache/Queue	Redis	ActionCable, SolidQueue, caching
Auth	Better Auth	JWT-based authentication
Jobs	SolidQueue	Background job processing
Push	APNS	iOS push notifications
Hosting	Railway	Container hosting

Directory structure

app/
  controllers/
    api/
      internal/     # Admin endpoints (~80 controllers)
      creator/      # Creator endpoints (~39 controllers)
      public/       # Public endpoints (~23 controllers)
      webhooks/     # External webhooks
  models/           # ~130+ models
    chat/           # Chat system models
    mc/             # Mission Control models
    slack/          # Slack integration models
  services/         # ~60+ service directories
  jobs/             # ~30+ job directories
  mailers/          # Email templates

config/
  routes.rb         # ~1000 lines of routes
  recurring.yml     # SolidQueue job schedules

docs/
  ai/               # AI-readable domain rules
  adr/              # Architecture Decision Records

Key documentation files

File	Purpose
`CLAUDE.md`	Development instructions and safety rules
`CONTEXT.md`	Domain glossary (source of truth)
`docs/ai/`	Standing product rules per feature
`docs/adr/`	Architecture Decision Records

API namespaces

The backend exposes three API namespaces:

Internal API (`/api/internal/*`)

For the admin frontend (EVO team):

Full CRUD on all resources
Mission Control, Pipeline, Roster operations
Analytics and reporting
Requires admin JWT (user_typ: "evo")

Creator API (`/api/creator/*`)

For the iOS app (creators):

Dashboard, brand hubs, chat
Content submission and metrics
Strategy viewing
Requires creator JWT (user_typ: "creator")

Public API (`/api/public/*`)

For unauthenticated access:

Client Hub (with optional passcode)
Public brand reports
Contract signing
Invite acceptance

Authentication

Authentication is handled by Better Auth (a separate service in the Next.js frontend). The Rails backend validates JWTs.

# Most controllers include:
include JwtAuthenticatable

# Admin-only routes add:
before_action :require_evo!

Critical ADR: user_id across ~46 tables is a Better Auth id (string(64)), NOT users.id. Always join via users.auth_user_id.

Core patterns

Single write paths

Critical state changes go through service objects:

Brands::PipelineStatusChange for brand status
Creators::Rejector for creator removal
Campaigns::PlacementAllocator for content attribution

Brand-centric model

Creators are assigned to brands, not campaigns:

BrandCreatorMembership is the core assignment table
Campaigns run under brands
Removing from a brand removes all campaign access

Dual-table identity

Better Auth owns authentication, Rails owns business data:

better_auth_users - Auth credentials
users - Business data (linked via auth_user_id)

Running locally

# Install dependencies
bundle install

# Setup database
bin/rails db:create db:migrate db:seed

# Start server
bin/rails server

Pre-push checklist

bin/brakeman --no-pager
bin/bundler-audit
bin/rubocop
RAILS_ENV=test bin/rails db:test:prepare test

Authentication - JWT and Better Auth details
Models - Core domain models
Services - Business logic patterns
Jobs - Background processing
API Reference - Endpoint documentation

Getting Started

Platform Guide

Admin Console

Notifications

Backend

Frontend

iOS App

Integrations

Technology stack

Directory structure

Key documentation files

API namespaces

Internal API (`/api/internal/*`)

Creator API (`/api/creator/*`)

Public API (`/api/public/*`)

Authentication

Core patterns

Single write paths

Brand-centric model

Dual-table identity

Running locally

Pre-push checklist

​Technology stack

​Directory structure

​Key documentation files

​API namespaces

​Internal API (/api/internal/*)

​Creator API (/api/creator/*)

​Public API (/api/public/*)

​Authentication

​Core patterns

​Single write paths

​Brand-centric model

​Dual-table identity

​Running locally

​Pre-push checklist

​Related documentation

Technology stack

Directory structure

Key documentation files

API namespaces

Internal API (`/api/internal/*`)

Creator API (`/api/creator/*`)

Public API (`/api/public/*`)

Authentication

Core patterns

Single write paths

Brand-centric model

Dual-table identity

Running locally

Pre-push checklist

Related documentation