Semantic Architecture
This page describes IronFlock’s data model: the core assets and how they relate to each other. While the Architecture Overview covers the system’s physical layers (edge, cloud, message broker), this page focuses on the logical structure — the relationships between projects, devices, apps, and data.
Entity Overview
Account
├─ App
│ └─ Release
└─ Project
├─ Device ──────────┐
│ └─ App Edge Component
├─ Group ───────────┘
├─ Release Installation
├─ Fleet Database
│ └─ Data Tables
├─ Dashboard
└─ AlarmCore Assets
Account
An account is the top-level identity — a person or organization signed in to IronFlock. An account owns projects and apps. Apps and projects are both direct children of an account but exist independently of each other.
App
An app is a deployable software package. Apps belong to an account, not to a project — a single app can be installed across many different projects. An app does not run anywhere on its own; it serves as a catalog entry whose releases can be installed on devices.
Release
A release is an immutable, versioned build of an app. Only releases in READY state can be installed on devices. Releases are immutable — to change an app’s behavior, a new release is published.
Project
A project is the primary isolation boundary. Everything inside a project — devices, groups, installations, data, dashboards, alarms — is invisible to other projects. Each project has its own WAMP realm on the message broker, a dedicated Fleet Database, and its own set of devices, groups, installations, dashboards, and alarms.
Device
A device is a physical or virtual Linux machine running the IronFlock agent. Each device belongs to exactly one project. A device hosts the edge components of installed releases — the containers that run locally on the hardware. A device can host edge components from multiple releases simultaneously and can be a member of multiple groups.
Group
A group is a logical collection of devices within a project, used for bulk operations. A device can belong to multiple groups (many-to-many). When a release is installed on a group, each member device receives an installation that can either inherit the group’s configuration or override it locally.
Release Installation
A release installation is the running instance of a specific release on a specific device. It is the join between a device and a release within a project. When installed via a group, each device’s installation can inherit or override the group’s configuration, providing fleet-wide defaults with per-device exceptions.
Group Installation
├─ Device A → inherits from group
├─ Device B → inherits from group
└─ Device C → overrides with custom configurationFleet Database
Each project has a dedicated Fleet Database — a PostgreSQL database with the TimescaleDB extension for time-series data. Edge components on devices publish telemetry via WAMP, the FleetDB service writes it to the project’s database, and the data is queryable by dashboards, the AI query service, and external tools.
Dashboard
A dashboard visualizes data from the project’s Fleet Database. Dashboards belong to a project and can combine data from multiple apps and devices into a single view.
Alarm
An alarm is a threshold-based alert rule within a project. Alarms monitor data in the Fleet Database and trigger notifications when conditions are met.
Entity Relationship Diagram
┌──────────┐
│ Account │
└──┬───┬───┘
│ │
│ │ owns 1:N
│ ▼
│ ┌─────────────────────┐
│ │ App │
│ └────────┬────────────┘
│ │ contains 1:N
│ ▼
│ ┌─────────────────────┐
│ │ Release │
│ └─────────────────────┘
│ ▲
│ │ references
│ owns 1:N │
▼ │
┌──────────────────────────────────────────────────────────────────┐
│ Project │
│ │
│ ┌──────────┐ N:N ┌──────────┐ │
│ │ Device │◆──────────◆│ Group │ │
│ └────┬─────┘ └────┬─────┘ │
│ │ hosts │ installs on │
│ │ edge components │ member devices │
│ │ 1:N │ │
│ │ ▼ │
│ │ ┌──────────────┐ │
│ └──────────────►│ Release │ (inherits or │
│ │ Installation│ overrides group) │
│ └──────────────┘ │
│ │
│ ┌───────────────────────┐ │
│ │ Fleet Database │ │
│ │ (TimescaleDB) │ │
│ │ ┌─────┐ ┌─────┐ │ │
│ │ │Table│ │Table│ ... │ │
│ │ └─────┘ └─────┘ │ │
│ └───────────────────────┘ │
│ ▲ │
│ │ queried by │
│ ┌───────────┴───────────┐ │
│ │ Dashboard │ │
│ └───────────────────────┘ │
│ │
│ ┌───────────────────────┐ │
│ │ Alarm │ │
│ │ (monitors FleetDB) │ │
│ └───────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘Relationship Summary
| Relationship | Type | Description |
|---|---|---|
| Account → Project | 1:N | One account owns multiple projects |
| Account → App | 1:N | One account owns multiple apps (independent of projects) |
| App → Release | 1:N | An app contains multiple versioned releases |
| Project → Device | 1:N | Each device belongs to exactly one project |
| Project → Group | 1:N | Groups are scoped to one project |
| Device ↔ Group | N:N | A device can be in multiple groups; a group contains multiple devices |
| Project → Fleet Database | 1:1 | Each project has its own dedicated database |
| Project → Dashboard | 1:N | Dashboards belong to a project and query its Fleet Database |
| Project → Alarm | 1:N | Alarms are scoped to a project and monitor its Fleet Database |
| Device → Release Installation | 1:N | A device hosts edge components from multiple release installations |
| Release Installation → Release | N:1 | Each installation references a specific release version |