Deploy Bema Learn backend only

Dockerfile

@@ -0,0 +1,24 @@
+FROM wordpress:6-php8.3-apache
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    MARIADB_ROOT_PASSWORD=change-me-root \
+    WORDPRESS_DB_NAME=bemalearn \
+    WORDPRESS_DB_USER=bemalearn \
+    WORDPRESS_DB_PASSWORD=change-me-db \
+    WORDPRESS_DB_HOST=127.0.0.1 \
+    PORT=7860
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends mariadb-server mariadb-client curl ca-certificates \
+    && rm -rf /var/lib/apt/lists/* \
+    && curl -fsSL https://github.com/wp-cli/wp-cli/releases/latest/download/wp-cli.phar -o /usr/local/bin/wp \
+    && chmod +x /usr/local/bin/wp \
+    && a2enmod rewrite headers
+
+COPY bemalearn /var/www/html/wp-content/plugins/bemalearn
+COPY docker-entrypoint-space.sh /usr/local/bin/docker-entrypoint-space.sh
+RUN chmod +x /usr/local/bin/docker-entrypoint-space.sh \
+    && chown -R www-data:www-data /var/www/html/wp-content/plugins/bemalearn
+
+EXPOSE 7860
+ENTRYPOINT ["/usr/local/bin/docker-entrypoint-space.sh"]

README.md

@@ -1,10 +1,11 @@
----
-title: JRNET
-emoji: 🌖
-colorFrom: green
-colorTo: pink
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Bema Learn backend
+
+Backend-only deployment of the Bema Learn assessment API. The Space runs the WordPress plugin with an embedded MariaDB database; the Next.js frontend, Python helper, and assessment evidence are not included.
+
+API base URL:
+
+`/wp-json/bemalearn/v1`
+
+Endpoints include public course listing/detail and authenticated login, earnings, and withdrawals. The seeded assessment accounts are `instructor@example.test` / `assessment123` and `learner@example.test` / `assessment123`.
+
+For production use, set `MARIADB_ROOT_PASSWORD`, `WORDPRESS_DB_PASSWORD`, `WP_ADMIN_PASSWORD`, and `SPACE_HOST` as Space secrets/variables. The embedded database is intended for this deployment and is not a substitute for managed persistent storage.

bemalearn/bemalearn.php

@@ -0,0 +1,61 @@
+<?php
+/**
+ * Plugin Name: Bema Learn Assessment API
+ * Description: A small course platform API. Assessment use only.
+ * Version:     1.0.0
+ * Requires PHP: 7.4
+ * Author:      Bema Integrated Services Ltd
+ */
+
+if (!defined('ABSPATH')) {
+    exit;
+}
+
+define('BEMALEARN_VERSION', '1.0.0');
+define('BEMALEARN_PATH', plugin_dir_path(__FILE__));
+
+require_once BEMALEARN_PATH . 'includes/class-bl-migrations.php';
+require_once BEMALEARN_PATH . 'includes/class-bl-auth.php';
+require_once BEMALEARN_PATH . 'includes/class-bl-courses-controller.php';
+require_once BEMALEARN_PATH . 'includes/class-bl-earnings-controller.php';
+require_once BEMALEARN_PATH . 'includes/class-bl-seeder.php';
+
+register_activation_hook(__FILE__, ['BL_Migrations', 'run']);
+register_activation_hook(__FILE__, ['BL_Seeder', 'seed']);
+
+add_action('rest_api_init', function () {
+    (new BL_Courses_Controller())->register_routes();
+    (new BL_Earnings_Controller())->register_routes();
+});
+
+/**
+ * CORS for the assessment frontend on :3000.
+ *
+ * Kept deliberately simple. Task 4 does not concern this file.
+ */
+add_action('init', function () {
+    $origin = $_SERVER['HTTP_ORIGIN'] ?? '';
+    if (preg_match('#^http://localhost:\d+$#', $origin)) {
+        header('Access-Control-Allow-Origin: ' . $origin);
+        header('Access-Control-Allow-Credentials: true');
+        header('Access-Control-Allow-Methods: GET, POST, OPTIONS');
+        header('Access-Control-Allow-Headers: Content-Type, Authorization, Idempotency-Key');
+    }
+    if (($_SERVER['REQUEST_METHOD'] ?? '') === 'OPTIONS') {
+        status_header(200);
+        exit;
+    }
+});
+
+/**
+ * WP-CLI helper so the environment can be reset between attempts.
+ *
+ *   wp bemalearn reset
+ */
+if (defined('WP_CLI') && WP_CLI) {
+    WP_CLI::add_command('bemalearn reset', function () {
+        BL_Migrations::run();
+        BL_Seeder::seed(true);
+        WP_CLI::success('Bema Learn data reset.');
+    });
+}

