Skip to main content

Controllers

WIP

Controller Organization by API Context​

What is an "API Context"?​

An API context groups related endpoints that:

  1. Share common authentication/authorization logic
  2. Operate on a bounded domain
  3. Have similar error handling needs

Our API Contexts​

app/controllers/
├── identities/            # Identity & Access Management API Context
│   └── sessions_controller.rb
│   └── users_controller.rb
│
├── employers/             # Employer-specific API Context
|   ├── base_controller.rb # Shared-logic for employers
│   ├── careers/
│   │   ├── jobs_controller.rb
│   │   └── job_applications_controller.rb
│   └── gig/
│       └── jobs_controller.rb
│
├── candidates/            # Candidate-specific operations context
|   ├── base_controller.rb # Shared-logic for careers and gig users
│   ├── careers/
|   |   ├── user_profiles_controller.rb
│   │   └── job_applications_controller.rb
│   └── gig/
│       └── jobs_applications_controller.rb
│
└── marketplace/         # Public marketplace context
|   ├── base_controller.rb # Shared-logic for careers and gig users
│   └── careers/
|       └── jobs_controller.rb

Each context can have its own:

  • Base controller with shared logic
  • Authentication requirements
  • Error handling
  • Response formats

Where Controllers Live​

Rule: Controllers belong in app/controllers/​

Why not app/domains/?

In Rails architecture:

  • app/domains/ → Domain logic, models, services, serializers
  • app/controllers/ → HTTP request/response handling

Controllers are HTTP adapters that:

  1. Parse HTTP requests
  2. Call domain services
  3. Serialize responses
  4. Handle HTTP-specific concerns (cookies, headers, status codes)

They don't belong in the domain layer because HTTP is an infrastructure concern.

Controller Inheritance​