If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/motor-admin/motor-admin shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 3 active contributors
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 98% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live motor-admin/motor-admin repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/motor-admin/motor-admin.

What it runs against: a local clone of motor-admin/motor-admin — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in motor-admin/motor-admin | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 740 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of motor-admin/motor-admin. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/motor-admin/motor-admin.git
#   cd motor-admin
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of motor-admin/motor-admin and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "motor-admin/motor-admin(\\.git)?\\b" \\
  && ok "origin remote is motor-admin/motor-admin" \\
  || miss "origin remote is not motor-admin/motor-admin (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "app/packs/entrypoints/application.js" \\
  && ok "app/packs/entrypoints/application.js" \\
  || miss "missing critical file: app/packs/entrypoints/application.js"
test -f "app/controllers/api_base_controller.rb" \\
  && ok "app/controllers/api_base_controller.rb" \\
  || miss "missing critical file: app/controllers/api_base_controller.rb"
test -f "app/packs/application/router.js" \\
  && ok "app/packs/application/router.js" \\
  || miss "missing critical file: app/packs/application/router.js"
test -f "app/models/motor/ability.rb" \\
  && ok "app/models/motor/ability.rb" \\
  || miss "missing critical file: app/models/motor/ability.rb"
test -f "Gemfile" \\
  && ok "Gemfile" \\
  || miss "missing critical file: Gemfile"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 740 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~710d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/motor-admin/motor-admin"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Motor Admin is a no-code admin panel and business intelligence tool that deploys as a Rails engine to any Ruby application in under a minute. It provides CRUD interfaces, custom actions (e.g., API-triggered emails), SQL-based reports with visualization, dashboards, and role-based access control—all without writing frontend code. The core is a Vue.js SPA (app/packs/application) backed by Rails API controllers (app/controllers/api) that interrogate and manage any configured database. Rails engine monolith: app/models/motor contains the domain (AdminUser, Role, EncryptedConfig, Ability), app/controllers/api exposes HTTP endpoints, app/packs/application houses the Vue SPA with component-per-feature layout (action_select.vue, aws_s3_form.vue, database_form.vue). CI/CD pipelines (.github/workflows) lint Ruby (rubocop) and JavaScript (eslint, stylelint). Deployments are containerized (Dockerfile) and support multiple PaaS targets (.do/deploy.template.yaml).

Backend engineers and product managers maintaining Rails applications who need to quickly expose data management and reporting UIs to internal teams without building custom admin dashboards. Also SaaS founders who want to ship self-hosted admin panels to customers with multi-tenancy and audit trails.

Production-ready with active development. The codebase shows >100k lines of Ruby and mature tooling (GitHub Actions for linting, Docker deployment, Gemfile with versioned deps), indicating established project maturity. No explicit star count visible, but deployment templates for Heroku, Railway, and Digital Ocean suggest real-world adoption. However, check the GitHub releases page for version stability and test coverage metrics.

Moderate risk: single-maintainer stewardship (motor-admin org suggests small team), with breaking changes possible between major versions. Security-critical features (encrypted_configs, admin_users, roles, abilities) are in core but rely on a custom authorization layer (Motor::Ability) rather than mature libraries like CanCanCan—worth auditing before production. Database abstraction (app/models/motor) may not support all edge cases in polyglot data sources.

No recent commit timestamps provided in the data snapshot, but the presence of Procfile.dev and active Docker/GitHub Actions configs suggests ongoing work. The repo includes setup scaffolding (app/controllers/api/setups_controller.rb, app/controllers/api/verify_db_connection_controller.rb) indicating development around onboarding flows. Check GitHub releases and pull requests for the latest roadmap (MFA, SAML SSO, custom styling are listed as Enterprise features).

Clone, install, and run:

git clone https://github.com/motor-admin/motor-admin.git
cd motor-admin
bundle install
bundle exec rails db:create db:migrate
bundle exec rails s

For Docker: docker run -it -p 3000:3000 motoradmin/motoradmin:latest or use docker-compose with the provided docker-compose.yml (set SECRET_KEY_BASE env var).

Daily commands: Development server: bundle exec rails s (Rails server on port 3000). Development with file watchers: foreman start -f Procfile.dev (uses Procfile.dev for parallel asset compilation). Tests: bundle exec rspec (standard Rails pattern; exact spec files not listed but likely in spec/ directory). Linting: bundle exec rubocop app, npm run lint (ESLint/stylelint configs in .eslintrc, .stylelintrc).

