btrc-hub/backend/AGENTS.md

backend/AGENTS.md

Scope

These rules apply to work under backend/.

This is a Rails API app using Active Record, RSpec, request specs, service objects, representation classes, and version tables for post/tag/wiki history.

Commands

Use commands backed by files and dependencies in this directory:

bin/setup
bin/dev
bin/rails
bin/rake
bin/rubocop
bin/brakeman
bundle exec rspec

Common checks:

bundle exec rspec
bin/rubocop
bin/brakeman

Common Rails commands:

bin/rails db:prepare
bin/rails db:migrate
bin/rails routes
bin/rails server

After backend behavior changes, run the relevant RSpec files. For broad backend changes, run:

bundle exec rspec

If a command cannot be run or fails, report the exact command and failure.

Do not create, modify, or run tests unless the user explicitly asks for test work. When the user asks for tests, keep working and rerun them until they pass or the remaining failure is clearly blocked.

Rails structure

• app/controllers: API controllers.
• app/models: Active Record models and concerns.
• app/representations: JSON response shaping.
• app/services: domain services such as version recorders, wiki commit, YouTube sync, and similarity calculation.
• config/routes.rb: public API routes.
• db/migrate: migrations.
• db/schema.rb: schema snapshot.
• lib/tasks: custom Rake tasks.
• spec: RSpec tests.

Before changing behavior, inspect the matching route, controller, model, service, representation, and spec.

Shared backend systems

Before adding backend behaviour, search the existing backend first. At minimum, check these locations:

