Appearance
Start Here
Documentation snapshot
| Field | Value |
|---|---|
| Repository | mr-himanshuyadav/brutal-learning |
| Branch inspected | main |
| Commit | 1775c9507205f3c00344a5deed52c61a56acda0f |
| Snapshot date | 2026-08-31 |
| Plugin header version | 4.2.2 |
Runtime Plugin::$version | 3.5.1 |
| PHP | >= 7.4 |
| WordPress | >= 5.8 |
The version mismatch is a confirmed implementation detail and should not be normalized in documentation: the plugin header reports 4.2.2 while includes/Plugin.php defines its runtime version as 3.5.1. See Architecture Notes.
What Brutal Learning actually is
Brutal Learning is a WordPress plugin whose current implementation combines a question bank, hierarchical custom taxonomy system, authenticated REST API, WordPress AJAX web application, practice/session engine, configurable test builder, course delivery/progress tracking, paid-access entitlements through WooCommerce, analytics/mastery state, reporting, notifications, backups and administrative tooling.
The important architectural fact is that this is not a single persistence model. WordPress posts/postmeta are used for selected content objects (bl_course, bl_plan, bl_test), while most domain state is stored in custom tables exposed by Tables, and some user state is compressed into JSON columns in the user vault.
The ten-minute mental model
The key reusable design pattern is thin transport adapters around shared business logic. REST controllers and AJAX handlers generally dispatch into Practice_Manager, Session_Manager, Course_Manager, database classes and utility managers instead of implementing separate domain rules.
Where things live
| Concern | Main implementation | Notes |
|---|---|---|
| Plugin bootstrap | brutal-learning.php, includes/Plugin.php | Composer bootstrap, singleton, hooks |
| Activation/schema | includes/Activator.php | Creates custom tables/FKs/default taxonomies/cron |
| Core DB naming | includes/Database/Tables.php | Canonical qp_ table names |
| Questions | includes/Database/Questions_DB.php, includes/Admin/Views/Question_Editor_Page.php | Group/question/option persistence |
| Practice | includes/Modules/Practice/Practice_Manager.php, includes/Ajax/Practice_Ajax.php, includes/Rest_Api/PracticeController.php | Multiple practice modes |
| Sessions | includes/Modules/Session/Session_Manager.php, includes/Ajax/Session_Ajax.php, includes/Rest_Api/SessionController.php | Lifecycle/finalization |
| Tests | includes/Admin/Meta_Boxes.php, assets/js/test-editor.js | JSON schema V2 builder |
| Courses | includes/Modules/Course/Course_Manager.php, includes/Admin/Meta_Boxes.php, assets/js/course-editor.js | CPT + custom relational structure |
| Access | includes/Utils/User_Access.php, includes/Utils/Vault_Manager.php | Scope, entitlements, course permissions |
| Authentication | includes/Rest_Api/AuthController.php, includes/Modules/Auth/* | JWT + server-side auth sessions + OTP |
| REST | includes/Rest_Api/Router.php | namespace brutallearning/v1 |
| Admin | includes/Admin/* | WordPress admin pages and forms |
| Frontend | includes/Frontend/*, assets/js/*, assets/css/*, templates/* | Shortcode-driven UI |
| WooCommerce | includes/Integrations/WooCommerce_Integration.php | Plans/products → user entitlements |
| Analytics/mastery | includes/Utils/Analytics_Manager.php, Mastery_Engine.php, Vault_Manager.php | Aggregate stats, streaks, SRS/Elo-like calculations |
| Reports | includes/Database/Reports_DB.php, includes/Rest_Api/ReportsController.php | State-machine workflow |
| Backup/restore | includes/Admin/Backup/Backup_Manager.php | ZIP + JSON + media/CPT data |
Task-oriented entry points
| I want to… | Start here |
|---|---|
| Change plugin startup | includes/Plugin.php |
| Change question editing | includes/Admin/Views/Question_Editor_Page.php, assets/js/question-editor.js |
| Change quick edit | includes/Admin/Views/Questions_List_Table.php, assets/js/quick-edit.js |
| Change practice selection | includes/Modules/Practice/Practice_Manager.php |
| Change attempt grading | includes/Modules/Practice/Attempt_Evaluator.php, includes/Modules/Session/Session_Manager.php |
| Change test configuration | includes/Admin/Meta_Boxes.php, assets/js/test-editor.js |
| Change course structure | includes/Admin/Meta_Boxes.php, assets/js/course-editor.js, includes/Modules/Course/Course_Manager.php |
| Change permissions/access scope | includes/Utils/User_Access.php, includes/Utils/Vault_Manager.php |
| Change JWT/OTP login | includes/Rest_Api/AuthController.php, includes/Modules/Auth/* |
| Change the mobile API | includes/Rest_Api/Router.php + corresponding Controller |
| Change web AJAX behavior | includes/Ajax/*, includes/Plugin.php, relevant JS |
| Change course purchase/entitlement behavior | includes/Integrations/WooCommerce_Integration.php, includes/Utils/User_Access.php |
| Change dashboard data | includes/Utils/Dashboard_Manager.php, includes/Rest_Api/DataController.php, assets/js/dashboard.js |
| Change backup/restore | includes/Admin/Backup/Backup_Manager.php, assets/js/backup-restore.js |
| Change global settings | includes/Admin/Views/Settings_Page.php |
| Change REST secret | includes/Admin/Views/Api_Settings_Page.php |
First development task
For a small feature, trace the entire chain before editing:
UI element → JS event → AJAX/REST route → controller/handler → domain manager → DB/table → response → UI state.
For persistence changes also trace activation/migration, restore, deletion and any scheduled recalculation that touches the same entity.
Evidence policy
This portal intentionally does not treat class names, comments or filenames as behavioral proof. Significant implementation claims are tied to the source files that were inspected. Where the repository contains contradictory or migration-era code, the contradiction is called out instead of silently choosing one interpretation.