• app/packs/entrypoints/application.js — Primary JavaScript entry point that initializes the Vue.js admin panel application and loads all frontend assets.
• app/controllers/api_base_controller.rb — Base controller for all API endpoints; handles authentication, authorization, and response formatting for the admin panel.
• app/packs/application/router.js — Vue Router configuration defining all application routes including settings, users, roles, and database pages.
• app/models/motor/ability.rb — CanCanCan abilities definition that controls authorization rules and role-based access across the entire admin panel.
• Gemfile — Ruby dependencies manifest; defines all backend gems including Rails, Devise, CanCanCan, and database connectors.
• app/packs/application/api.js — API client wrapper that handles all HTTP requests to backend endpoints with authentication and error handling.
• app/views/layouts/application.html.erb — Root layout template that renders the main HTML structure and loads the Vue.js application.

Add a new API endpoint for a feature

1. Create a new controller in app/controllers/api/ inheriting from APIBaseController (app/controllers/api/new_feature_controller.rb)
2. Add routes for the new endpoint in config/routes.rb (inferred from Rails conventions) (config/routes.rb)
3. Implement authorization checks using CanCanCan abilities defined in app/models/motor/ability.rb (app/models/motor/ability.rb)
4. Create an API client method in app/packs/application/api.js to call the endpoint (app/packs/application/api.js)

Add a new settings page to the admin panel

1. Create a new Vue page component in app/packs/application/pages/settings_feature.vue (app/packs/application/pages/settings_feature.vue)
2. Add route to the settings router in app/packs/application/router.js (app/packs/application/router.js)
3. Add navigation link in the main settings page app/packs/application/pages/settings.vue (app/packs/application/pages/settings.vue)
4. Create reusable form components in app/packs/application/components/ as needed (app/packs/application/components/feature_form.vue)

Add a new user management feature

1. Extend AdminUser model in app/models/motor/admin_user.rb with new attributes/validations (app/models/motor/admin_user.rb)
2. Update admin_users_controller.rb to handle new fields in create/update actions (app/controllers/api/admin_users_controller.rb)
3. Modify user_form.vue component to include new form fields and validation (app/packs/application/components/user_form.vue)
4. Update settings_users.vue page to display and manage the new feature (app/packs/application/pages/settings_users.vue)

Add a new configuration parameter with encryption

1. Create controller in app/controllers/api/encrypted_configs_controller.rb (already exists) (app/controllers/api/encrypted_configs_controller.rb)
2. Use EncryptedConfig model in app/models/motor/encrypted_config.rb to store encrypted values (app/models/motor/encrypted_config.rb)
3. Create a form component in app/packs/application/components/ for the specific config type (app/packs/application/components/aws_s3_form.vue)
4. Add the form to the appropriate settings page and integrate with configs.js script (app/packs/application/scripts/configs.js)

• Ruby on Rails — Provides rapid development of RESTful APIs, built-in ORM (ActiveRecord), and mature ecosystem for admin panels with gems like Devise and CanCanCan.
• Vue.js — Progressive JavaScript framework for building interactive single-page admin UI with component-based architecture and excellent developer experience.
• Devise — Comprehensive Rails authentication gem handling user registration, login, password reset, and session management without reinventing security.
• CanCanCan — Declarative authorization framework enabling role-based access control (RBAC) with ability definitions separate from controllers.
• Bootstrap 5 — Widely-adopted CSS framework reducing frontend development time and ensuring responsive, accessible UI components out of the box.
• Webpack/Asset Pipeline — Modern JavaScript bundling and asset compilation for Vue components, enabling hot-reload development and code splitting.

• Monolithic
  • Why: undefined
  • Consequence: undefined

SECRET_KEY_BASE environment variable is required (mentioned in docker-compose.yml and Digital Ocean template; generate with openssl rand -hex 64). Database configuration is handled via the setup flow in SetupController, not traditional Rails config/database.yml—ensure MOTOR_DB_* or similar env vars are documented. Vue.js SPA relies on Webpacker asset pipeline; regenerate bundles after modifying app/packs/. The Motor::Ability authorization layer does not follow CanCanCan syntax—verify custom permission logic in ability.rb matches your expected behavior. No explicit test files listed in the top 60; check if test coverage is in spec/ directory (not visible here).