bemalearn/includes/class-bl-auth.php

@@ -0,0 +1,72 @@
+<?php
+/**
+ * Minimal bearer-token auth for the assessment.
+ *
+ * Deliberately simple: a signed, expiring token stored in user meta. This is
+ * NOT a production auth design, and Task 4 does not concern this file.
+ */
+
+if (!defined('ABSPATH')) {
+    exit;
+}
+
+class BL_Auth {
+
+    const META_KEY = 'bl_api_token';
+    const TTL      = 86400;
+
+    public static function issue_token($user_id) {
+        $token = wp_generate_password(48, false, false);
+        update_user_meta((int) $user_id, self::META_KEY, [
+            'hash'    => hash('sha256', $token),
+            'expires' => time() + self::TTL,
+        ]);
+        return $token;
+    }
+
+    /**
+     * Resolve the caller from the Authorization header.
+     * Returns a WP_User, or null when absent/invalid/expired.
+     */
+    public static function user_from_request($request) {
+        $header = '';
+        if (is_object($request) && method_exists($request, 'get_header')) {
+            $header = (string) $request->get_header('authorization');
+        }
+        if ($header === '' && isset($_SERVER['HTTP_AUTHORIZATION'])) {
+            $header = (string) $_SERVER['HTTP_AUTHORIZATION'];
+        }
+        if (stripos($header, 'Bearer ') !== 0) {
+            return null;
+        }
+
+        $token = trim(substr($header, 7));
+        if ($token === '') {
+            return null;
+        }
+
+        $hash = hash('sha256', $token);
+
+        $users = get_users([
+            'meta_key'   => self::META_KEY,
+            'number'     => 100,
+            'fields'     => 'ID',
+        ]);
+
+        foreach ($users as $uid) {
+            $stored = get_user_meta((int) $uid, self::META_KEY, true);
+            if (!is_array($stored) || empty($stored['hash'])) {
+                continue;
+            }
+            if (!hash_equals($stored['hash'], $hash)) {
+                continue;
+            }
+            if (!empty($stored['expires']) && $stored['expires'] < time()) {
+                return null;
+            }
+            return get_user_by('id', (int) $uid);
+        }
+
+        return null;
+    }
+}

bemalearn/includes/class-bl-courses-controller.php

