Design Principles

Five pillars, zero compromise

Every decision in Thecore traces back to one of these principles. Together they eliminate entire categories of work.

⚡

Convention over configuration

Files land in predictable places with predictable names. Every developer reads every Thecore project without a README.

🤖

High automation

A single context menu click triggers migrations, model moves, concern scaffolding, and i18n entries simultaneously.

📐

High standardisation

Every ATOM has the same internal layout. Every model has the same three concern files. Scale to ten ATOMs feels like adding the second.

🔍

Introspection-based

The API and admin UI configure themselves at runtime by reading your model structure. Add a field to a migration and it appears everywhere, automatically.

🎯

Sensible defaults

A new model is visible in the admin UI, serialised in the API, and has a custom endpoint stub — before you write a single line of business logic.

Core ATOMs

Two engines.
Everything else follows.

Thecore ships with two foundational ATOMs that every application inherits. Every feature ATOM you create builds on top of them.

REST API

model_driven_api

Turns any Rails model into a fully-documented REST API endpoint with zero controller code. The JSON shape is driven entirely by the model's json_attrs configuration, read at runtime via introspection.

🔌

Zero-boilerplate REST endpoints

index, show, create, update, destroy — all live the moment the concern is included. No routes file to edit, no controller to write.

🎛️

Declarative JSON serialisation

Use json_attrs with only:, except:, methods:, include: to shape the response with no serialiser class.

🔗

Custom non-CRUD endpoints

The Endpoints::ModelName concern lets you add custom actions with inline OpenAPI/Swagger documentation.

📄

Auto-generated OpenAPI docs

API schema is derived from the model definition and json_attrs. Your API is always self-describing.

🔐

Token-based authentication

Integrated with Devise. Every endpoint is protected by default. Scoped access via CanCan ability rules.

concerns/api/vehicle.rb

module Api::Vehicle
  extend ActiveSupport::Concern
  included do
    cattr_accessor :json_attrs
    self.json_attrs = ::ModelDrivenApi.smart_merge(
      (json_attrs || {}), {
        only: [:id, :plate, :make, :year, :status],
        include: { assignments: { only: [:id, :driver] } }
      }
    )
  end
end
          

Admin UI

thecore_ui_rails_admin

Wires rails_admin, Devise, and CanCan into a coherent, permission-aware admin interface. Model configuration is done in the RailsAdmin::ModelName concern, co-located with the model itself.

🖥️

Auto-wired admin panel

Every model with the concern appears in the sidebar with correct navigation label and icon, immediately after the server starts.

🔑

Authentication out of the box

Devise is pre-configured. An admin user is created during db:seed. Login, session, and token reset work without configuration.

🛡️

Role-based authorisation

CanCan ability classes are auto-loaded from each ATOM's Abilities::AtomName. Rules compose across ATOMs.

📋

Configurable list, edit, show views

Customise every aspect of the admin UI inside the concern, with no separate config file. The configuration lives next to the model.

⚡

Root & member actions

Generate custom admin pages (dashboards) and per-row buttons with ActionCable support for real-time updates — via a single VS Code command.

concerns/rails_admin/vehicle.rb

module RailsAdmin::Vehicle
  extend ActiveSupport::Concern
  included do
    rails_admin do
      navigation_label I18n.t('admin.fleet.label')
      navigation_icon  'fa fa-car'
      list do
        field :plate
        field :make
        field :status
        field :created_at
      end
    end
  end
end
          

How it works

From empty folder
to running API

Every step is a single VS Code right-click command. No terminal commands to memorise. No documentation to consult.

Open in devcontainer

Clone the repository and reopen in the pre-built Docker devcontainer. Ruby, Rails, Node, PostgreSQL drivers, and all Thecore tooling are already installed. Ctrl+Shift+P → Dev Containers: Reopen in Container

Create the application

Right-click the project folder → Thecore 3: Create an App. Thecore runs rails new, adds all gems, runs every generator, seeds the database, and commits — automatically.

Create an ATOM for your domain

Right-click the project folder → Thecore 3: Create an ATOM. Name it, fill in the metadata. The full Rails engine structure is scaffolded and wired into the main app's Gemfile.

Add a model

Right-click the ATOM folder → Thecore 3: Add a Model. Enter the model name and fields. The migration, model file, and all three concerns (Api::, RailsAdmin::, Endpoints::) are created and wired together.

Run the server — you're done

Start rails s. The REST API is live at /api/v2/your_models. The admin interface is live at /app. No additional configuration needed.

Comparison

Thecore vs. vanilla Rails

Everything you would otherwise build by hand, Thecore generates and maintains for you.

Capability	Vanilla Rails	Thecore
REST API from a model	Controller + routes + serialiser	✓ Include Api::Model — done
Admin interface	Manual rails_admin config file	✓ Include RailsAdmin::Model — done
Authentication	Configure Devise manually	✓ Pre-configured, seeded admin user
Authorisation	Write Ability class from scratch	✓ Stub generated per ATOM, auto-loaded
Background jobs	Add Sidekiq, configure queues	✓ Sidekiq config generated with sensible defaults
Custom API actions	New controller + route + docs	✓ Endpoints::Model with OpenAPI inline
Admin dashboard pages	Custom controller, view, JS, CSS	✓ One command → root action with ActionCable
Modular feature isolation	Namespace conventions by hand	✓ Full Rails engine per domain, as a gem
CI/CD pipeline	Write from scratch	✓ GitLab CI + GitHub Actions generated on create
Reuse across projects	Copy-paste or extract a gem manually	✓ git submodule add — ATOM includes schema
i18n support	Add locale files manually	✓ en.yml and it.yml stubs generated per action

