> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evomarketing.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Backend overview

> Rails API architecture powering the EVO Dialed platform

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.

```ruby theme={null}
# Most controllers include:
include JwtAuthenticatable

# Admin-only routes add:
before_action :require_evo!
```

<Warning>
  **Critical ADR:** `user_id` across \~46 tables is a **Better Auth id (string(64))**, NOT `users.id`. Always join via `users.auth_user_id`.
</Warning>

## 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

```bash theme={null}
# Install dependencies
bundle install

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

# Start server
bin/rails server
```

## Pre-push checklist

```bash theme={null}
bin/brakeman --no-pager
bin/bundler-audit
bin/rubocop
RAILS_ENV=test bin/rails db:test:prepare test
```

## Related documentation

* [Authentication](/backend/authentication) - JWT and Better Auth details
* [Models](/backend/models) - Core domain models
* [Services](/backend/services) - Business logic patterns
* [Jobs](/backend/jobs) - Background processing
* [API Reference](/backend/api-reference) - Endpoint documentation