@@ -0,0 +1,119 @@
+<?php
+/**
+ * Courses endpoints.
+ *
+ * GET /bemalearn/v1/courses       public list
+ * GET /bemalearn/v1/courses/{id}  public detail
+ *
+ * The authority on what these should return is docs/API-CONTRACT.md.
+ */
+
+if (!defined('ABSPATH')) {
+    exit;
+}
+
+class BL_Courses_Controller {
+
+    const PREVIEW_TTL = 300;
+
+    public function register_routes() {
+        register_rest_route('bemalearn/v1', '/courses', [
+            'methods'             => 'GET',
+            'callback'            => [$this, 'get_courses'],
+            'permission_callback' => '__return_true',
+        ]);
+
+        register_rest_route('bemalearn/v1', '/courses/(?P<id>\d+)', [
+            'methods'             => 'GET',
+            'callback'            => [$this, 'get_course'],
+            'permission_callback' => '__return_true',
+            'args'                => [
+                'id' => [
+                    'required'          => true,
+                    'validate_callback' => function ($v) {
+                        return is_numeric($v) && (int) $v > 0;
+                    },
+                ],
+            ],
+        ]);
+    }
+
+    public function get_courses($request) {
+        global $wpdb;
+
+        $table = $wpdb->prefix . 'bl_courses';
+        $users = $wpdb->users;
+
+        $rows = $wpdb->get_results(
+            "SELECT c.id, c.title, c.price_minor, c.currency,
+                    c.enrolment_count, c.average_rating,
+                    c.is_published, c.published_at,
+                    u.display_name AS instructor_name
+               FROM {$table} c
+               LEFT JOIN {$users} u ON u.ID = c.instructor_id
+              WHERE c.is_published = 1
+              ORDER BY c.published_at DESC, c.id DESC"
+        );
+
+        $courses = [];
+        foreach ((array) $rows as $row) {
+            $courses[] = $this->shape($row);
+        }
+
+        return new WP_REST_Response([
+            'courses'                 => $courses,
+            'previewExpiresInSeconds' => self::PREVIEW_TTL,
+        ], 200);
+    }
+
+    public function get_course($request) {
+        global $wpdb;
+
+        $id    = (int) $request->get_param('id');
+        $table = $wpdb->prefix . 'bl_courses';
+        $users = $wpdb->users;
+
+        $row = $wpdb->get_row($wpdb->prepare(
+            "SELECT c.*, u.display_name AS instructor_name
+               FROM {$table} c
+               LEFT JOIN {$users} u ON u.ID = c.instructor_id
+              WHERE c.id = %d",
+            $id
+        ));
+
+        // An unpublished course is treated as absent. A 403 here would confirm
+        // that the course exists, which is itself a disclosure.
+        if (!$row || !(int) $row->is_published) {
+            return new WP_Error('not_found', 'Course not found.', ['status' => 404]);
+        }
+
+        $shaped = $this->shape($row);
+        $shaped['description'] = $row->description;
+        $shaped['lessonCount'] = (int) $row->lesson_count;
+
+        return new WP_REST_Response($shaped, 200);
+    }
+
+    /**
+     * Turn a database row into the contract shape.
+     *
+     * enrolmentCount and averageRating are nullable in the contract: null means
+     * "not yet counted", which is not the same as a measured zero. They are
+     * cast only when they carry a value.
+     */
+    private function shape($row) {
+        return [
+            'id'             => (int) $row->id,
+            'title'          => $row->title,
+            'instructorName' => $row->instructor_name,
+            'priceMinor'     => (int) $row->price_minor,
+            'currency'       => $row->currency,
+            'enrolmentCount' => $row->enrolment_count === null ? null : (int) $row->enrolment_count,
+            'averageRating'  => $row->average_rating === null ? null : (float) $row->average_rating,
+            'publishedAt'    => $row->published_at
+                ? gmdate('c', strtotime($row->published_at))
+                : null,
+            'isPublished'    => (bool) $row->is_published,
+        ];
+    }
+}

bemalearn/includes/class-bl-earnings-controller.php

