Developer Handbook

1. System Requirements

2. Repository Layout Highlights

app/                 Application code (controllers, config, libraries, filters)
modules/             Feature modules (Auth, Backend, Blog, etc.)
public/
  index.php          Front controller
  be-assets/         Admin UI build artifacts (CSS/JS)
  templates/         Front-end themes (default shipped)
  media/             Media storage (ensure writable)
writable/            Cache, logs, temporary files (must be writable)
vendor/              Composer packages

Essential configuration files include composer.json, the contents of app/Config, and the environment overrides stored in .env.

3. Getting Started

1. Clone & install

   git clone <repo-url> ci4ms
   cd ci4ms
   composer install

2. Prepare the environment

   cp env .env
   php spark env development

   Set app.baseURL, database.default.*, mail credentials, and security options.

3. Migrate & seed

   php spark migrate
   php spark db:seed Ci4msDefaultsSeeder  # prompts for admin account details
   php spark key:generate
   php spark create:route

4. Serve locally

   php spark serve

   Visit http://localhost:8080 for the front-end and /backend for the admin.

Tip: Re-running the seeder on a populated database can duplicate data. Truncate first if needed.

4. Dependency Management

composer install
composer update vendor/package
composer outdated

5. Coding Guidelines

• Namespaces: PSR-4 via Composer. Modules live under Modules\<Name>, app code under App\.
• Controllers: Backend controllers extend Modules\Backend\Controllers\BaseController; frontend extends App\Controllers\BaseController.
• Views: Stored per module (Modules\Blog\Views\list etc.).
• Helpers/Filters: Keep helpers/filters modular; app/Config/Filters discovers them dynamically.
• Configuration: Module-specific configs live in modules/<Module>/Config.
• Translations: Use modules/<Module>/Language/<locale>.
• Testing: Run composer test; add linting tooling if desired.

6. Modules & Permissions

Permissions are stored in auth_permissions_pages (CRUD JSON flags) and auth_users_permissions (overrides). The Modules\Methods\Controllers\Methods::moduleScan() command inspects routes and helps keep permissions in sync.

Workflow for a new module:

1. Scaffold with php spark make:module <Name> (provided by ext_module_generator).
2. Define routes in modules/<Name>/Config/Routes.php with role metadata.
3. Implement controllers, models, views.
4. Update permissions (run module scan or insert records manually).
5. Create migrations/seeds for new tables if required.

Clear cached permissions with php spark cache:clear or cache()->delete("{userId}_permissions").

7. Configuration & Settings Cache

• Settings: Stored in the settings table and cached for 24h. Clear via cache()->delete('settings').
• Menus: Cached as menus; automatically refreshed when editing via the Menu module.
• Maintenance mode: Controlled by settings.maintenanceMode; triggers redirect in App\Filters\Ci4ms.

8. Media, File, & Theme Handling

9. Public Assets & Front Controller

• public/index.php bootstraps CodeIgniter; production servers should expose only public/.
• public/maintenance/ serves the maintenance splash when enabled.
• public/be-assets/ houses admin CSS/JS, images, plugins, and package manifests.
• public/media/ contains uploaded media (include in backups).
• public/templates/default/ is the bundled theme—use it as a blueprint for custom themes.

10. Testing & QA

• Tests live under tests/; namespace under Tests\Support is autoloaded.
• Add integration tests for auth, CRUD operations, and menu updates as coverage grows.
• Use maintenance mode to hide upcoming changes during manual QA.

11. Debugging Tips

• Enable the debug toolbar via CI_ENVIRONMENT=development.
• Logs reside in writable/logs/; ensure permissions allow writing or inspect them via the backend viewer at /backend/logs.
• Clear cache via php spark cache:clear or delete contents of writable/cache/.
• Migration issues? Check logs and the ci_migrations table for batch sync.
• Mail issues? Trigger the AJAX Test Mail button in Settings after configuring SMTP.

12. Deployment Checklist

1. Switch to CI_ENVIRONMENT=production.
2. Set the public app.baseURL.
3. Point the web server root to public/; restrict other directories.
4. Run migrations/seeds (php spark migrate --all, relevant seeders).
5. Optional cache warm-up via scripted requests.
6. Disable the debug toolbar in production.
7. Set secure permissions (775/664 depending on user/group).
8. Back up uploads, database, and .env before major upgrades.

13. Contribution Workflow

• Branching: Prefix with scope (e.g., feature/blog-scheduling).
• Commits: Reference modules/issues ([Blog] Add scheduling support).
• Pull requests: Note migrations, env vars, npm steps.
• Reviews: Highlight permission changes, cache impacts, asset updates.
• Changelog: Maintain if releasing versions.

14. Further Reading & Resources

• CodeIgniter 4 Documentation
• Composer Docs
• CI4MS Architecture Guide (Markdown)
• CI4MS User Guide (HTML)

Update this handbook whenever the stack or workflows evolve so the team always has a current source of truth.