Out of the Box

Built-in integrations.
Zero boilerplate.

Enterprise SSO, real-time WebSockets, background jobs, and advanced search — all active with a handful of environment variables or a database record. Click any card to read the full docs.

🏢

Auth

LDAP / Active Directory

Authenticate users against any LDAP server or Microsoft AD. Configure multiple servers with priority order — entirely through the ldap_servers table. No code changes required. Supports role mapping from AD groups and scheduled user sync via ldap:sync_users.

🔵

Auth

Google OAuth 2

Sign in with Google via OmniAuth. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET — a Sign in with Google button appears on the login page automatically. Users are created on first login and linked to their existing account by email.

🪟

Auth

Microsoft Entra ID

Azure AD / Entra ID enterprise SSO via OpenID Connect. Set ENTRA_CLIENT_ID, ENTRA_CLIENT_SECRET, and ENTRA_TENANT_ID to enable organisation-wide sign-in. Scopes include openid, profile, email, and User.Read.

⚡

Real-time

WebSocket / ActionCable

Real-time push via ActionCable's ActivityLogChannel. Every model persist event (create, update, destroy) broadcasts automatically. Topic-based routing lets any ATOM send custom messages to connected clients — from both Ruby and JavaScript.

🔐

Auth

JWT Stateless Auth

Every API request is authenticated by a JWT token with sliding expiration — a fresh token is issued with each successful response. Works with any HTTP client, mobile app, or IoT device. Protected by default on every endpoint via Devise + CanCan.

⚙️

Background

Sidekiq Background Jobs

Sidekiq is pre-configured with sensible queue defaults. Scheduled LDAP user import (BackgroundLdapImportJob), custom workers, and retry logic work without any additional setup. Backed by KeyDB / Redis already in the devcontainer.

📄

API

OpenAPI / Swagger

The full API schema is derived at runtime from your model definitions and json_attrs. Hit GET /api/v2/info/swagger for a live OpenAPI spec. No annotations to write, no spec to maintain — it stays in sync automatically.

🔎

API

Ransack Search & Filter

Every model endpoint supports Ransack-style query parameters (q[field_predicate]=value). Complex multi-field filters, flexible sorting, and pagination — with zero controller code. Client-driven field selection with a[only] / a[except] gives full API shape control.

📎

Storage

ActiveStorage File Uploads

File attachments work out of the box via multipart FormData uploads. Attach files to any model without extra gems or storage configuration changes. Both has_one_attached and has_many_attached are fully supported through the REST API.

🗄️

API

Safe Raw SQL Endpoint

Need a complex report query? POST /api/v2/raw/sql accepts SELECT-only statements and returns results as JSON. Read-only guard is enforced server-side. Combine with json_agg for nested result sets without a custom endpoint.

Trusted in Production

Sponsors & real-world
deployments

Companies that have built their core business on Thecore — proving the framework in demanding, long-running enterprise environments.

Frontend Integration

Build React frontends
on top of Thecore.

The thecore-auth npm package gives React applications a complete authentication layer, JWT client, routing guards, modal system, and ActionCable integration — all pre-wired for Thecore backends.

⚛️

Walkthrough

React Frontend Walkthrough

Build a complete Fleet Management React app from scratch. Covers project setup, JWT authentication, private and admin-only routes, full CRUD with modals, server-side Ransack search, pagination, and live updates via ActionCable.

Start the walkthrough →

📘

Reference

React Frontend Reference

Full API reference for thecore-auth: provider architecture, useAuth, useConfig, useAlert, useModal, Axios instance, route guards, CSS variables, IndexedDB utilities, and ActionCable setup.

Build production-gradeRails backends without the boilerplate

Five pillars, zero compromise

Convention over configuration

High automation

High standardisation

Introspection-based

Sensible defaults

Two engines.Everything else follows.

model_driven_api

Zero-boilerplate REST endpoints

Declarative JSON serialisation

Custom non-CRUD endpoints

Auto-generated OpenAPI docs

Token-based authentication

thecore_ui_rails_admin

Auto-wired admin panel

Authentication out of the box

Role-based authorisation

Configurable list, edit, show views

Root & member actions

One thin app.Many self-contained ATOMs.

From empty folderto running API

Open in devcontainer

Create the application

Create an ATOM for your domain

Add a model

Run the server — you're done

Thecore vs. vanilla Rails

Built-in integrations.Zero boilerplate.

LDAP / Active Directory

Google OAuth 2

Microsoft Entra ID

WebSocket / ActionCable

JWT Stateless Auth

Sidekiq Background Jobs

OpenAPI / Swagger

Ransack Search & Filter

ActiveStorage File Uploads

Safe Raw SQL Endpoint

Sponsors & real-worlddeployments

Build React frontendson top of Thecore.

React Frontend Walkthrough

React Frontend Reference

Start building in minutes,not days.

Build production-grade
Rails backends without the boilerplate

Two engines.
Everything else follows.

One thin app.
Many self-contained ATOMs.

From empty folder
to running API

Built-in integrations.
Zero boilerplate.

Sponsors & real-world
deployments

Build React frontends
on top of Thecore.

Start building in minutes,
not days.