@@ -0,0 +1,238 @@
+<?php
+/**
+ * Earnings and withdrawals.
+ *
+ * GET  /bemalearn/v1/me/earnings      instructor only
+ * POST /bemalearn/v1/me/withdrawals   instructor only
+ *
+ * These endpoints move money. The authority on their behaviour is
+ * docs/API-CONTRACT.md.
+ */
+
+if (!defined('ABSPATH')) {
+    exit;
+}
+
+class BL_Earnings_Controller {
+
+    const MINIMUM_WITHDRAWAL_MINOR = 50000;
+
+    public function register_routes() {
+        register_rest_route('bemalearn/v1', '/me/earnings', [
+            'methods'             => 'GET',
+            'callback'            => [$this, 'get_earnings'],
+            'permission_callback' => [$this, 'check_instructor'],
+        ]);
+
+        register_rest_route('bemalearn/v1', '/me/withdrawals', [
+            'methods'             => 'POST',
+            'callback'            => [$this, 'create_withdrawal'],
+            'permission_callback' => [$this, 'check_instructor'],
+            'args'                => [
+                'amountMinor' => [
+                    'required'          => true,
+                    'validate_callback' => function ($v) {
+                        // Money is an integer in minor units, and a withdrawal
+                        // is strictly positive. Rejects strings, floats and
+                        // negatives with a 400 before anything reaches the DB.
+                        if (!is_int($v) && !(is_string($v) && ctype_digit($v))) {
+                            return new WP_Error(
+                                'rest_invalid_param',
+                                'amountMinor must be a positive integer in minor units.',
+                                ['status' => 400]
+                            );
+                        }
+                        return (int) $v > 0;
+                    },
+                ],
+                'payoutReference' => [
+                    'required'          => true,
+                    'validate_callback' => function ($v) {
+                        // Must fit the VARCHAR(64) idempotency column.
+                        return is_string($v)
+                            && $v !== ''
+                            && strlen($v) <= 64
+                            && preg_match('/^[A-Za-z0-9_-]+$/', $v) === 1;
+                    },
+                    'sanitize_callback' => function ($v) {
+                        return sanitize_text_field((string) $v);
+                    },
+                ],
+            ],
+        ]);
+
+        register_rest_route('bemalearn/v1', '/auth/login', [
+            'methods'             => 'POST',
+            'callback'            => [$this, 'login'],
+            'permission_callback' => '__return_true',
+        ]);
+    }
+
+    /**
+     * The caller is signed in. Says nothing about their role.
+     */
+    public function check_authenticated($request) {
+        $user = BL_Auth::user_from_request($request);
+
+        if (!$user) {
+            return new WP_Error('unauthenticated', 'Sign in to continue.', ['status' => 401]);
+        }
+
+        return true;
+    }
+
+    public function check_instructor($request) {
+        $user = BL_Auth::user_from_request($request);
+
+        if (!$user) {
+            return new WP_Error('unauthenticated', 'Sign in to continue.', ['status' => 401]);
+        }
+
+        if (!in_array('bl_instructor', (array) $user->roles, true)) {
+            return new WP_Error('forbidden', 'Instructors only.', ['status' => 403]);
+        }
+
+        return true;
+    }
+
+    public function login($request) {
+        $email    = sanitize_email((string) $request->get_param('email'));
+        $password = (string) $request->get_param('password');
+
+        $user = get_user_by('email', $email);
+
+        if (!$user || !wp_check_password($password, $user->user_pass, $user->ID)) {
+            return new WP_Error(
+                'invalid_credentials',
+                'Email or password is incorrect.',
+                ['status' => 401]
+            );
+        }
+
+        return new WP_REST_Response([
+            'token' => BL_Auth::issue_token($user->ID),
+            'user'  => [
+                'id'   => (int) $user->ID,
+                'name' => $user->display_name,
+                'role' => in_array('bl_instructor', (array) $user->roles, true)
+                    ? 'instructor' : 'learner',
+            ],
+        ], 200);
+    }
+
+    public function get_earnings($request) {
+        global $wpdb;
+
+        $user = BL_Auth::user_from_request($request);
+        $ledger = $wpdb->prefix . 'bl_earnings_ledger';
+
+        $available = (int) $wpdb->get_var($wpdb->prepare(
+            "SELECT COALESCE(SUM(amount_minor), 0) FROM {$ledger}
+              WHERE instructor_id = %d
+                AND available_at IS NOT NULL
+                AND available_at <= UTC_TIMESTAMP()",
+            $user->ID
+        ));
+
+        $pending = (int) $wpdb->get_var($wpdb->prepare(
+            "SELECT COALESCE(SUM(amount_minor), 0) FROM {$ledger}
+              WHERE instructor_id = %d
+                AND (available_at IS NULL OR available_at > UTC_TIMESTAMP())",
+            $user->ID
+        ));
+
+        $last = $wpdb->get_var($wpdb->prepare(
+            "SELECT created_at FROM {$wpdb->prefix}bl_withdrawals
+              WHERE instructor_id = %d ORDER BY id DESC LIMIT 1",
+            $user->ID
+        ));
+
+        return new WP_REST_Response([
+            'availableMinor'         => $available,
+            'pendingMinor'           => $pending,
+            'currency'               => 'NGN',
+            'minimumWithdrawalMinor' => self::MINIMUM_WITHDRAWAL_MINOR,
+            'lastWithdrawalAt'       => $last ? gmdate('c', strtotime($last)) : null,
+        ], 200);
+    }
+
+    public function create_withdrawal($request) {
+        global $wpdb;
+
+        $user   = BL_Auth::user_from_request($request);
+        $amount = (int) $request->get_param('amountMinor');
+        $ref    = (string) $request->get_param('payoutReference');
+
+        $table = $wpdb->prefix . 'bl_withdrawals';
+
+        if ($amount < self::MINIMUM_WITHDRAWAL_MINOR) {
+            return new WP_Error(
+                'below_minimum',
+                'The withdrawal amount is below the minimum allowed.',
+                ['status' => 422]
+            );
+        }
+
+        // Idempotency: a repeat of the same reference returns the original.
+        if ($ref) {
+            $existing = $wpdb->get_row($wpdb->prepare(
+                "SELECT * FROM {$table} WHERE instructor_id = %d AND payout_reference = %s",
+                $user->ID, $ref
+            ));
+            if ($existing) {
+                return new WP_REST_Response($this->shape($existing), 200);
+            }
+        }
+
+        $available = (int) $wpdb->get_var($wpdb->prepare(
+            "SELECT COALESCE(SUM(amount_minor), 0) FROM {$wpdb->prefix}bl_earnings_ledger
+              WHERE instructor_id = %d
+                AND available_at IS NOT NULL
+                AND available_at <= UTC_TIMESTAMP()",
+            $user->ID
+        ));
+
+        if ($amount > $available) {
+            return new WP_Error(
+                'insufficient_balance',
+                'Your available balance is lower than the requested amount.',
+                ['status' => 422]
+            );
+        }
+
+        $pending = (int) $wpdb->get_var($wpdb->prepare(
+            "SELECT COUNT(*) FROM {$table} WHERE instructor_id = %d AND status = 'pending'",
+            $user->ID
+        ));
+
+        if ($pending > 0) {
+            return new WP_Error(
+                'withdrawal_in_progress',
+                'You already have a withdrawal in progress.',
+                ['status' => 422]
+            );
+        }
+
+        $wpdb->insert($table, [
+            'instructor_id'    => $user->ID,
+            'amount_minor'     => $amount,
+            'status'           => 'pending',
+            'payout_reference' => $ref,
+            'created_at'       => current_time('mysql', true),
+        ]);
+
+        $row = $wpdb->get_row($wpdb->prepare("SELECT * FROM {$table} WHERE id = %d", $wpdb->insert_id));
+
+        return new WP_REST_Response($this->shape($row), 201);
+    }
+
+    private function shape($row) {
+        return [
+            'id'              => (int) $row->id,
+            'amountMinor'     => (int) $row->amount_minor,
+            'status'          => $row->status,
+            'payoutReference' => $row->payout_reference,
+            'createdAt'       => gmdate('c', strtotime($row->created_at)),
+        ];
+    }
+}

