# iotile/iotile-companion-mobile-app architecture

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

- Interactive diagram: https://gitdiagram.com/iotile/iotile-companion-mobile-app
- Repository: https://github.com/iotile/iotile-companion-mobile-app

## Overview

IOTile-M is a hybrid Ionic mobile app for customers to interact with IOTile devices and the IOTile.cloud Dashboard. The main workflow takes a user through app navigation and project/device screens, where they can discover devices, collect device data, and synchronize project information; report handling and upload support that workflow. Other major branches include account access, firmware updates, device-specific pages and settings, and local persistence. The graph uses sampled source and README statements; unsampled features are grouped at their existing directories, and unverified links are omitted.

Main entry points: [`app/main/main.ts`](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/main.ts) (Main module), [`app/main/controllers/active-project-ctrl.ts`](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/controllers/active-project-ctrl.ts) (Project screens), [`app/main/pages/controllers`](https://github.com/iotile/iotile-companion-mobile-app/tree/master/app/main/pages/controllers) (Device interaction), [`app/packages/ng-iotile-app/report-serv.ts`](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/packages/ng-iotile-app/report-serv.ts) (Report handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_app_entry["App entry<br/>[app.ts]"]
  node_app_module["Main module<br/>[main.ts]"]
  node_routing["Navigation and routes<br/>[main.route.ts]"]
  node_startup["Startup and session guard<br/>[main.run.ts]"]
end

subgraph group_projects["Projects and devices"]
  node_access["Account access"]
  node_project_screens["Project screens"]
  node_project_setup["Project setup"]
  node_device_screens["Device interaction"]
  node_notes["Device notes<br/>[note-modal.ts]"]
end

subgraph group_services["Device and data services"]
  node_device_core["Device abstraction<br/>[device-base.ts]"]
  node_device_adapter["IOTile adapter<br/>[main.ts]"]
  node_firmware["Firmware updates<br/>[firmware-serv.ts]"]
  node_report_service["Report handling<br/>[report-serv.ts]"]
  node_upload["Device data upload"]
  node_cache["Project and device cache<br/>[cache-serve.ts]"]
  node_filesystem[("Local filesystem<br/>[filesystem-serv.ts]")]
end

subgraph group_features["Device features"]
  node_settings["Device settings"]
  node_widgets["Device widgets"]
  node_geolocation["Geolocation"]
  node_websocket["WebSocket server"]
end

node_customer(("Customer"))
node_cloud["IOTile.cloud"]
node_iotile_devices["IOTile devices"]

node_customer -->|"uses"| node_app_entry
node_app_entry -->|"loads"| node_app_module
node_app_module -->|"imports"| node_routing
node_app_module -->|"imports"| node_startup
node_app_module -->|"registers"| node_device_adapter
node_startup -->|"guards access"| node_access
node_customer -->|"uses"| node_project_screens
node_project_screens -->|"scans"| node_iotile_devices
node_project_screens -->|"syncs project"| node_cloud
node_project_setup -.->|"sets up project"| node_cloud
node_notes -->|"posts note"| node_cloud
node_notes -->|"captures location"| node_geolocation
node_device_core -->|"uses"| node_cache
node_device_core -->|"uses"| node_report_service
node_firmware -->|"reads and writes"| node_filesystem
node_report_service -->|"reads and writes"| node_filesystem
node_upload -->|"uses reports"| node_report_service
node_upload -->|"uses cache"| node_cache
node_customer -->|"uses"| node_device_screens
node_device_screens -.->|"configures"| node_settings
node_device_screens -.->|"views"| node_widgets
node_device_adapter -.->|"connects"| node_iotile_devices

click node_app_entry "https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/app.ts"
click node_app_module "https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/main.ts"
click node_routing "https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/main.route.ts"
click node_startup "https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/main.run.ts"
click node_access "https://github.com/iotile/iotile-companion-mobile-app/tree/master/app/main/controllers"
click node_project_screens "https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/controllers/active-project-ctrl.ts"
click node_project_setup "https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/controllers/setup-claim-ctrl.ts"
click node_device_screens "https://github.com/iotile/iotile-companion-mobile-app/tree/master/app/main/pages/controllers"
click node_notes "https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/controllers/modals/note-modal.ts"
click node_device_core "https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/packages/ng-iotile-app/classes/device-base.ts"
click node_device_adapter "https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/main.ts"
click node_firmware "https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/packages/ng-iotile-app/firmware/firmware-serv.ts"
click node_report_service "https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/packages/ng-iotile-app/report-serv.ts"
click node_upload "https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/packages/ng-iotile-app/uploader-service.ts"
click node_cache "https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/packages/ng-iotile-app/cache-serve.ts"
click node_filesystem "https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/packages/ng-iotile-app/filesystem-serv.ts"
click node_settings "https://github.com/iotile/iotile-companion-mobile-app/tree/master/app/main/pages/controllers/settings"
click node_widgets "https://github.com/iotile/iotile-companion-mobile-app/tree/master/app/main/directives/widgets"
click node_geolocation "https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/controllers/device-geolocate-ctrl.ts"
click node_websocket "https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/packages/ng-iotile-app/classes/websocket-server.ts"

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_app_entry,node_app_module,node_routing,node_startup toneBlue
class node_access,node_project_screens,node_project_setup,node_device_screens,node_notes toneAmber
class node_device_core,node_device_adapter,node_firmware,node_report_service,node_upload,node_cache,node_filesystem toneMint
class node_settings,node_widgets,node_geolocation,node_websocket toneRose
class node_customer,node_cloud,node_iotile_devices toneIndigo
```

## Components

### App shell

- [App entry](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/app.ts): `app/app.ts`
- [Main module](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/main.ts): `app/main/main.ts`
- [Navigation and routes](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/main.route.ts): `app/main/main.route.ts`
- [Startup and session guard](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/main.run.ts): `app/main/main.run.ts`

### Projects and devices

- [Account access](https://github.com/iotile/iotile-companion-mobile-app/tree/master/app/main/controllers): `app/main/controllers`
- [Project screens](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/controllers/active-project-ctrl.ts): `app/main/controllers/active-project-ctrl.ts`
- [Project setup](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/controllers/setup-claim-ctrl.ts): `app/main/controllers/setup-claim-ctrl.ts`
- [Device interaction](https://github.com/iotile/iotile-companion-mobile-app/tree/master/app/main/pages/controllers): `app/main/pages/controllers`
- [Device notes](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/controllers/modals/note-modal.ts): `app/main/controllers/modals/note-modal.ts`

### Device and data services

- [Device abstraction](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/packages/ng-iotile-app/classes/device-base.ts): `app/packages/ng-iotile-app/classes/device-base.ts`
- [IOTile adapter](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/main.ts): `app/main/main.ts`
- [Firmware updates](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/packages/ng-iotile-app/firmware/firmware-serv.ts): `app/packages/ng-iotile-app/firmware/firmware-serv.ts`
- [Report handling](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/packages/ng-iotile-app/report-serv.ts): `app/packages/ng-iotile-app/report-serv.ts`
- [Device data upload](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/packages/ng-iotile-app/uploader-service.ts): `app/packages/ng-iotile-app/uploader-service.ts`
- [Project and device cache](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/packages/ng-iotile-app/cache-serve.ts): `app/packages/ng-iotile-app/cache-serve.ts`
- [Local filesystem](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/packages/ng-iotile-app/filesystem-serv.ts): `app/packages/ng-iotile-app/filesystem-serv.ts`

### Device features

- [Device settings](https://github.com/iotile/iotile-companion-mobile-app/tree/master/app/main/pages/controllers/settings): `app/main/pages/controllers/settings`
- [Device widgets](https://github.com/iotile/iotile-companion-mobile-app/tree/master/app/main/directives/widgets): `app/main/directives/widgets`
- [Geolocation](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/main/controllers/device-geolocate-ctrl.ts): `app/main/controllers/device-geolocate-ctrl.ts`
- [WebSocket server](https://github.com/iotile/iotile-companion-mobile-app/blob/master/app/packages/ng-iotile-app/classes/websocket-server.ts): `app/packages/ng-iotile-app/classes/websocket-server.ts`

### Other components

- **Customer**
- **IOTile.cloud**
- **IOTile devices**

## Connections

- Customer → App entry: uses
- App entry → Main module: loads (evidence: `app/app.ts`)
- Main module → Navigation and routes: imports (evidence: `app/main/main.ts`)
- Main module → Startup and session guard: imports (evidence: `app/main/main.ts`)
- Main module → IOTile adapter: registers (evidence: `app/main/main.ts`)
- Startup and session guard → Account access: guards access (evidence: `app/main/main.run.ts`)
- Customer → Project screens: uses
- Project screens → IOTile devices: scans (evidence: `app/main/controllers/active-project-ctrl.ts`)
- Project screens → IOTile.cloud: syncs project (evidence: `app/main/controllers/active-project-ctrl.ts`)
- Project setup → IOTile.cloud: sets up project
- Device notes → IOTile.cloud: posts note (evidence: `app/main/controllers/modals/note-modal.ts`)
- Device notes → Geolocation: captures location (evidence: `app/main/controllers/modals/note-modal.ts`)
- Device abstraction → Project and device cache: uses (evidence: `app/packages/ng-iotile-app/classes/device-base.ts`)
- Device abstraction → Report handling: uses (evidence: `app/packages/ng-iotile-app/classes/device-base.ts`)
- Firmware updates → Local filesystem: reads and writes (evidence: `app/packages/ng-iotile-app/firmware/firmware-serv.ts`)
- Report handling → Local filesystem: reads and writes (evidence: `app/packages/ng-iotile-app/report-serv.ts`)
- Device data upload → Report handling: uses reports (evidence: `app/packages/ng-iotile-app/uploader-service.ts`)
- Device data upload → Project and device cache: uses cache (evidence: `app/packages/ng-iotile-app/uploader-service.ts`)
- Customer → Device interaction: uses
- Device interaction → Device settings: configures
- Device interaction → Device widgets: views
- IOTile adapter → IOTile devices: connects
