# jingz/cmms architecture

> Architecture diagram of the GitHub repository jingz/cmms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jingz/cmms
- Repository: https://github.com/jingz/cmms

## Overview

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: [`app/controllers/workorders_controller.rb`](https://github.com/jingz/cmms/blob/master/app/controllers/workorders_controller.rb) (Workorders Ctrl), [`app/models/ability.rb`](https://github.com/jingz/cmms/blob/master/app/models/ability.rb) (Ability), [`config/routes.rb`](https://github.com/jingz/cmms/blob/master/config/routes.rb) (Routes), [`app/views/layouts/application.html.erb`](https://github.com/jingz/cmms/blob/master/app/views/layouts/application.html.erb) (App Layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_shell["Rails Shell"]
  node_node_application_controller["App Controller<br/>rails controller base"]
  node_node_routes["Routes<br/>request map<br/>[routes.rb]"]
  node_node_views_layout["App Layout<br/>server layout"]
end

subgraph group_grp_auth["Identity"]
  node_node_devise_views["Devise Views<br/>auth UI<br/>[new.html.erb]"]
  node_node_user_model[("Users<br/>account model<br/>[user.rb]")]
  node_node_role_model[("Roles<br/>access model<br/>[role.rb]")]
  node_node_permission_model[("Permissions<br/>access model<br/>[permission.rb]")]
  node_node_ability["Ability<br/>authorization rules<br/>[ability.rb]"]
end

subgraph group_grp_equipment["Equipment"]
  node_node_assets_controller["Assets Ctrl<br/>crud controller"]
  node_node_asset_model[("Assets<br/>equipment model<br/>[asset.rb]")]
  node_node_machine_model[("Machines<br/>equipment model<br/>[machine.rb]")]
  node_node_reference_models[("Refs<br/>reference data<br/>[asset_type.rb]")]
end

subgraph group_grp_workorders["Work Orders"]
  node_node_workorders_controller["Workorders Ctrl<br/>workflow controller"]
  node_node_workorder_model[("Workorders<br/>workflow model<br/>[workorder.rb]")]
  node_node_wo_state_log[("State Log<br/>audit model<br/>[wo_wf_state_log.rb]")]
  node_node_wo_part[("WO Parts<br/>usage model<br/>[wo_part.rb]")]
end

subgraph group_grp_inventory["Materials"]
  node_node_inventory_controller["Inventory Ctrl<br/>crud controller"]
  node_node_inventory_model[("Inventory<br/>stock model<br/>[inventory.rb]")]
  node_node_inv_type_model[("Item Types<br/>catalog model<br/>[inv_type.rb]")]
  node_node_inv_tran_model[("Inventory Tx<br/>transaction model<br/>[inv_tran.rb]")]
end

subgraph group_grp_request["Intake"]
  node_node_request_controller["Request Forms Ctrl<br/>intake controller"]
  node_node_request_model[("Requests<br/>intake model")]
  node_node_home_controller["Home<br/>dashboard controller<br/>[home_controller.rb]"]
end

node_node_routes -->|"routes to"| node_node_home_controller
node_node_routes -->|"routes to"| node_node_assets_controller
node_node_routes -->|"routes to"| node_node_workorders_controller
node_node_routes -->|"routes to"| node_node_inventory_controller
node_node_routes -->|"routes to"| node_node_request_controller
node_node_assets_controller -->|"reads/writes"| node_node_asset_model
node_node_assets_controller -->|"uses"| node_node_machine_model
node_node_asset_model -->|"classifies with"| node_node_reference_models
node_node_machine_model -->|"classifies with"| node_node_reference_models
node_node_workorders_controller -->|"reads/writes"| node_node_workorder_model
node_node_workorders_controller -->|"records"| node_node_wo_state_log
node_node_workorders_controller -->|"consumes"| node_node_wo_part
node_node_workorder_model -->|"references"| node_node_asset_model
node_node_workorder_model -->|"consumes"| node_node_inventory_model
node_node_wo_part -->|"deducts from"| node_node_inventory_model
node_node_inventory_controller -->|"reads/writes"| node_node_inventory_model
node_node_inventory_controller -->|"uses"| node_node_inv_type_model
node_node_inv_tran_model -->|"tracks"| node_node_inventory_model
node_node_request_controller -->|"reads/writes"| node_node_request_model
node_node_request_model -->|"feeds"| node_node_workorder_model
node_node_user_model -->|"assigned via"| node_node_role_model
node_node_user_model -->|"assigned via"| node_node_permission_model
node_node_ability -->|"evaluates"| node_node_user_model
node_node_devise_views -->|"authenticates"| node_node_user_model
node_node_workorders_controller -->|"authorizes"| node_node_ability
node_node_assets_controller -->|"authorizes"| node_node_ability
node_node_inventory_controller -->|"authorizes"| node_node_ability
node_node_request_controller -->|"authorizes"| node_node_ability
node_node_home_controller -->|"renders in"| node_node_views_layout
node_node_assets_controller -->|"renders in"| node_node_views_layout
node_node_workorders_controller -->|"renders in"| node_node_views_layout
node_node_inventory_controller -->|"renders in"| node_node_views_layout
node_node_request_controller -->|"renders in"| node_node_views_layout
node_node_application_controller -->|"centralizes"| node_node_ability
node_node_application_controller -->|"shares"| node_node_views_layout

click node_node_application_controller "https://github.com/jingz/cmms/blob/master/app/controllers/application_controller.rb"
click node_node_routes "https://github.com/jingz/cmms/blob/master/config/routes.rb"
click node_node_views_layout "https://github.com/jingz/cmms/blob/master/app/views/layouts/application.html.erb"
click node_node_devise_views "https://github.com/jingz/cmms/blob/master/app/views/devise/sessions/new.html.erb"
click node_node_user_model "https://github.com/jingz/cmms/blob/master/app/models/user.rb"
click node_node_role_model "https://github.com/jingz/cmms/blob/master/app/models/role.rb"
click node_node_permission_model "https://github.com/jingz/cmms/blob/master/app/models/permission.rb"
click node_node_ability "https://github.com/jingz/cmms/blob/master/app/models/ability.rb"
click node_node_assets_controller "https://github.com/jingz/cmms/blob/master/app/controllers/assets_controller.rb"
click node_node_asset_model "https://github.com/jingz/cmms/blob/master/app/models/asset.rb"
click node_node_machine_model "https://github.com/jingz/cmms/blob/master/app/models/machine.rb"
click node_node_reference_models "https://github.com/jingz/cmms/blob/master/app/models/asset_type.rb"
click node_node_workorders_controller "https://github.com/jingz/cmms/blob/master/app/controllers/workorders_controller.rb"
click node_node_workorder_model "https://github.com/jingz/cmms/blob/master/app/models/workorder.rb"
click node_node_wo_state_log "https://github.com/jingz/cmms/blob/master/app/models/wo_wf_state_log.rb"
click node_node_wo_part "https://github.com/jingz/cmms/blob/master/app/models/wo_part.rb"
click node_node_inventory_controller "https://github.com/jingz/cmms/blob/master/app/controllers/inventories_controller.rb"
click node_node_inventory_model "https://github.com/jingz/cmms/blob/master/app/models/inventory.rb"
click node_node_inv_type_model "https://github.com/jingz/cmms/blob/master/app/models/inv_type.rb"
click node_node_inv_tran_model "https://github.com/jingz/cmms/blob/master/app/models/inv_tran.rb"
click node_node_request_controller "https://github.com/jingz/cmms/blob/master/app/controllers/maintenance_request_forms_controller.rb"
click node_node_request_model "https://github.com/jingz/cmms/blob/master/app/models/maintenance_request_form.rb"
click node_node_home_controller "https://github.com/jingz/cmms/blob/master/app/controllers/home_controller.rb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_application_controller,node_node_routes,node_node_views_layout toneBlue
class node_node_devise_views,node_node_user_model,node_node_role_model,node_node_permission_model,node_node_ability toneAmber
class node_node_assets_controller,node_node_asset_model,node_node_machine_model,node_node_reference_models toneMint
class node_node_workorders_controller,node_node_workorder_model,node_node_wo_state_log,node_node_wo_part toneRose
class node_node_inventory_controller,node_node_inventory_model,node_node_inv_type_model,node_node_inv_tran_model toneIndigo
class node_node_request_controller,node_node_request_model,node_node_home_controller toneTeal
```

## Components

### Rails Shell

Framework entrypoints and shared application plumbing

- [App Controller](https://github.com/jingz/cmms/blob/master/app/controllers/application_controller.rb): rails controller base · Shared controller behavior for the monolith · `app/controllers/application_controller.rb`
- [Routes](https://github.com/jingz/cmms/blob/master/config/routes.rb): request map · HTTP routing into controllers · `config/routes.rb`
- [App Layout](https://github.com/jingz/cmms/blob/master/app/views/layouts/application.html.erb): server layout · Common server-rendered page shell · `app/views/layouts/application.html.erb`

### Identity

Authentication and role-based authorization

- [Devise Views](https://github.com/jingz/cmms/blob/master/app/views/devise/sessions/new.html.erb): auth UI · Login, registration, reset, and unlock screens · `app/views/devise/sessions/new.html.erb`
- [Users](https://github.com/jingz/cmms/blob/master/app/models/user.rb): account model · User accounts and association hub · `app/models/user.rb`
- [Roles](https://github.com/jingz/cmms/blob/master/app/models/role.rb): access model · Role-based authorization structure · `app/models/role.rb`
- [Permissions](https://github.com/jingz/cmms/blob/master/app/models/permission.rb): access model · Fine-grained permission assignments · `app/models/permission.rb`
- [Ability](https://github.com/jingz/cmms/blob/master/app/models/ability.rb): authorization rules · Application-level authorization logic · `app/models/ability.rb`

### Equipment

Assets, machines, and supporting reference data

- [Assets Ctrl](https://github.com/jingz/cmms/blob/master/app/controllers/assets_controller.rb): crud controller · Asset management entrypoint · `app/controllers/assets_controller.rb`
- [Assets](https://github.com/jingz/cmms/blob/master/app/models/asset.rb): equipment model · Physical asset records and lifecycle data · `app/models/asset.rb`
- [Machines](https://github.com/jingz/cmms/blob/master/app/models/machine.rb): equipment model · Machine records and status metadata · `app/models/machine.rb`
- [Refs](https://github.com/jingz/cmms/blob/master/app/models/asset_type.rb): reference data · Asset types, machine types, contacts, manufacturers, vendors, and units of measure · `app/models/asset_type.rb`

### Work Orders

Workflow-driven maintenance execution

- [Workorders Ctrl](https://github.com/jingz/cmms/blob/master/app/controllers/workorders_controller.rb): workflow controller · Stateful work order operations · `app/controllers/workorders_controller.rb`
- [Workorders](https://github.com/jingz/cmms/blob/master/app/models/workorder.rb): workflow model · Core maintenance execution records · `app/models/workorder.rb`
- [State Log](https://github.com/jingz/cmms/blob/master/app/models/wo_wf_state_log.rb): audit model · Work order state history and transitions · `app/models/wo_wf_state_log.rb`
- [WO Parts](https://github.com/jingz/cmms/blob/master/app/models/wo_part.rb): usage model · Parts consumed by work orders · `app/models/wo_part.rb`

### Materials

Inventory items and stock transactions

- [Inventory Ctrl](https://github.com/jingz/cmms/blob/master/app/controllers/inventories_controller.rb): crud controller · Inventory and item-type management · `app/controllers/inventories_controller.rb`
- [Inventory](https://github.com/jingz/cmms/blob/master/app/models/inventory.rb): stock model · Item master records and quantities · `app/models/inventory.rb`
- [Item Types](https://github.com/jingz/cmms/blob/master/app/models/inv_type.rb): catalog model · Inventory classification and grouping · `app/models/inv_type.rb`
- [Inventory Tx](https://github.com/jingz/cmms/blob/master/app/models/inv_tran.rb): transaction model · Stock movement history · `app/models/inv_tran.rb`

### Intake

Maintenance request capture and dashboard entry

- [Request Forms Ctrl](https://github.com/jingz/cmms/blob/master/app/controllers/maintenance_request_forms_controller.rb): intake controller · Maintenance request submission and listing · `app/controllers/maintenance_request_forms_controller.rb`
- [Requests](https://github.com/jingz/cmms/blob/master/app/models/maintenance_request_form.rb): intake model · Maintenance request forms that can seed work · `app/models/maintenance_request_form.rb`
- [Home](https://github.com/jingz/cmms/blob/master/app/controllers/home_controller.rb): dashboard controller · Landing page and summary entrypoint · `app/controllers/home_controller.rb`

## Connections

- 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