bemalearn/includes/class-bl-migrations.php

@@ -0,0 +1,104 @@
+<?php
+/**
+ * Bema Learn schema.
+ *
+ * Forward-only. Each run is idempotent: creating a table that already exists is
+ * a no-op, so activating the plugin twice is safe.
+ *
+ * THIS FILE IS THE AUTHORITY ON WHAT COLUMNS EXIST.
+ * If code elsewhere reads a column, it must exist here.
+ */
+
+if (!defined('ABSPATH')) {
+    exit;
+}
+
+class BL_Migrations {
+
+    public static function run() {
+        global $wpdb;
+
+        $charset = $wpdb->get_charset_collate();
+        require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+
+        $courses = $wpdb->prefix . 'bl_courses';
+        dbDelta("CREATE TABLE {$courses} (
+            id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+            title VARCHAR(191) NOT NULL,
+            description TEXT NULL,
+            instructor_id BIGINT UNSIGNED NOT NULL,
+            price_minor INT UNSIGNED NOT NULL DEFAULT 0,
+            currency VARCHAR(3) NOT NULL DEFAULT 'NGN',
+            lesson_count INT UNSIGNED NOT NULL DEFAULT 0,
+            enrolment_count INT UNSIGNED NULL DEFAULT NULL,
+            average_rating DECIMAL(3,2) NULL DEFAULT NULL,
+            is_published TINYINT(1) NOT NULL DEFAULT 0,
+            published_at DATETIME NULL DEFAULT NULL,
+            created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+            PRIMARY KEY (id),
+            KEY idx_instructor (instructor_id),
+            KEY idx_published (is_published)
+        ) {$charset};");
+
+        $enrolments = $wpdb->prefix . 'bl_enrolments';
+        dbDelta("CREATE TABLE {$enrolments} (
+            id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+            course_id BIGINT UNSIGNED NOT NULL,
+            learner_id BIGINT UNSIGNED NOT NULL,
+            amount_paid_minor INT UNSIGNED NOT NULL,
+            rating TINYINT UNSIGNED NULL DEFAULT NULL,
+            enrolled_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+            refunded_at DATETIME NULL DEFAULT NULL,
+            PRIMARY KEY (id),
+            KEY idx_course (course_id),
+            KEY idx_learner (learner_id)
+        ) {$charset};");
+
+        /*
+         * Instructor earnings ledger. APPEND-ONLY.
+         *
+         * A reversal is a new row with a negative amount, never an edit or a
+         * delete of the original. The balance is the SUM of this table, so
+         * history stays auditable.
+         */
+        $ledger = $wpdb->prefix . 'bl_earnings_ledger';
+        dbDelta("CREATE TABLE {$ledger} (
+            id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+            instructor_id BIGINT UNSIGNED NOT NULL,
+            amount_minor INT NOT NULL,
+            entry_type VARCHAR(32) NOT NULL,
+            available_at DATETIME NULL DEFAULT NULL,
+            enrolment_id BIGINT UNSIGNED NULL DEFAULT NULL,
+            created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+            PRIMARY KEY (id),
+            KEY idx_instructor (instructor_id),
+            KEY idx_available (available_at)
+        ) {$charset};");
+
+        /*
+         * Withdrawals.
+         *
+         * payout_reference is the idempotency key: a retried request carrying
+         * the same reference must return the ORIGINAL row rather than create a
+         * second payout.
+         *
+         * NOTE FOR THE CANDIDATE (Task 5): look closely at the unique key
+         * below and satisfy yourself that it does what that paragraph claims.
+         */
+        $withdrawals = $wpdb->prefix . 'bl_withdrawals';
+        dbDelta("CREATE TABLE {$withdrawals} (
+            id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+            instructor_id BIGINT UNSIGNED NOT NULL,
+            amount_minor INT UNSIGNED NOT NULL,
+            status VARCHAR(32) NOT NULL DEFAULT 'pending',
+            payout_reference VARCHAR(64) NULL DEFAULT NULL,
+            cancelled_at DATETIME NULL DEFAULT NULL,
+            created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+            PRIMARY KEY (id),
+            UNIQUE KEY uq_reference (instructor_id, payout_reference, cancelled_at),
+            KEY idx_status (status)
+        ) {$charset};");
+
+        update_option('bemalearn_schema_version', BEMALEARN_VERSION);
+    }
+}

