How jingz/cmms works
1. This is a single Rails monolith for a CMMS domain. The request path is the standard Rails flow: browser request → controller → ActiveRecord model(s) → database → HAML/ERB view. There is no evidence of separate frontend, API service, or background worker architecture in this repo.
2. The application is organized by business domain rather than technical layers. The main user-facing controllers are for assets, machines, inventory types, inventories, work orders, maintenance request forms, users, plus a home/dashboard controller. Most of these appear to be CRUD-style resource controllers with form partials and show/index pages.
3. Work orders are the most workflow-heavy subsystem and likely the core of the application. The workorders views include multiple step pages and partials for info, material list, next action, state info, state log, and update forms, which suggests state-driven processing rather than simple record editing. Supporting models like wo_part and wo_wf_state_log indicate parts consumption and workflow audit/history are part of the work order lifecycle.
4. Equipment management is split across asset and machine concepts. The models include asset, asset_type, machine, ref_machine_type, contact, manufacturer, vendor, and uom, which together represent equipment metadata, classification, contacts, and supporting reference data. The readme frames this area as the equipment history / hierarchy / condition monitoring side of the CMMS.
5. Inventory is its own bounded subsystem and is tied to maintenance operations. inventory, inv_type, and inv_tran suggest item master data plus transaction history, with the UI exposing inventory listing and forms. In the CMMS context, this subsystem likely feeds work order material usage and stock tracking rather than acting as a standalone stock management app.
6. Preventive maintenance is represented in the domain model even though there is no dedicated PM controller in the tree. The pm, rcm_action, requisition, and reference maintenance models indicate PM definitions, maintenance types/statuses, and planned work generation concepts. This fits the readme’s description of PM schedules that generate work orders.
7. Security is handled with Devise for authentication and a custom role/permission model for authorization. The repo includes user, role, permission, roles_users, permissions_users, and ability.rb, which implies role-based access control is enforced in application code rather than through an external identity service. Seed data and Devise views support account setup, login, registration, password reset, and unlock flows.
8. The UI is server-rendered and view-partial heavy. Views are split between HAML and ERB, with reusable partials for forms, status blocks, user lookup, and work order sections. This suggests most interactivity is page-based and form-driven, not client-side SPA behavior.
9. The persistence layer is classic ActiveRecord backed by a relational database. The large migration history and db/schema.rb show the data model is central to the app’s architecture, with many lookup/reference tables alongside operational tables. This repo is especially strong as a data model for CMMS concepts like assets, work orders, inventory, labor, vendors, and permissions.
10. The supporting layers are conventional Rails app infrastructure: config/routes.rb, environment configs, initializers, Rakefile, and config.ru. Static assets use an older Rails stack with Bootstrap, jQuery, Prototype-era JavaScript files, and custom CSS, which suggests a legacy Rails 3 application rather than a modern asset-bundler setup.
11. For an architecture diagram, the most important boundaries are: authentication/authorization, equipment/asset management, work order workflow, inventory/materials, and maintenance request intake. Most data flows converge on work orders, which appear to consume equipment context, inventory parts, and workflow state logs, then feed history and reporting back into the equipment and maintenance domains.
Main entry points: workorders_controller.rb Workorders Ctrl · ability.rb Ability · routes.rb Routes · application.html.erb App Layout
Components 23
Rails Shell
Framework entrypoints and shared application plumbing
- App Controller · Shared controller behavior for the monolith
app/controllers/application_controller.rb - Routes · HTTP routing into controllers
config/routes.rb - App Layout · Common server-rendered page shell
app/views/layouts/application.html.erb
Identity
Authentication and role-based authorization
- Devise Views · Login, registration, reset, and unlock screens
app/views/devise/sessions/new.html.erb - Users · User accounts and association hub
app/models/user.rb - Roles · Role-based authorization structure
app/models/role.rb - Permissions · Fine-grained permission assignments
app/models/permission.rb - Ability · Application-level authorization logic
app/models/ability.rb
Equipment
Assets, machines, and supporting reference data
- Assets Ctrl · Asset management entrypoint
app/controllers/assets_controller.rb - Assets · Physical asset records and lifecycle data
app/models/asset.rb - Machines · Machine records and status metadata
app/models/machine.rb - Refs · Asset types, machine types, contacts, manufacturers, vendors, and units of measure
app/models/asset_type.rb
Work Orders
Workflow-driven maintenance execution
- Workorders Ctrl · Stateful work order operations
app/controllers/workorders_controller.rb - Workorders · Core maintenance execution records
app/models/workorder.rb - State Log · Work order state history and transitions
app/models/wo_wf_state_log.rb - WO Parts · Parts consumed by work orders
app/models/wo_part.rb
Materials
Inventory items and stock transactions
- Inventory Ctrl · Inventory and item-type management
app/controllers/inventories_controller.rb - Inventory · Item master records and quantities
app/models/inventory.rb - Item Types · Inventory classification and grouping
app/models/inv_type.rb - Inventory Tx · Stock movement history
app/models/inv_tran.rb
Intake
Maintenance request capture and dashboard entry
- Request Forms Ctrl · Maintenance request submission and listing
app/controllers/maintenance_request_forms_controller.rb - Requests · Maintenance request forms that can seed work
app/models/maintenance_request_form.rb - Home · Landing page and summary entrypoint
app/controllers/home_controller.rb
Connections 35
- Routes → Home: routes to · Landing page routing
- Routes → Assets Ctrl: routes to · Equipment CRUD routing
- Routes → Workorders Ctrl: routes to · Work order workflow routing
- Routes → Inventory Ctrl: routes to · Inventory routing
- Routes → Request Forms Ctrl: routes to · Maintenance request intake routing
- Assets Ctrl → Assets: reads/writes · Asset persistence via ActiveRecord
- Assets Ctrl → Machines: uses · Machine context for equipment pages
- Assets → Refs: classifies with · Asset metadata and lookup tables
- Machines → Refs: classifies with · Machine types and reference data
- Workorders Ctrl → Workorders: reads/writes · Core workflow state persistence
- Workorders Ctrl → State Log: records · Workflow transition history
- Workorders Ctrl → WO Parts: consumes · Material usage and parts logging
- Workorders → Assets: references · Work orders are tied to equipment
- Workorders → Inventory: consumes · Material allocations and stock impact
- WO Parts → Inventory: deducts from · Part consumption affects inventory
- Inventory Ctrl → Inventory: reads/writes · Inventory CRUD operations
- Inventory Ctrl → Item Types: uses · Inventory type browsing and forms
- Inventory Tx → Inventory: tracks · Transaction history for inventory items
- Request Forms Ctrl → Requests: reads/writes · Maintenance request intake persistence
- Requests → Workorders: feeds · Requests can become work orders
- Users → Roles: assigned via · Role membership through join table
- Users → Permissions: assigned via · Permission membership through join table
- Ability → Users: evaluates · Authorization checks against current user
- Devise Views → Users: authenticates · Account lifecycle and sign-in UI
- Workorders Ctrl → Ability: authorizes · Restricted workflow actions
- Assets Ctrl → Ability: authorizes · Protected equipment actions
- Inventory Ctrl → Ability: authorizes · Protected inventory actions
- Request Forms Ctrl → Ability: authorizes · Protected request intake actions
- Home → App Layout: renders in · Server-rendered dashboard pages
- Assets Ctrl → App Layout: renders in · Server-rendered CRUD pages
- Workorders Ctrl → App Layout: renders in · Step-based workflow pages
- Inventory Ctrl → App Layout: renders in · Server-rendered inventory pages
- Request Forms Ctrl → App Layout: renders in · Server-rendered intake pages
- App Controller → Ability: centralizes · Common controller-side security hook
- App Controller → App Layout: shares · Common rendering context