​
Backend Feature Template

​
Status

  • document type: implementation template
  • use this page when an agent needs a default structure for a new backend feature

​
Goal

Provide a default backend feature shape so an agent does not invent a new architecture for each service, controller, or entity change.

​
Default Decision Order

Before creating backend files, ask:
  1. can this be handled by an existing native entity plus settings or custom attributes?
  2. does this belong to shared platform, domain behavior, or tenant configuration?
  3. does the workflow require a service?
  4. does the API contract need a controller or serializer change?
  5. does access require a policy or filter update?

​
Common Backend Shapes

​
Extend Existing Entity

Use when:
  • the behavior belongs to an existing model
  • no new aggregate is needed
Typical touched files:
  • model
  • service
  • controller
  • policy
  • spec

​
New Shared Feature Without New Model

Use when:
  • the behavior is mostly orchestration
  • current entities already cover the data model
Typical touched files: 
app/services/<feature>/<action>_service.rb
app/controllers/api/v1/accounts/<feature>_controller.rb
app/policies/<feature>_policy.rb
spec/services/<feature>/<action>_service_spec.rb
spec/controllers/... or spec/requests/...

​
New Shared Entity

Use only when current native entities do not fit cleanly. Typical touched files: 
app/models/<entity>.rb
app/controllers/api/v1/accounts/<entities>_controller.rb
app/policies/<entity>_policy.rb
app/services/<entity>/...
db/migrate/...
spec/models/<entity>_spec.rb
spec/controllers/... or spec/requests/...
spec/policies/<entity>_policy_spec.rb

​
Placement Rules

​
Model

Put in the model:
  • associations
  • validations
  • scopes
  • small record-local helpers

​
Service

Put in a service:
  • multi-step workflows
  • external integrations
  • cross-record orchestration
  • domain operations that should stay readable outside the model

​
Controller

Put in a controller:
  • params
  • authorization
  • invoking service or model work
  • response handling

​
Policy

Put in a policy:
  • read/write permission rules
  • account-user visibility rules

​
Serializer Or View

Put in serializer/view layer:
  • response-shape concerns
  • presentation fields for APIs

​
Enterprise Check Rule

Before finalizing any shared backend change:
  • search app/ and enterprise/
  • keep contracts compatible where the inherited enterprise/ tree extends the same surface
  • prefer extension hooks or enterprise modules over unnecessary hard forks

​
Example Skeleton

app/services/contacts/company_association_service.rb
enterprise/app/controllers/api/v1/accounts/companies_controller.rb
enterprise/app/policies/company_policy.rb
spec/enterprise/controllers/api/v1/accounts/companies_controller_spec.rb
spec/enterprise/policies/company_policy_spec.rb

​
Verification Template

For a normal backend feature, the minimum verification path is usually:
  • narrow RSpec for the touched service/controller/policy
  • optional manual smoke call for API-heavy features
  • Swagger update if the contract is documented and public