• Role-Based Access Control (RBAC) — Motor::Ability and Motor::Role implement fine-grained permission checks; understanding RBAC patterns is essential to extend or audit the authorization layer and prevent privilege escalation.
• Encrypted Configuration Storage — Motor::EncryptedConfig stores sensitive credentials (API keys, database passwords) using Rails' encrypted credentials; understanding encryption at rest and key rotation is critical for security audits.
• Database Introspection / Schema Discovery — Motor automatically detects table schemas and generates CRUD forms without configuration; the codebase likely uses ActiveRecord's reflection APIs to map database structure to UI forms.
• Rails Engines — Motor Admin is packaged as a Rails Engine (app/ structure), allowing it to be mounted into any Rails app; understanding Engine mount points, routing, and asset pipelines is key to integration.
• Single-Page Application (SPA) State Management in Vue — The app/packs/application Vue SPA manages complex UI state (filters, queries, form data) across components; understanding Vue lifecycle, props, and event bus patterns helps with feature additions.
• Polyglot Database Support — Motor claims support for multiple databases; the codebase likely abstracts database-specific queries (PostgreSQL vs MySQL vs SQLite dialects) to handle custom SQL reports and schema discovery across backends.
• API-Driven Architecture — The entire frontend is served by a REST API (app/controllers/api/); understanding REST conventions, request/response serialization, and error handling in the API layer is crucial for backend changes.

