CommandTower

CommandTower is a mountable Rails engine that provides shared platform capabilities for host applications: JWT authentication, RBAC authorization, account/Me surfaces, messaging HTTP (inbox, preferences, endpoints), admin announcements, and shared test factories.

Hosts mount the engine, configure secrets and product policy, and build product features on top—without re-implementing platform foundations.

The engine is opinionated and configurable. Architecture follows a stable layer map (workflows orchestrate; services implement capabilities). See Architecture.

# Gemfile
gem "command_tower"

bundle install
bin/rails command_tower:install
bin/rails db:migrate
bin/rails command_tower:doctor

Full install, upgrade, configuration, and troubleshooting: Initializing CommandTower.

After install, complete RBAC, feature gates, and a Me smoke check: Host integration guide (start here for a new Rails host).

Controller / Job → Workflow → Shared Sequences / Services → Models & Clients

• Controllers are transport adapters (one workflow per action).
• Workflows orchestrate a business action.
• Services (including CommandTower::ServiceBase) implement one capability.

See Architecture and ServiceBase.

See Initializing CommandTower for:

• command_tower:install / install:migrations
• Configure generator flags (SKIP_CONFIGURE, SKIP_MOUNT, FORCE)
• Schema ownership (AD-SCH-01)
• Secrets and doctor checks
• Existing customized hosts

Shared factories for hosts:

require "command_tower/testing"
CommandTower::Testing.install!

Details: Testing with CommandTower.

Engine HTTP coverage lives primarily under spec/requests/. Residual journey coverage may remain under spec/integration_test/.

Engine routes cover Auth, Me (profile, inbox, preferences, phone, Pushover), and Admin messaging announcements. Index: Controllers. Contracts: API reference.

Core models such as User and UserSecret are available for hosts to use and reopen carefully. See Models.

Authentication establishes identity (401 when it fails).

• Engine controllers use authenticate_request! / authorize_request! (Authentication/Authorization boundaries) and return the application envelope.

• Host controllers may use provisional before_action :authenticate_user! (failure shapes can differ — see the deep guide).

• Quick start: Authentication

• Deep guide: Authentication & authorization

• Web / SPA cookies: Cookie authentication

Cookie mode supports HttpOnly JWT cookies, SameSite, optional double-submit CSRF, and secure cookies in production.

Authorization establishes permission after authentication (403 when it fails).

Engine defaults ship owner and admin (announcements). Hosts must supply rbac_groups.yml entities for Me/Auth surfaces (fail-closed). Host controllers may use provisional authorize_user! after authenticate_user!.

• Quick start: Authorization
• Deep guide: Authentication & authorization

JWT tokens embed a verifier_token bound to the user. Rotating the verifier invalidates outstanding sessions. See Sensitive changes.

Modern messaging surfaces: Me Inbox consume, Produce / ProduceMany emit, admin announcements. See Messaging.

Pagination helpers are available for controllers and services. See Pagination.

CommandTower::ServiceBase adds logging and argument validation for service classes under workflows. See ServiceBase.

MIT — see MIT-LICENSE.