# Module Registry vs Filesystem Plugin Flow

Practical step-by-step reference for how ERPFlow handles module registration and plugin sync.

---

## A) UI Module Registry Flow (DB-centric, no `module.json` required)

1. Admin opens **Module Registry** page.
2. Admin submits module form (`name`, `slug`, `status`, `actions`, etc.).
3. Frontend calls API (for example: `POST /api/v1/modules`).
4. Backend `ModuleController` forwards to `ModuleRegistryService`.
5. A row is created in `modules`.
6. Selected actions are synced to `module_actions`.
7. Permission sync runs and generates/updates `permissions`.
8. Module is now registered in DB.
9. Admin assigns role permissions from the permission matrix.
10. Admin creates sidebar entry from Menu Builder with proper `permission_key`.
11. User sees menu from `/me/navigation` only if permissions match.

Use this flow when module metadata is managed directly from admin UI.

---

## B) Filesystem Plugin Flow (`module.json`-driven)

1. Developer creates `backend/Modules/{ModuleName}/module.json`.
2. Developer adds backend code (routes/controllers/services/repositories/migrations).
3. Developer adds frontend route/pages/components.
4. Run `platform:sync`.
5. Sync process discovers all `Modules/*/module.json` files.
6. Manifest is validated (`name`, `slug`, `version`, etc.).
7. `modules` table is created/updated from manifest data.
8. Manifest snapshot is stored in `modules.metadata`.
9. `module_actions`, `menus`, `permissions`, `dependencies` are synced.
10. Installation/sync history is recorded in `module_installations`.
11. Run `module:migrate {slug}` for module database changes.
12. Enable/disable/lifecycle behavior applies based on module status.
13. After role assignment, users can access module UI/API.

Use this flow for real plugin packages and lifecycle-ready modules.

---

## C) `module.json` vs DB JSON (`modules.metadata`)

1. `module.json` is the source manifest maintained by developers.
2. `modules.metadata` is the parsed/stored DB snapshot of that manifest.
3. If `module.json` changes, run `platform:sync` to update DB.
4. Without sync, DB can remain stale compared to filesystem.
5. Runtime behavior usually depends on DB state after sync.

---

## D) Recommended Team Rule

1. For business modules (HRMS, CRM, Inventory), prefer filesystem plugin flow.
2. Keep Module Registry UI for admin-level metadata management.
3. Always sync after manifest changes.
4. Keep one agreed process per team to avoid mixed-state confusion.

---

## E) Command Checklist (Quick)

```bash
# 1) Sync manifest to DB
docker compose exec backend php artisan platform:sync

# 2) Run module migration
docker compose exec backend php artisan module:migrate {slug}

# 3) Optional: reseed menus if needed by phase behavior
docker compose exec backend php artisan db:seed --class=MenuSeeder
```

---

*Purpose: quick team reference to avoid confusion between UI registry and filesystem plugin workflow.*