• app/controllers
• app/controllers/concerns
• app/models
• app/models/concerns
• app/representations
• app/services
• app/services/*
• app/jobs
• lib
• lib/tasks
• config/initializers

Do not infer commonality from directory names alone. Read the actual responsibility and representative usage sites.

Controller reuse

Before adding logic to a controller, inspect:

• ApplicationController authentication, authorization, BAN, and IP BAN
• existing render and validation-error helpers
• existing param parsing
• controller concerns
• the controller for the same resource
• existing services
• existing representations

Keep controllers focused on:

• authentication and authorization
• parameter intake
• service and model invocation
• HTTP status selection
• representation selection

Do not reimplement these per controller when an existing path already owns them:

• authentication and role checks
• validation error JSON
• URL normalisation
• tag normalisation
• thumbnail handling
• version recording
• complex transactions
• external HTTP fetching
• response representation assembly

Authentication, authorization, and BAN

Treat these as the canonical backend entrypoints:

• ApplicationController#authenticate_user
• current_user
• X-Transfer-Code
• reject_banned_ip_address!
• reject_banned_user!
• gte_member?
• admin?

Do not create feature-local permission services, role comparisons, or header parsing when the existing authentication boundary already owns the behaviour. If the current boundary is insufficient, extend it minimally instead of adding another permission path.

Representations

If an endpoint for the same resource already uses app/representations, do not assemble a separate JSON shape directly inside the controller without first checking the existing representation contract.

Inspect at least:

• PostRepr
• TagRepr
• MaterialRepr
• TheatreRepr
• UserRepr
• WikiPageRepr
• DeerjikistRepr

When a lightweight response is genuinely different in purpose, keep it deliberate and compatible with the surrounding contracts. Do not force every identifier list into a large representation, but do not fork the same resource shape casually either.

Domain services

When work touches multiple models, transactions, external APIs, file handling, history creation, or multi-step workflow, search app/services first.

At minimum, search for existing services in these responsibility areas:

• version recorder and versioning
• wiki commit
• YouTube or Google Drive API client
• material sync or ZIP export
• similarity calculation
• theatre selection or skip finalisation
• metadata, thumbnail, or file processing
• URL normaliser or sanitisation
• import or export
• preview safety or HTTP fetch

Do not create a same-responsibility service under another namespace or another name. If an existing service is close, extend that API minimally instead of wrapping it in a feature-local service.

Versioning

When a feature writes history, snapshots, or restore roots, search the existing versioning path first. At minimum, inspect:

• VersionRecorder
• PostVersionRecorder
• TagVersionRecorder
• TagVersioning
• MaterialVersionRecorder
• NicoTagVersionRecorder
• WikiVersionRecorder

Do not implement history writes in controllers, callbacks, or ad hoc feature services when the recorder layer already owns the transaction boundary and meaning.

Normalisation, sanitisation, and parsing

For URLs, tag names, times, video durations, identifiers, and paths, search the existing normaliser, sanitisation rule, parser, and model-callback path first.

Do not let frontend, controller, service, and model each invent different rules for the same value. Use one canonical normalisation path and keep input validation distinct from pre-persistence normalisation.

External HTTP and URL safety

When fetching external URLs, reuse the existing preview-safety stack. Search at least for:

• URL safety
• redirect validation
• response size limits
• timeouts
• network failure mapping
• HTML metadata extraction
• known-site extraction
• thumbnail fetching

Do not add direct Net::HTTP, Faraday, or equivalent feature-local HTTP code that reimplements SSRF checks, redirect restrictions, size limits, or timeouts. If the current fetcher is insufficient, extend its existing safety contract.

Storage, files, and Active Storage

When handling files, thumbnails, ZIP output, object storage, or Active Storage blobs, inspect existing storage helpers, exporters, thumbnail generators, and checksum helpers first. Do not reimplement the same attach, export path, download, resize, or checksum flow in a controller or one-off service.

Concerns

Do not create controller or model concerns merely because some code is shared. Use a concern only when multiple classes share the same lifecycle, macro, callback, or tightly cohesive behaviour. Utility collections belong in explicit objects or services, not in CommonConcern, SharedMethods, or Utils.

Model boundaries

Model-specific invariants, associations, validations, and normalisation may live in the model. Multi-model workflow, external access, complex transaction flow, and feature orchestration belong in services. Do not hide feature workflow in model callbacks.

Transactions, locking, and race handling

If transactions, locking, idempotency, or race recovery already exist in a service or model method, do not add a second implementation in a controller or new service. Inspect the existing transaction boundary first, avoid wrapping the same operation in needless nested transactions, and handle unique-constraint races according to the target constraint's business meaning.

Ruby style

• Prefer precise, minimal changes.
• Use single quotes unless interpolation or escaping makes double quotes better.
• Do not put a space before Ruby method-call parentheses.
• For render-family method calls, omit parentheses even when passing keyword arguments.
• Never put a line break immediately before ) in Ruby.
• Do not use %w or %i in new Ruby code.
• Never write a Ruby line longer than 99 characters.
• Aim to keep Ruby lines within 79 characters where practical.
• For small Ruby method definitions that take keyword arguments, match the local no-parentheses style when nearby code uses it.
• When an if condition is split across multiple lines and combines clauses with && or ||, wrap the whole condition in parentheses.
• Treat Ruby hash { ... } style and Ruby block { ... } style as separate rules.
• Do not format Ruby hashes like Ruby blocks.
• For Ruby hashes, keep the closing } on the same line as the final pair.
• Keep the first pair on the same line as { by default.
• Short Ruby hashes may stay visually compact across two lines with the first pair kept on the opening line and aligned continuation pairs below it.
• If the hash would exceed the line limit, break after { and indent pairs by 4 spaces.
• Put one logical pair per line when the expression would otherwise become dense.
• For Ruby arrays, never put whitespace or a line break immediately before ].
• Keep the first element on the same line as [ by default.
• If an array would exceed the line limit, break after [ and indent elements by 4 spaces.
• For Ruby blocks, use 2-space indentation for the block body.
• Keep comments short and useful; avoid narrating obvious code.
• Do not add production dependencies without approval.

Authentication and authorization

• Authentication is handled through the X-Transfer-Code header in ApplicationController#authenticate_user.
• current_user is set by looking up User.inheritance_code.
• Do not bypass or weaken the X-Transfer-Code flow unless the task explicitly changes authentication.
• Unauthenticated write actions should return :unauthorized consistently with existing controllers.
• Role checks use User enum roles: guest, member, and admin.
• Use current_user.gte_member? for member-or-admin write permissions where existing controllers do so.
• Use current_user.admin? only for admin-only paths, such as tag child relationship changes.
• Do not replace role checks with looser presence checks.

BAN and IP BAN

• ApplicationController runs these before actions in order:
  • reject_banned_ip_address!
  • authenticate_user
  • reject_banned_user!
• User and IP bans use banned_at, not a boolean banned column.
• User#banned? and IpAddress#banned? check banned_at.present?.
• Do not weaken BAN or IP BAN behavior.
• If changing request authentication or controller before actions, add or update request specs covering banned users and banned IP addresses only when the user explicitly asks for tests.

RSpec

• Prefer RSpec for new backend tests.
• Put API behavior coverage under spec/requests.
• Put model behavior under spec/models.
• Put service behavior under spec/services.
• Put Rake task coverage under spec/tasks.
• spec/rails_helper.rb loads spec/support/**/*.rb.
• Request specs include AuthHelper and JsonHelper.
• AuthHelper#sign_in_as(user) stubs ApplicationController#current_user; use it when matching existing request spec style.
• Add or update request specs for API behavior changes only when the user explicitly asks for tests, especially status codes, permissions, response shape, and version conflict behavior.