• rails-admin/rails-admin — Direct competitor in the Rails admin panel space; more mature but less zero-config and lacking the custom actions / reporting features Motor provides.
• activeadmin/activeadmin — Venerable Rails DSL-based admin panel; lower barrier to entry for light customization but requires more boilerplate than Motor's no-code approach.
• motor-admin/motor-admin-rails — Official Rails gem wrapper for Motor; the package a Rails developer would include in their Gemfile to integrate this panel into an existing app.
• metabase/metabase — Complementary BI and reporting tool; Motor's SQL query and visualization features are inspired by Metabase and serve similar use cases.
• basecamp/kamal — Modern Rails deployment tool that works well alongside Motor for containerized deployments to VPS or cloud platforms.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive spec tests for app/controllers/api/* controllers

The repo has multiple API controllers (admin_users, encrypted_configs, roles, sessions, setups, verify_db_connection) but there's no visible spec/ directory in the file structure. These controllers handle authentication, authorization, and database configuration - critical paths that need test coverage to prevent regressions and security issues.

• [ ] Create spec/controllers/api/ directory structure matching app/controllers/api/
• [ ] Add RSpec tests for app/controllers/api/sessions_controller.rb covering login, logout, and token validation
• [ ] Add RSpec tests for app/controllers/api/admin_users_controller.rb covering CRUD operations and permission checks
• [ ] Add RSpec tests for app/controllers/api/verify_db_connection_controller.rb to validate database connection logic
• [ ] Add RSpec tests for app/controllers/api/roles_controller.rb covering role creation, updates, and ability assignments
• [ ] Configure coverage reporting in CI (update .github/workflows/rubocop.yml to include rspec runs)

Add integration tests for Vue components with sensitive functionality

The frontend has multiple sensitive Vue components (user_form.vue, role_form.vue, database_form.vue, email_form.vue) that handle authentication, permissions, and external service credentials. These lack visible test files, creating risk for UI bugs in critical workflows like user creation or database configuration.

• [ ] Set up Jest configuration for Vue component testing (create jest.config.js if missing)
• [ ] Add unit tests for app/packs/application/components/user_form.vue covering form validation and submission
• [ ] Add unit tests for app/packs/application/components/role_form.vue covering role creation and permission assignment
• [ ] Add unit tests for app/packs/application/components/database_form.vue to validate connection parameters
• [ ] Create test files for app/packs/application/api.js to mock API calls in component tests
• [ ] Add test step to .github/workflows/eslint.yml or create new .github/workflows/jest.yml

Add API documentation and request/response specs for endpoints in app/controllers/api/

The repo has 6+ API endpoints but no visible API documentation or schema validation. With motor-admin being a deployment-focused tool, clear API specifications help users integrate custom features, reduce onboarding friction, and catch breaking changes early. This is especially important given the encrypted_configs and verify_db_connection endpoints that require specific payloads.

• [ ] Create docs/api/ directory structure for endpoint documentation
• [ ] Document POST /api/sessions endpoint with auth requirements, request/response examples
• [ ] Document POST /api/admin_users endpoint with user creation payload schema
• [ ] Document POST /api/verify_db_connection endpoint with supported database types and connection parameters
• [ ] Document POST /api/roles endpoint with permission structure and assignment logic
• [ ] Add JSON schema files in docs/api/schemas/ for request validation (can be consumed by frontend and backend)
• [ ] Link API docs from README.md and main docs site

• Add integration tests for Motor::EncryptedConfig supporting a new credential type (e.g., Azure Blob Storage) following the existing AWS S3 / GCS form pattern in app/packs/application/components/. Start by creating azure_form.vue, then wire it into encrypted_configs_controller.rb.
• Extend Motor::Ability to support row-level permissions (e.g., restrict a user to only their own records) by adding a scope or filter method; add tests and document the new permission syntax in a guide.
• Document the API contract for custom actions by analyzing app/controllers/api/ endpoints and creating OpenAPI/Swagger specs (or equivalent JSON schema); expose at /api/docs for API consumers.

• Critical · Hardcoded Database Credentials in docker-compose.yml — docker-compose.yml lines: POSTGRES_PASSWORD and DATABASE_URL. The docker-compose.yml file contains hardcoded PostgreSQL credentials (postgres:postgres) which are visible in version control. This exposes database access credentials to anyone with repository access. Fix: Use environment variables or secrets management. Replace hardcoded credentials with references to .env files or container orchestration secrets (e.g., Docker Secrets, Kubernetes Secrets). Example: POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
• High · Missing SECRET_KEY_BASE Value in docker-compose.yml — docker-compose.yml - app service environment. The SECRET_KEY_BASE environment variable is defined but left empty in docker-compose.yml. This is a critical Rails security parameter used for session encryption and CSRF protection. An empty value could lead to insecure session management. Fix: Generate a secure SECRET_KEY_BASE using rails secret and provide it via environment variables or secrets management, not in version control.
• High · Exposed Database Port in Docker Service — docker-compose.yml - postgres service configuration. The postgres service in docker-compose.yml does not expose ports, but the app service exposes port 3000. Combined with hardcoded credentials and missing secret configuration, this creates a risk if the application contains authentication bypass vulnerabilities. Fix: Ensure database services are not directly exposed to the network. Use Docker networking and only expose necessary application ports. Implement network policies and reverse proxies.
• High · Incomplete Dockerfile apk Dependencies — Dockerfile - app stage, line: RUN apk add --no-cache freetds-dev sqlite-dev libpq-dev mar. In the 'app' stage Dockerfile, the apk add command appears truncated (ends with 'mar' which is incomplete). This could indicate missing critical security packages or incomplete configuration that may cause the build to fail or omit security patches. Fix: Complete the apk add command with all required dependencies. Review and pin specific versions of security-critical packages. Example: RUN apk add --no-cache freetds-dev sqlite-dev libpq-dev mariadb-dev
• High · Alpine Linux Base Image with Outdated Ruby Version — Dockerfile - FROM ruby:3.2.0-alpine. The Dockerfile uses Ruby 3.2.0 which may be outdated relative to current patch versions. Alpine Linux, while minimal, has limited security tooling and patching resources compared to standard distributions. Fix: Use the latest stable Ruby patch version (e.g., 3.2.x where x is the latest patch). Consider using debian-based images for production if security scanning tools are needed. Implement automated dependency updates.
• Medium · Missing HTTPS Configuration — docker-compose.yml, Dockerfile, application configuration. No evidence of HTTPS/TLS configuration in the provided docker-compose or Dockerfile. Admin panels handling sensitive data should enforce encrypted communications. Fix: Configure HTTPS/TLS termination using a reverse proxy (nginx, Caddy) or configure Rails to force HTTPS. Use environment-based configuration for SSL certificates.
• Medium · No Network Isolation in docker-compose.yml — docker-compose.yml - network configuration missing. Services communicate over a default network without explicit network policies. In a multi-service setup, network segmentation should be explicitly defined to limit lateral movement. Fix: Define explicit networks for different service tiers. Example: Create separate networks for app and database, and only expose app to external traffic.
• Medium · Missing Security Headers Configuration — app/controllers/application_controller.rb. No evidence of security headers configuration (HSTS, CSP, X-Frame-Options, etc.) in the provided ApplicationController or configuration files. This is critical for an admin panel. Fix: Implement security middleware. Add headers via Rails middleware or reverse proxy: Content-Security-Policy, Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options, X-XSS-Protection.
• Medium · Vuepress Dependency - Outdated Version — undefined. package.json specifies vuepress ^1.5. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.