bemalearn/includes/class-bl-seeder.php

@@ -0,0 +1,109 @@
+<?php
+/**
+ * Seed data for the assessment.
+ *
+ * Deliberately shaped to exercise the contract's edge cases:
+ *   - a course with NULL enrolment_count and NULL average_rating
+ *   - a course with a REAL zero rating (0.00) - not the same thing
+ *   - an UNPUBLISHED course, which must never appear in the public list
+ *   - a ledger with both available and pending money
+ */
+
+if (!defined('ABSPATH')) {
+    exit;
+}
+
+class BL_Seeder {
+
+    public static function seed($force = false) {
+        global $wpdb;
+
+        if (!$force && get_option('bemalearn_seeded')) {
+            return;
+        }
+
+        add_role('bl_instructor', 'Bema Learn Instructor', ['read' => true]);
+        add_role('bl_learner', 'Bema Learn Learner', ['read' => true]);
+
+        $instructor = self::ensure_user('instructor@example.test', 'Ada Okafor', 'bl_instructor');
+        $learner    = self::ensure_user('learner@example.test', 'Bola Adeyemi', 'bl_learner');
+
+        $courses = $wpdb->prefix . 'bl_courses';
+        $wpdb->query("TRUNCATE TABLE {$courses}");
+
+        $rows = [
+            // title, price, lessons, enrolments, rating, published, published_at
+            ['Introduction to Bread Baking', 4500, 12, 128,  4.60, 1, '2026-03-14 08:00:00'],
+            ['Sourdough Starters',           6000, 18,  64,  4.20, 1, '2026-04-02 08:00:00'],
+            // NULL enrolments and NULL rating - "not yet counted", NOT zero
+            ['Pastry Fundamentals',          7500, 24, null, null, 1, '2026-05-20 08:00:00'],
+            // A REAL zero rating - must display differently from NULL
+            ['Cake Decorating Basics',       3000,  8,   9,  0.00, 1, '2026-06-11 08:00:00'],
+            // UNPUBLISHED - must never appear in the public list
+            ['Advanced Laminated Dough',     9000, 30,   0, null, 0, null],
+        ];
+
+        foreach ($rows as $r) {
+            $wpdb->insert($courses, [
+                'title'           => $r[0],
+                'description'     => $r[0] . ' - a short course for the assessment environment.',
+                'instructor_id'   => $instructor,
+                'price_minor'     => $r[1],
+                'currency'        => 'NGN',
+                'lesson_count'    => $r[2],
+                'enrolment_count' => $r[3],
+                'average_rating'  => $r[4],
+                'is_published'    => $r[5],
+                'published_at'    => $r[6],
+            ]);
+        }
+
+        $ledger = $wpdb->prefix . 'bl_earnings_ledger';
+        $wpdb->query("TRUNCATE TABLE {$ledger}");
+
+        // Available now
+        foreach ([45000, 60000, 23500] as $amount) {
+            $wpdb->insert($ledger, [
+                'instructor_id' => $instructor,
+                'amount_minor'  => $amount,
+                'entry_type'    => 'enrolment',
+                'available_at'  => gmdate('Y-m-d H:i:s', time() - 86400),
+            ]);
+        }
+
+        // Still pending (held)
+        $wpdb->insert($ledger, [
+            'instructor_id' => $instructor,
+            'amount_minor'  => 45000,
+            'entry_type'    => 'enrolment',
+            'available_at'  => gmdate('Y-m-d H:i:s', time() + (86400 * 5)),
+        ]);
+
+        $wpdb->query("TRUNCATE TABLE {$wpdb->prefix}bl_withdrawals");
+        $wpdb->query("TRUNCATE TABLE {$wpdb->prefix}bl_enrolments");
+
+        // Enrolments, including one refunded and some unrated rows
+        $enr = $wpdb->prefix . 'bl_enrolments';
+        $wpdb->insert($enr, ['course_id' => 1, 'learner_id' => $learner, 'amount_paid_minor' => 4500, 'rating' => 5]);
+        $wpdb->insert($enr, ['course_id' => 1, 'learner_id' => $learner, 'amount_paid_minor' => 4500, 'rating' => null]);
+        $wpdb->insert($enr, ['course_id' => 2, 'learner_id' => $learner, 'amount_paid_minor' => 6000, 'rating' => 4,
+                             'refunded_at' => gmdate('Y-m-d H:i:s')]);
+
+        update_option('bemalearn_seeded', 1);
+    }
+
+    private static function ensure_user($email, $name, $role) {
+        $existing = get_user_by('email', $email);
+        if ($existing) {
+            return (int) $existing->ID;
+        }
+        $id = wp_insert_user([
+            'user_login'   => sanitize_user(strtok($email, '@')),
+            'user_email'   => $email,
+            'user_pass'    => 'assessment123',
+            'display_name' => $name,
+            'role'         => $role,
+        ]);
+        return (int) $id;
+    }
+}

