device-management/README.md

RADIQ NDM

RADIQ NDM (Network Device Management) is a centralized, multi-tenant platform for managing ISP and network-device access.

Phase 1 architecture

• PHP 8.3 and Laravel 13.
• React 19, TypeScript, Inertia 3, Tailwind CSS 4, and shadcn/ui.
• Laravel Fortify/session authentication with registration disabled. Users are provisioned by authorized administrators.
• Spatie Laravel Permission 8 with team mode mapped to tenant_id.
• Laravel Sanctum for /api/v1 token authentication.
• Database-backed session, cache, and queue for the foundation. Redis is deferred until operational load justifies it.
• Tenant context is established server-side for every web/API request. Tenant-owned Eloquent models use a reusable global scope.
• Platform access requires the explicit platform-admin marker and cross-tenant permission; normal administrators remain tenant-bound.

Phase 1 database

• tenants: UUID public identifier, unique slug, active state.
• users: UUID, nullable tenant for platform identities, hashed application password, active/platform flags.
• roles, permissions, and tenant-aware model pivots supplied by Spatie.
• Authentication support tables for sessions, resets, passkeys, 2FA, and API tokens.
• Database queue/cache foundation tables.

Secrets belong only in .env. The committed .env.example intentionally contains blank database credentials.

Development commands (Windows)

Ensure PHP 8.3 is first in the process path because the machine also contains an older XAMPP PHP:

$env:Path = 'C:\php83;' + $env:Path
C:\php83\php.exe artisan about
C:\php83\php.exe artisan migrate:status
npm run dev

Run tests with the available SQLite DLLs loaded for the test process:

C:\php83\php.exe -d "extension=C:\php83\ext\php_pdo_sqlite.dll" -d "extension=C:\php83\ext\php_sqlite3.dll" vendor\bin\phpunit
npm run types:check
npm run lint:check

Current scope

Phase 1 foundation is ready for user acceptance testing. Authentication, tenant context, RBAC schema, base API, Master Admin bootstrap, platform dashboard, Tenant + Tenant Admin provisioning, tenant user management, password reset, and account activation are present. Device/driver functionality intentionally has not started pending acceptance of Phase 1.

Phase 2 device inventory is now available: global vendor/type/model catalogs, tenant-scoped device CRUD, encrypted and masked device credentials, server-side search/filter/pagination, and configurable Tenant User create/update-own/delete-own policy. Network connection testing remains disabled until the Phase 3 driver engine is implemented.

MikroTik provisioning is available through the native RouterOS API client. Tenant Admin configures an encrypted Base User template, then explicitly activates a MikroTik device after storing its bootstrap credential. Activation assigns the Base User to RouterOS' built-in full group and synchronizes RADIQ-READ, RADIQ-WRITE, and RADIQ-NOC without RouterOS policy.

Centralized Device Users are managed independently from application users. One encrypted credential can target many devices, while each assignment tracks queued/pending/processing/synced/failed/unsupported state. Queue jobs contain only tenant and assignment IDs. Pending offline devices are re-queued by the scheduler every five minutes.

Roles and permissions are fixed by the application and have no management UI. The only roles are MASTER ADMIN, TENANT ADMIN, and TENANT USER. A Tenant Admin can only create and manage Tenant User accounts in its own tenant. Device permissions for Tenant User are governed by the fixed tenant policy and will be refined with the device module.

Deployment and licensing boundary

• control_plane: RADIQ-owned licensing/master administration. Stores customer tenants, installations, license lifecycle, limits, and renewal history.
• managed_cloud: RADIQ-hosted multi-tenant NDM. Platform Master Admin exists here; each ISP remains a tenant.
• self_hosted: installed on an ISP/customer server. The customer is still a tenant and receives Tenant Owner access, never Platform Master Admin. Its signed license is issued and renewed by the RADIQ control plane.

Raw license and instance secrets are never stored. Only SHA-256 hashes are persisted. The schema supports signed license payloads so a self-hosted installation can validate a license with a public key; the signing private key must exist only on the RADIQ control plane. Runtime activation/heartbeat and enforcement will be implemented as a dedicated licensing increment before production distribution.

Create the first Platform Super Admin interactively (the password is never passed as a command option):

C:\php83\php.exe artisan app:create-platform-admin

Public registration is intentionally disabled. Subsequent tenant users will be created from the permission-protected Administration UI.