Modules & Feature Flags

Modules & Feature Flags

KoAkademy provides modular extensibility and runtime configurability through three distinct mechanisms:

1. Modules (Code level): Optional domain features with dedicated models, controllers, migrations, and UI.
2. Feature Flags (Runtime level): Class-based toggles powered by Laravel Pennant for gradual feature rollouts.
3. Institution Settings (Configuration level): Per-school settings stored via spatie/laravel-settings.

Modules Overview

Modules are managed via nwidart/laravel-modules and integrated with Filament through coolsam/modules:

Bundled Core Modules

KoAkademy includes six bundled modules under Modules/ that are active by default:

Module	Namespace	Purpose
Announcement	Modules\Announcement	School-wide news and targeted broadcast banners
Cashier	Modules\Cashier	In-person student balance lookup and cashier payment processing
Inventory	Modules\Inventory	Campus equipment tracking, suppliers, and stock ledger
LibrarySystem	Modules\LibrarySystem	Book cataloging, borrow/return logs, and digital paper archives
NotificationCenter	Modules\NotificationCenter	Dynamic notification templates and batch broadcast jobs
StudentMedicalRecords	Modules\StudentMedicalRecords	Confidential clinic visit notes and student medical profiles

Standalone Composer Modules

Standalone modules (like the Forms Module) are published as separate Composer packages via the KoAkademy Module Registry.

Installation is performed at the Composer level:

# Add the registry repository
composer config repositories.koakademy composer https://yukazakiri.github.io/koakademy-modules

# Require the desired module package
composer require koakademy/module-forms:^1.0

# Run module database migrations
php artisan migrate --force

Marketplace Enablement

The in-app Marketplace under Administrators → Marketplace displays available and installed modules. The Marketplace allows administrators to enable or disable installed modules, but it never executes arbitrary shell commands or modifies a running container at runtime.

Feature Flags (Laravel Pennant)

KoAkademy uses class-based feature flags located in app/Features/Toggles/. Feature flags are defined in AppServiceProvider and mapped in FeatureToggleRegistry.

Creating a New Feature Flag

To add a new feature toggle:

1. Create a toggle class in app/Features/Toggles/:

<?php

declare(strict_types=1);

namespace App\Features\Toggles;

use App\Features\Concerns\ResolvesFeatureToggle;
use App\Features\Contracts\FeatureToggle;

final class FacultyAnalytics implements FeatureToggle
{
    use ResolvesFeatureToggle;

    public function key(): string
    {
        return 'faculty-analytics';
    }

    public function name(): string
    {
        return 'Faculty Analytics';
    }

    public function summary(): string
    {
        return 'Visual class attendance and grade distribution charts.';
    }

    public function audience(): string
    {
        return 'faculty';
    }

    public function badge(): string
    {
        return 'Analytics';
    }

    public function accent(): string
    {
        return 'text-primary';
    }

    public function ctaLabel(): string
    {
        return 'View Analytics';
    }

    public function ctaUrl(): string
    {
        return '/faculty/analytics';
    }

    public function steps(): array
    {
        return [];
    }

    public function category(): string
    {
        return 'Faculty';
    }
}

2. Register the class in App\Services\FeatureToggleRegistry:

private const array KEY_TO_CLASS = [
    // ...
    'faculty-analytics' => FacultyAnalytics::class,
];

3. Define the feature in App\Providers\AppServiceProvider::definePennantFeatures():

Feature::define(FacultyAnalytics::class);

4. Guard backend routes using the EnsureFeatureEnabled middleware in app/Http/Middleware/EnsureFeatureEnabled.php or controller policies.

Choosing the Right Extensibility Mechanism

If you are adding…	Use this mechanism
A complete domain with separate database tables and migrations	A Module
A toggleable screen, sub-feature, or staged rollout	A Pennant Feature Flag
School-specific preferences (e.g. school logo, term labels, fees)	A GeneralSetting property