docker-entrypoint-space.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+: "${MARIADB_ROOT_PASSWORD:?MARIADB_ROOT_PASSWORD is required}"
+: "${WORDPRESS_DB_NAME:?WORDPRESS_DB_NAME is required}"
+: "${WORDPRESS_DB_USER:?WORDPRESS_DB_USER is required}"
+: "${WORDPRESS_DB_PASSWORD:?WORDPRESS_DB_PASSWORD is required}"
+
+mkdir -p /run/mysqld /var/lib/mysql
+chown -R mysql:mysql /run/mysqld /var/lib/mysql
+
+if [ ! -d /var/lib/mysql/mysql ]; then
+  mariadb-install-db --user=mysql --datadir=/var/lib/mysql >/dev/null
+fi
+
+mariadbd --user=mysql --bind-address=127.0.0.1 --skip-name-resolve &
+DB_PID=$!
+cleanup() { kill "$DB_PID" 2>/dev/null || true; }
+trap cleanup EXIT
+
+for _ in $(seq 1 60); do
+  mariadb-admin ping -h 127.0.0.1 --silent >/dev/null 2>&1 && break
+  sleep 1
+done
+mariadb-admin ping -h 127.0.0.1 --silent >/dev/null 2>&1 || { echo 'MariaDB failed to start' >&2; exit 1; }
+
+mariadb -h 127.0.0.1 -uroot <<SQL
+CREATE DATABASE IF NOT EXISTS \`${WORDPRESS_DB_NAME}\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER IF NOT EXISTS '${WORDPRESS_DB_USER}'@'127.0.0.1' IDENTIFIED BY '${WORDPRESS_DB_PASSWORD}';
+ALTER USER '${WORDPRESS_DB_USER}'@'127.0.0.1' IDENTIFIED BY '${WORDPRESS_DB_PASSWORD}';
+GRANT ALL PRIVILEGES ON \`${WORDPRESS_DB_NAME}\`.* TO '${WORDPRESS_DB_USER}'@'127.0.0.1';
+FLUSH PRIVILEGES;
+SQL
+
+cat > /var/www/html/wp-config-extra.php <<'PHP'
+<?php
+if (getenv('WP_ENVIRONMENT_TYPE')) {
+    define('WP_ENVIRONMENT_TYPE', getenv('WP_ENVIRONMENT_TYPE'));
+}
+define('WP_DEBUG', filter_var(getenv('WORDPRESS_DEBUG') ?: '0', FILTER_VALIDATE_BOOLEAN));
+define('WP_DEBUG_LOG', true);
+define('WP_DEBUG_DISPLAY', false);
+PHP
+
+# The official image generates wp-config.php from the standard environment variables.
+export WORDPRESS_DB_HOST=127.0.0.1
+export WORDPRESS_DB_NAME="$WORDPRESS_DB_NAME"
+export WORDPRESS_DB_USER="$WORDPRESS_DB_USER"
+export WORDPRESS_DB_PASSWORD="$WORDPRESS_DB_PASSWORD"
+
+apache2-foreground &
+APACHE_PID=$!
+for _ in $(seq 1 90); do
+  if wp core is-installed --path=/var/www/html --allow-root >/dev/null 2>&1; then break; fi
+  if [ ! -f /var/www/html/wp-config.php ]; then
+    wp core download --path=/var/www/html --force --allow-root >/dev/null 2>&1 || true
+    wp config create --path=/var/www/html --dbname="$WORDPRESS_DB_NAME" --dbuser="$WORDPRESS_DB_USER" --dbpass="$WORDPRESS_DB_PASSWORD" --dbhost=127.0.0.1 --skip-check --force --allow-root >/dev/null 2>&1 || true
+  fi
+  wp core install --path=/var/www/html --url="${SPACE_HOST:-http://localhost:7860}" --title='Bema Learn API' --admin_user="${WP_ADMIN_USER:-admin}" --admin_password="${WP_ADMIN_PASSWORD:-change-me-admin}" --admin_email="${WP_ADMIN_EMAIL:-admin@example.test}" --skip-email --allow-root >/dev/null 2>&1 || true
+  sleep 2
+done
+wp core is-installed --path=/var/www/html --allow-root >/dev/null 2>&1 || { echo 'WordPress failed to initialize' >&2; exit 1; }
+wp plugin activate bemalearn --path=/var/www/html --allow-root >/dev/null
+wp rewrite structure '/%postname%/' --path=/var/www/html --allow-root >/dev/null 2>&1 || true
+wp rewrite flush --hard --path=/var/www/html --allow-root >/dev/null 2>&1 || true
+
+wait "$APACHE_PID"