1. Executive brief
Build a multi-organization, multi-location CMMS that is fast enough for field technicians and sufficiently controlled for portfolio-level managers and auditors. The first usable release should establish the facilities hierarchy, users and scoped access, the asset register, and the complete work-order loop. Fleet, inventory, automation, reporting, and offline mobile capability should follow through explicit release gates.
Success measures
2. Scope and boundaries
In scope
All functional areas in the PDF are represented in the architecture and roadmap:
Facilities hierarchyAssetsMovementsWork ordersRequestsPMInspectionsChecklistsFleetInventoryVendorsDocumentsApprovalsNotificationsReportsQR/barcodesAuditMobile/offline
Not part of this document
- Application source code, Dockerfiles, Compose YAML, migrations, API implementations, or Flutter code.
- Final UI artwork, production credentials, cloud-vendor selection, or infrastructure procurement.
- Immediate implementation of future integrations such as IoT, ERP, GPS, Power BI, SMS, or WhatsApp.
- A promise that every listed PDF field belongs in the first release; field-level validation occurs during domain workshops.
3. Architecture decisions
| Area | Decision | Reason / guardrail |
|---|---|---|
| Backend | Laravel 13 on PHP 8.5, subject to package compatibility verification. | Laravel 13 supports PHP 8.3-8.5 and has security support through March 2028. Drop to PHP 8.4 only if a required dependency blocks 8.5. |
| Admin web | Filament 5 as the operations and administration interface. | Use Resources, forms, tables, widgets, notifications, and panel access; keep domain rules in application services/policies, not Filament screens. |
| Database | PostgreSQL current stable, pinned to a tested major image. | Relational integrity for operational records; JSONB only for controlled custom fields; GIN/full-text indexes where proven by query plans. |
| Web edge | Nginx serves static assets and forwards PHP requests to PHP-FPM. | Only Nginx publishes the application HTTP port. PHP-FPM, PostgreSQL, Redis, Mailpit SMTP, and MinIO API remain on private Compose networks unless a local tool explicitly needs access. |
| Containers | Separate development and production Compose overlays with multi-stage images. | Named volumes, private networks, health checks, non-root runtime users, deterministic dependency locks, and immutable production tags/digests. |
| Async work | Redis-backed queues and cache; dedicated queue worker and scheduler services. | Notifications, exports, report delivery, PM generation, file processing, and sync jobs must not block requests. Workers restart during deployment. |
| Mobile | Flutter client consuming the same versioned REST API. | Offline-first local database and outbox; no direct database or object-store credentials in the app. |
| Files | Laravel filesystem abstraction using MinIO locally and S3-compatible production storage. | Private buckets by default, short-lived signed access, metadata in PostgreSQL, object bytes outside PostgreSQL. |
| Mailpit in local/development only. | Captures SMTP safely at ports 1025/8025; production mail is supplied by a real transactional provider. | |
| Tenancy | Organization is the security tenant; portfolios are operational scopes within it. | Every tenant-owned aggregate carries an organization boundary. Filament tenancy conveniences do not replace server-side policy and query scoping. |
4. Runtime topology
Core services
Nginx, PHP-FPM app, CLI, queue worker, scheduler, PostgreSQL, and Redis.
Development services
Mailpit, MinIO, one-shot MinIO bucket initializer, and optional database/admin tooling behind a profile.
Persistence
Named volumes for PostgreSQL, Redis only if persistence is required, MinIO objects, and approved application storage. Source bind mounts only in development.
Compose readiness checklist
5. Product domains
Identity & tenancy
Organizations, users, roles, permissions, teams, departments, scoped access grants, sessions, and audit events.
Places
Portfolio -> continent -> country -> city -> facility -> building -> floor -> room/zone, with status, contacts, documents, and path projection.
Assets
Categories, assets, technical/financial data, custodians, tags, documents, condition, criticality, movement, disposal, and history.
Maintenance
Requests, work orders, tasks, labor, parts, media, state transitions, downtime, costs, approvals, ratings, and close-out.
Reliability
PM schedules, recurrence rules, checklists, inspections, results, compliance, corrective actions, and idempotent generation.
Fleet
Vehicles/mobile equipment, drivers, assignments, mileage/hours, documents, trips, fuel, accidents, and maintenance triggers.
Supply & vendors
Stores, items, stock ledger, reservations/issues/returns/transfers, suppliers, vendors, contracts, compliance, and performance.
Communication
Notification preferences, in-app/email/push channels, templates, delivery attempts, reminders, and escalation rules.
Insight & governance
Dashboards, exports, scheduled reports, numbering, settings, approvals, documents, audit history, and import jobs.
6. Data architecture
Core modelling rules
- Use stable internal primary keys and separate human-readable, organization-scoped codes/numbers with unique constraints.
- Normalize the fixed facilities hierarchy with parent foreign keys. Do not copy all ancestor IDs into every child as independent truths.
- Maintain a derived location-path projection (or materialized path/read model) for breadcrumbs, search, QR results, exports, and access evaluation; rebuild it safely after moves.
- Store timestamps as time-zone-aware instants (UTC operationally) and retain each facility/user IANA time-zone identifier for display and scheduling.
- Use explicit state-machine transitions and append-only history for regulated events. Archive/retire instead of hard delete where records are referenced.
- Model inventory as an immutable transaction ledger; derive quantity on hand and reconcile it, rather than trusting editable counters alone.
- Use JSONB only for versioned custom fields or integration payloads. Core reporting/filter fields remain typed columns with constraints.
- Index foreign keys, tenant/scope columns, status/due-date queues, normalized codes, and proven search predicates. Validate with realistic query plans.
Aggregate map
| Aggregate | Owns | Key invariants |
|---|---|---|
| Organization | Settings, numbering sequences, roles, grants | No cross-organization relation; numbering is atomic and unique within configured scope. |
| Location hierarchy | Typed nodes, documents, contacts, path projection | Correct parent type; no cycles; moves are authorized and audited. |
| Asset | Identifiers, assignments, documents, photos, movement/history | One active location; unique tag/code per organization; retirement blocks new operational work. |
| Work order | Tasks, checklist run, labor, parts, photos, timeline, approvals | Allowed transitions only; costs/downtime derived consistently; close requires completion rules. |
| PM schedule | Recurrence, trigger, assignment, template | One generated occurrence per schedule/due instant using an idempotency key. |
| Inspection | Checklist snapshot, responses, evidence, score | Template changes never rewrite completed inspections; failed corrective actions are traceable. |
| Inventory item/store | Stock movements and reservations | No unexplained stock mutation; negative stock policy explicit; work-order issues traceable. |
| Document | Metadata, versions, expiry, object reference | Private by default; content type/size checked; access follows linked record permissions. |
Schema design checklist
7. Core workflows
Service request to closure
Preventive maintenance
Inspection and corrective action
Asset movement
Inventory issue
8. API and integration plan
Expose one versioned API (for example /api/v1) for Flutter and approved external clients. Filament may use Laravel internally, but it must call the same domain services and policies so web and mobile cannot develop conflicting rules.
Resource groups
Auth/me, organizations/scopes, hierarchy, assets/movements, work orders, service requests, PM, inspections/checklists, fleet, inventory, vendors, documents/uploads, notifications, approvals, reports/exports, settings, and sync.
Contract standards
Pagination, filtering, sorting, sparse includes where justified, consistent error envelopes, request correlation IDs, optimistic concurrency, idempotency keys, ISO-8601 timestamps, and explicit API version/deprecation rules.
Authentication
Use a first-party/mobile token approach selected during security design. Store mobile tokens in platform secure storage; support revocation, device/session visibility, rate limiting, and least-privilege abilities.
Files and exports
Authorize upload intent, validate metadata, upload through the application or short-lived signed flow, scan asynchronously, and publish private downloads only after permission checks. Run large exports asynchronously.
9. Flutter mobile plan
The mobile app is a field-work client, not a smaller copy of the entire admin system. Its first jobs are assigned work, evidence capture, checklists, inspections, QR scan, signatures, asset context, odometer updates, and resilient synchronization.
Local-first read model
Keep the user’s permitted assignments, minimal asset/location context, checklist snapshots, and pending media in an encrypted local database. UI reads from local state.
Outbox writes
Record mutations locally with client-generated IDs and idempotency keys. Sync in dependency order with retry/backoff and visible per-item status.
Conflict policy
Server wins for permissions and closed/approved records; merge append-only notes/evidence; require user resolution for incompatible edits. Never silently discard field work.
Offline acceptance checklist
10. Security and access
Use role permissions for capabilities and explicit scope grants for where those capabilities apply. Effective access is the intersection of tenant, role/capability, location scope, record state, and (where relevant) ownership/assignment.
| Control | Required design | Verification |
|---|---|---|
| Tenant isolation | Organization-scoped queries, policies, unique keys, jobs, cache keys, exports, and object paths. | Cross-tenant negative tests on every module and background job. |
| Location access | Hierarchical grants with inheritance and explicit exceptions; server-side filtering before pagination/search. | Matrix tests for manager, technician, inspector, vendor, requester, and auditor. |
| Authentication | Strong password policy, reset, verified identity, session/token expiry, revocation; optional MFA/SSO later. | Threat model and automated auth/session tests. |
| Files | Allow-listed type, detected MIME, size limits, randomized keys, malware scanning, private bucket, signed download. | Malicious file, path, object-ID, and expired-link tests. |
| Audit | Actor, action, target, before/after where safe, time, correlation ID, IP/device; redact secrets and sensitive content. | Immutable retention and privileged-action review. |
| Web/API | CSRF where applicable, authorization on every request, output escaping, validation, rate limiting, secure headers, TLS in production. | OWASP-oriented review and security regression suite. |
| Secrets | No committed credentials; local env files excluded; production secret store and rotation procedure. | Repository scan and rotation drill. |
11. Quality strategy
Automated layers
- Unit tests for domain policies, numbering, recurrence, scoring, transitions, cost and downtime calculations.
- Feature/API tests for permissions, validation, persistence, queues, uploads, exports, and audit.
- Contract tests for Flutter sync and integration adapters.
- Browser tests for critical Filament workflows.
- Migration and restore tests against PostgreSQL.
Operational checks
- Structured logs and correlation IDs across requests/jobs.
- Health/readiness checks and queue-failure visibility.
- Metrics for API latency/errors, database saturation, queue lag, sync failures, storage, mail, and scheduled-job completion.
- Alert runbooks, backup monitoring, and restore drills.
- Representative performance data by tenant/location scale.
Minimum non-functional targets to agree
12. Phases and gates
Discovery & foundations
Glossary, personas, tenant model, scope rules, states, NFRs, UX journeys, architecture, ADRs, ERD, API conventions, delivery environments, and prioritized backlog.
Core setup
Organizations, identity, roles/grants, hierarchy, location path, assets, documents, search, audit foundation, numbering, and imports for foundation data.
Maintenance operations
Service requests, work orders, assignments, task/checklist runs, labor, parts references, photos, timeline, PM, inspections, approvals, and notifications.
Fleet & inventory
Fleet assets, drivers, assignments, documents/expiry, mileage/hours, service triggers, stores, stock ledger, issues/returns/transfers, vendors, and contracts.
Automation & insight
QR/barcode, richer approvals, dashboards, scheduled reports, bulk import/export, escalation, configurable notifications, compliance reminders, and operational monitoring.
Mobile & advanced
Flutter technician/inspector release, secure auth, local-first reads, outbox sync, QR scan, evidence/signature, push, conflict handling, GPS/IoT adapter foundations, and analytics.
13. Developer deliverables checklist
These 20 items directly trace to the source PDF’s final expected deliverables.
14. Release acceptance checklist
15. Risks and open decisions
| Priority | Decision / risk | Required resolution |
|---|---|---|
| Critical | Meaning of “multiple organizations” and data isolation model. | Choose shared database/shared schema with mandatory tenant key (recommended initially) versus stronger physical isolation; document migration path. |
| Critical | Offline conflict and permission-revocation semantics. | Approve per-entity merge policy, local data wipe/revocation behavior, and evidence retention before mobile implementation. |
| High | Facilities hierarchy can vary in real organizations. | Confirm fixed eight-level hierarchy versus optional/skippable levels; avoid custom arbitrary trees until concrete cases require them. |
| High | Location-scoped access and derived path performance. | Prototype access queries and moving subtrees with representative scale before schema freeze. |
| High | “Custom workflows” can become an unbounded workflow engine. | Start with configured approvals/notifications over named state machines; defer a general workflow builder. |
| High | Report definitions and financial totals are ambiguous. | Create a metric catalogue with formula, grain, filters, currency/time-zone rules, and source of truth. |
| Medium | PHP 8.5 and newest packages may have ecosystem gaps. | Run compatibility spike; pin PHP 8.4 if any required supported package is not ready. |
| Medium | Object-storage environment differences. | Test S3 endpoint/path-style behavior, CORS, signed URLs, lifecycle, encryption, and large uploads against the production provider. |
| Medium | Notification providers, maps, SSO, GPS, IoT, ERP remain unspecified. | Use adapter interfaces and event contracts; choose providers only when a funded integration enters scope. |
Decision checklist
16. Documentation sources
Context7 was used on 28 June 2026 to resolve and query current documentation. Exact runtime versions must still be pinned and compatibility-tested at implementation kickoff.
Application platform
- Laravel 13 documentation - PHP support, queues, notifications, deployment.
- Filament 5 documentation - panels, access, tenancy, notifications, deployment.
- Flutter offline-first guidance - local/remote reads, local-first writes, synchronization.
Runtime and data
- Docker Laravel production setup - multi-stage PHP-FPM/Nginx and health-gated services.
- Docker Compose documentation - services, volumes, networks, profiles, health checks.
- PostgreSQL current documentation - constraints, indexing, full-text search, time zones, backup/scaling foundations.
- Nginx documentation - PHP request processing, proxying, static assets, timeouts.
Local development services
- Mailpit documentation - SMTP capture, web UI, Docker and API testing.
- MinIO documentation - container deployment, persistent object storage, access policies, signed URLs.
Primary requirements source
Comprehensive Prompt for Facilities & Fleet Management CMMS, 36 pages, 40 sections. Reviewed in full, including document layout and extracted text. The roadmap above consolidates its module catalogue, workflows, tables, API groups, UX, security, integration, scalability, and delivery expectations.