folio-rails-code-structure

name	folio-rails-code-structure
description	Ruby/Rails code structure conventions for Folio: keeping model, controller, and concern entrypoints thin; extracting multi-step parsing, decision, or orchestration logic to focused classes under lib; and avoiding helper-method clusters on Rails integration objects. Use when adding or refactoring Ruby methods, controller actions, model hooks, concerns, or service-style code.

Rails code structure (Folio)

Use this skill when Ruby/Rails code would otherwise add several helper methods to a model, controller, concern, or similar integration object.

Thin entrypoints

Keep public model methods, controller actions, callbacks, hooks, and concern methods focused on their integration role.

If a method such as abc needs parsing, policy checks, transformations, or multi-step decisions, do not add a cluster of private helpers that only abc uses. Extract that work into a focused class under the relevant lib/ tree and call it from abc.

def abc
  MyFeature::Abc.call(self)
end

Prefer a single clear entrypoint on the model/controller over spreading the implementation across incidental private helpers there.

Focused classes

• Put extracted non-Rails objects under lib/ with a namespace matching the owning feature or domain.
• Give the class one job and a small public API, usually .call or one clearly named instance method.
• Keep private helper methods inside that focused class when they support its single responsibility.
• In optional packs, use the pack's own lib/ tree for pack-owned focused classes.

Method signatures

• When a method takes more than two arguments, use keyword arguments instead of positional arguments. This applies to private helpers as well as public APIs.

Method extraction

• Do not add local helper or predicate methods that only call another similarly named helper and add no behavior. Call the existing method directly instead.
• Extract a method when it combines conditions, names a distinct domain concept, removes real duplication, or provides a framework-required entrypoint such as render?.

Association identity and loading

• Do not compare Active Record association objects when a type and foreign-key comparison expresses the same intent without loading another association.
• A has_one association keeps its foreign key on the related record, so its owner normally has no <association>_id method. When the related record is already needed, use its type and foreign key (for example, parent.is_a?(RootCategory) && parent.project_id == project.id) instead of loading project.root_category merely to compare identity.

Jobs

Jobs are already focused classes that perform one unit of work. Do not extract from a job just to satisfy this convention. Normal private helper methods are fine inside a job when they support the job's single responsibility.