Arquitectura Semántica

Esta página describe el modelo de datos de IronFlock: los activos principales y cómo se relacionan entre sí. Mientras que la Descripción General de la Arquitectura cubre las capas físicas del sistema (edge, cloud, message broker), aquí nos enfocamos en la estructura lógica — las relaciones entre proyectos, dispositivos, apps y datos.

Visión General de Entidades

Cuenta
 ├─ App
 │   └─ Release
 └─ Proyecto
     ├─ Dispositivo ─────────┐
     │   └─ Componente Edge
     ├─ Grupo ───────────────┘
     ├─ Instalación de Release
     ├─ Fleet Database
     │   └─ Tablas de datos
     ├─ Dashboard
     └─ Alarma

Activos Principales

Cuenta

Una cuenta es la identidad de nivel superior — una persona u organización registrada en IronFlock. Una cuenta posee proyectos y apps. Apps y proyectos son hijos directos de una cuenta pero existen de forma independiente entre sí.

App

Una app es un paquete de software desplegable. Las apps pertenecen a una cuenta, no a un proyecto — una misma app puede instalarse en muchos proyectos diferentes. Una app no se ejecuta por sí sola; sirve como entrada de catálogo cuyos releases pueden instalarse en dispositivos.

Release

Un release es una compilación inmutable y versionada de una app. Solo los releases en estado READY pueden instalarse en dispositivos. Los releases son inmutables — para cambiar el comportamiento de una app, se publica un nuevo release.

Proyecto

Un proyecto es el límite principal de aislamiento. Todo dentro de un proyecto — dispositivos, grupos, instalaciones, datos, dashboards, alarmas — es invisible para otros proyectos. Cada proyecto tiene su propio realm WAMP en el message broker, una Fleet Database dedicada y su propio conjunto de dispositivos, grupos, instalaciones, dashboards y alarmas.

Dispositivo

Un dispositivo es una máquina Linux física o virtual que ejecuta el agente de IronFlock. Cada dispositivo pertenece a exactamente un proyecto. Un dispositivo aloja los componentes edge de los releases instalados — los contenedores que se ejecutan localmente en el hardware. Un dispositivo puede alojar componentes edge de múltiples releases simultáneamente y puede ser miembro de múltiples grupos.

Grupo

Un grupo es una colección lógica de dispositivos dentro de un proyecto, utilizada para operaciones masivas. Un dispositivo puede pertenecer a múltiples grupos (muchos a muchos). Cuando un release se instala en un grupo, cada dispositivo miembro recibe una instalación que puede heredar la configuración del grupo o sobrescribirla localmente.

Instalación de Release

Una instalación de release es la instancia en ejecución de un release específico en un dispositivo específico. Es la unión entre un dispositivo y un release dentro de un proyecto. Cuando se instala a través de un grupo, cada instalación de dispositivo puede heredar o sobrescribir la configuración del grupo, proporcionando valores predeterminados a nivel de flota con excepciones por dispositivo.

Instalación de Grupo
  ├─ Dispositivo A → hereda del grupo
  ├─ Dispositivo B → hereda del grupo
  └─ Dispositivo C → sobrescribe con configuración personalizada

Fleet Database

Cada proyecto tiene una Fleet Database dedicada — una base de datos PostgreSQL con la extensión TimescaleDB para datos de series temporales. Los componentes edge en los dispositivos publican telemetría vía WAMP, el servicio FleetDB la escribe en la base de datos del proyecto, y los datos son consultables por dashboards, el servicio de consultas IA y herramientas externas.

Dashboard

Un dashboard visualiza datos de la Fleet Database del proyecto. Los dashboards pertenecen a un proyecto y pueden combinar datos de múltiples apps y dispositivos en una sola vista.

Alarma

Una alarma es una regla de alerta basada en umbrales dentro de un proyecto. Las alarmas monitorean datos en la Fleet Database y activan notificaciones cuando se cumplen las condiciones.

Diagrama de Relación de Entidades

┌──────────┐
│  Cuenta  │
└──┬───┬───┘
   │   │
   │   │ posee 1:N
   │   ▼
   │  ┌─────────────────────┐
   │  │        App          │
   │  └────────┬────────────┘
   │           │ contiene 1:N
   │           ▼
   │  ┌─────────────────────┐
   │  │      Release        │
   │  └─────────────────────┘
   │            ▲
   │            │ referencia
   │ posee 1:N │
   ▼            │
┌──────────────────────────────────────────────────────────────────┐
│                          Proyecto                                │
│                                                                  │
│  ┌─────────────┐  N:N   ┌──────────┐                            │
│  │ Dispositivo │◆──────◆│  Grupo   │                            │
│  └──────┬──────┘        └────┬─────┘                            │
│         │ aloja              │ instala en                        │
│         │ componentes edge   │ dispositivos miembros             │
│         │ 1:N                │                                   │
│         │                    ▼                                   │
│         │            ┌──────────────┐                            │
│         └───────────►│ Instalación  │   (hereda o               │
│                      │ de Release   │    sobrescribe grupo)     │
│                      └──────────────┘                            │
│                                                                  │
│       ┌───────────────────────┐                                  │
│       │    Fleet Database     │                                  │
│       │   (TimescaleDB)       │                                  │
│       │  ┌─────┐ ┌─────┐      │                                  │
│       │  │Tabla│ │Tabla│ ... │                                  │
│       │  └─────┘ └─────┘      │                                  │
│       └───────────────────────┘                                  │
│                   ▲                                              │
│                   │ consultado por                               │
│       ┌───────────┴───────────┐                                  │
│       │      Dashboard        │                                  │
│       └───────────────────────┘                                  │
│                                                                  │
│       ┌───────────────────────┐                                  │
│       │       Alarma          │                                  │
│       │ (monitorea FleetDB)   │                                  │
│       └───────────────────────┘                                  │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

Resumen de Relaciones