Migrations

• Keep migrations and db/schema.rb consistent.
• Use reversible migrations where practical; otherwise define explicit up and down.
• For data backfills inside migrations, follow the existing pattern of defining migration-local ActiveRecord::Base classes with self.table_name.
• Preserve existing indexes, foreign keys, check constraints, and null constraints.
• Be careful with MySQL-specific options already present in migrations, such as after:.
• Do not edit old migrations just to change current behavior unless explicitly requested; add a new migration.

Version tables

• Versioned records include posts, tags, nico tags, and wiki pages.
• Current records have version_no; version tables have positive version_no with unique indexes scoped to the parent record.
• Version event types are create, update, discard, and restore.
• Version rows are readonly through the VersionRecord concern.
• Use the existing recorder services instead of manually inserting version rows in application code:
  • PostVersionRecorder
  • TagVersionRecorder
  • NicoTagVersionRecorder
  • WikiVersionRecorder
  • TagVersioning
• VersionRecorder locks the current record, validates sequence consistency, skips unchanged update snapshots, creates the next version row, and updates the record version_no.
• Do not update versioned records without considering whether a version snapshot must be created.
• For optimistic concurrency paths, preserve base_version_no, force, and merge semantics. Cover conflicts in request specs only when the user explicitly asks for tests.

Domain cautions

• Posts have tag snapshots, parent post implications, original-created ranges, viewed state, and version conflict behavior.
• Tags have canonical names, aliases through TagName, categories, parent implications, discard behavior, and version snapshots.
• Nico tags have separate relation/version behavior; do not treat them like normal editable tags without checking existing code.
• Wiki pages involve page content, revisions/history, version rows, title/tag-name behavior, and diff/restore paths.
• Materials, theatres, and comments have user and permission checks; inspect the controller before changing them.

API responses

• Use representation classes under app/representations when existing endpoints do.
• Keep response keys consistent with existing JSON contracts.
• Frontend code expects camelCase conversion client-side, while Rails params and JSON keys are generally snake_case.
• Preserve existing HTTP status conventions: :unauthorized for no user, :forbidden for insufficient role or banned user, :not_found for missing records, and :unprocessable_entity for validation failures.
• For diagnostic or internal helper JSON, prefer a deliberately light response shape over full representation classes when callers only need identifiers, labels, URLs, or weights.

Active Record performance

• When a controller action serializes nested associations, preload the associations it will touch instead of allowing N+1 queries.
• Be sensitive to N+1 queries in all backend work.
• Avoid introducing N+1 queries, and proactively fix existing N+1 issues when you find them in the code path you are editing.
• When an association may already be preloaded, prefer loaded-association checks that reuse the preloaded data without losing the efficient database path.

Files to avoid in routine work

• Do not inspect or edit tmp/, log/, storage/, vendor/, or dependency directories unless explicitly needed.
• Do not modify generated schema or migration output without the corresponding migration when schema changes are made.