🚁 Aircraft Custodian & dTwin Strategy

🎯 Solution Concept

The Aircraft Custodian is split into two Docker microservices: Custodian Software (one process per drone) and Custodian APIs (the shared REST layer). Between them sits RTTP — Real Time Telemetry Processing, the central telemetry hub. All GCS Plugins and the Cloud Broker stream telemetry into RTTP; RTTP (encompassing Flink event processing) normalises and routes data to the Custodian APIs, which write the dTwin to tenant.drones. The same API contract is consumed by the browser UI, MCP agents, and the Flight_Live microservice.

① System Architecture — Where & How Drone Data Comes In

This is the structural view: where drone records originate, how they enter tenant.drones, and where identity propagates. It corresponds directly to the architecture whiteboard from the Jun 15 Daily Technical Review.

What this diagram says

• FLYsafe.software DLB.Drones is the inventory source of truth — brand, model, serial, TC registration, core RID fields. Owned by Yves; pulled from in two environments (DEV, PROD).
• The Import process (Steve Smith) is the one-way bridge from DLB into each tenant’s rtm-app-db.drones. It writes only DLB-sourced columns; RTM-managed columns are left for the Custodian and operators to manage.
• tenant.drones (T.Drones) is the operational config plane — one row per drone, keyed by (tenant, serial). Carries both DLB-sourced fields (read-only via sync) and RTM-managed fields (writable via Custodian APIs).
• Aircraft Custodian maintains its drone’s row in tenant.drones — that is its primary job. Telemetry enters via the GCS Plugins (§③), gets normalized, and the Custodian writes state through the API.
• Keycloak.θ.Drone registers each drone as a user with ID <tenant>-<SN>. This is auth-only — no drone metadata lives here.
• AADMS.{schema}.tenant.Drones is the cross-tenant lookup. ADS-B records arrive carrying only callsign; AADMS resolves callsign to the correct (tenant, serial) so the record can be routed to the right tenant’s pipeline.
• FSL RTM Map (JC’s frontend) uses the Custodian APIs to read state and write RTM-managed operator changes — the same APIs the Custodian itself uses.

② The Custodian Role — Three Obligations

An Aircraft Custodian is the entity inside FLYsafe.live RTM responsible for representing one specific drone. There is exactly one Custodian per drone per tenant. The Custodian carries three formal obligations, each independently observable through the state it maintains in tenant.drones.

③ GCS Plugins — How Telemetry Enters the System

The data path into the Aircraft Custodian is a plugin embedded inside the operator’s GCS — not a separate edge container the operator has to install and manage. Two plugin form factors cover the bulk of our drone fleet:

Why this is materially different from v1.4–v1.5

Prior versions described the integration as a Python Aircraft Agent container per drone, with adapters for MAVLink/DJI/DroneSense/ADS-B. v1.6 moves the integration point into the operator’s GCS. The Custodian itself becomes a server-side component that takes API input from the plugin, normalizes/persists state, and exposes APIs to consumers. Benefits:

③.5 Centralized Configuration Management via Custodian APIs

The Aircraft Custodian doesn’t just maintain telemetry-derived state — it’s also the system of record for how each aircraft connects. The protocol-specific configuration for every supported telemetry source (MAVLink autopilot, DJI FlightHub 2, DJI Cloud API, ADS-B) is stored in tenant.drones and exposed through the Custodian APIs. This is what makes FLYsafe.live RTM a centrally-managed fleet platform rather than a collection of one-off integrations.

Per-protocol configuration the Custodian manages

④ State Lives in tenant.drones

The dTwin is a row in tenant.drones. The Custodian maintains it. Everything that wants to know the current state of an aircraft reads through the API surface that sits on top of this table.

DLB Field Cross-Reference

The table below maps every field the FLYsafe.software DLB exposes for a drone to its role in the Aircraft Custodian. Stored in dlb_drones fields are persisted verbatim in drones.dlb_drones and surfaced through the v_dtwin view — they are never copied into drones.drones. Seeds RTM default fields supply initial values the Import process seeds into drones.drones on first insert; operators may later override via Custodian APIs. FK link fields are written to drones.drones once to establish the foreign key relationship.

Schema: Raw DLB Import Table (drones.dlb_drones)

Stores every field from the DLB API with column names exactly as they arrive. This is the upsert target for the Import process (Steve Smith). No renaming — the schema matches the DLB source verbatim, making forward sync and any future column additions straightforward.

-- drones.dlb_drones · /tenant/rtm-app-db/schema/dlb_drones.sql
-- Raw DLB import table. Column names match the DLB API verbatim.
-- Written by the Import process (Steve Smith). Never modified by RTM side.
CREATE TABLE IF NOT EXISTS drones.dlb_drones (

  -- DLB primary identity (exact field names from DLB API)
  guid                             TEXT        NOT NULL,        -- DLB drone UUID
  serial_number                    TEXT        NOT NULL,
  name                             TEXT,                        -- drone display name
  brand                            TEXT,
  model                            TEXT,
  drone_type                       TEXT,
  status                           TEXT,                        -- e.g. Airworthy, Grounded
  color                            TEXT,

  -- Regulatory / operational identifiers
  identification_number            TEXT,                        -- TC registration  (AS TC_Registration in v_dtwin)
  inventory_number                 TEXT,                        -- operator callsign (AS Callsign in v_dtwin)

  -- Hardware & firmware
  hardware_version                 TEXT,                        -- e.g. Pixhawk Cube
  firmware_version                 TEXT,                        -- e.g. 4.0.7
  flight_controller_serial_number  TEXT,
  controller_serial_number         TEXT,
  controller_serial_number2        TEXT,

  -- Performance specs (stored as TEXT to match DLB source; cast on use)
  max_horizontal_speed             TEXT,                        -- seeds horizontal_speed_ms in drones.drones
  max_vertical_speed               TEXT,                        -- seeds vertical_speed_ms in drones.drones
  max_flight_time                  TEXT,                        -- rated endurance (minutes)
  payload_capacity                 TEXT,                        -- kg
  weight                           TEXT,
  propulsion_type                  TEXT,                        -- ELECTRIC | ICE | HYBRID

  -- Ownership & financial
  company_guid                     TEXT,
  user_guid                        TEXT,
  insurable_value                  TEXT,
  purchase_date                    TEXT,                        -- ISO-8601 string from DLB; cast on use
  tech_number                      TEXT,
  notes                            TEXT,

  -- Import bookkeeping
  imported_at                      TIMESTAMPTZ NOT NULL DEFAULT now(),

  PRIMARY KEY (guid)
);

CREATE UNIQUE INDEX IF NOT EXISTS idx_dlb_drones_serial
  ON drones.dlb_drones (serial_number);

Schema: Custodian dTwin Table (drones.drones)

The canonical per-drone RTM state table maintained by the Aircraft Custodian. Holds only RTM-specific data — configuration, live state, and the link key (dlb_guid) back to drones.dlb_drones. All DLB identity fields (name, brand, model, callsign, TC registration, etc.) live exclusively in dlb_drones and are accessed via the v_dtwin view. Speed defaults are seeded from dlb_drones on first insert and may be overridden by the operator.

-- /tenant/rtm-app-db/schema/drones.sql
-- One row per drone per tenant. Maintained by the Custodian. PK = (tenant, serial).
-- DLB identity data lives in drones.dlb_drones; join via dlb_guid. Use v_dtwin for the full dTwin record.
CREATE SCHEMA IF NOT EXISTS drones;

CREATE TABLE drones.drones (
  -- Core identity
  tenant_id                         text NOT NULL,
  serial_number                     text NOT NULL,
  dlb_guid                          text NOT NULL,            -- FK → drones.dlb_drones.guid

  -- Custodian configuration (RTM-managed; written via Custodian APIs)
  adapter_type                      text DEFAULT 'mavlink'::text NOT NULL,   -- mavlink | dji_fh2 | dronesense
  adapter_config                    jsonb DEFAULT '{}'::jsonb NOT NULL,
  publish_rate_hz                   int4 DEFAULT 4 NOT NULL,

  -- OI defaults & FLYplan automation (speeds seeded from dlb_drones on first insert)
  oi_automation_enabled             bool DEFAULT false NOT NULL,
  horizontal_speed_ms               float8 DEFAULT 15.0 NOT NULL,   -- seeded from dlb_drones.max_horizontal_speed
  vertical_speed_ms                 float8 DEFAULT 6.0 NOT NULL,    -- seeded from dlb_drones.max_vertical_speed
  flight_volume_m                   float8 DEFAULT 56.0 NOT NULL,
  contingency_vol_m                 float8 DEFAULT 150.0 NOT NULL,

  -- OI geometry parameters (see OI Configuration — New Required Fields below)
  oi_automation_square_m            float8 DEFAULT 700.0 NOT NULL,   -- OI square side (m); valid 350–1400
  oi_automation_radius_m            float8 DEFAULT 400.0 NOT NULL,   -- OI radius (m); valid 200–800
  oi_automation_amend_min_trigger_m float8 DEFAULT 100.0 NOT NULL,   -- OI amend min trigger (m); valid 50–200
  oi_automation_amend_max_alt_agl_m float8 DEFAULT 300.0 NOT NULL,   -- OI amend max altitude AGL (m)
  oi_automation_amend_enabled       bool DEFAULT false NOT NULL,

  -- ADS-B provisioning
  adsb_in_enabled                   bool DEFAULT false NOT NULL,
  adsb_out_enabled                  bool DEFAULT false NOT NULL,
  adsb_surrogate_enabled            bool DEFAULT false NOT NULL,
  tisb_rebroadcast_enabled          bool DEFAULT false NOT NULL,     -- enables rebroadcast of this aircraft’s own telemetry to TIS-B

  -- Ownership flag (v1.5: replaces ghost extraction; see §⑧)
  ownership_flag_enabled            bool DEFAULT false NOT NULL,

  -- Live state (Custodian writes these from GCS plugin telemetry)
  position_lat                      float8 NULL,
  position_lon                      float8 NULL,
  position_alt                      float8 NULL,
  flight_mode                       text NULL,
  armed                             bool NULL,
  battery_remaining_pct             int4 NULL,
  link_rssi_dbm                     int4 NULL,
  adapter_connected                 bool DEFAULT false NOT NULL,
  last_telemetry_at                 timestamptz NULL,

  -- Cross-references
  keycloak_client_id                text NULL,               -- drone-as-user reference
  aadms_id                          text NULL,               -- cross-tenant identity reference

  -- Timestamps
  created_at                        timestamptz DEFAULT now() NOT NULL,
  updated_at                        timestamptz DEFAULT now() NOT NULL,
  retired_at                        timestamptz NULL,

  CONSTRAINT drones_pkey PRIMARY KEY (tenant_id, serial_number),
  CONSTRAINT drones_dlb_guid_fk FOREIGN KEY (dlb_guid) REFERENCES drones.dlb_drones(guid),
  CONSTRAINT drones_dlb_guid_unique UNIQUE (dlb_guid)
);

CREATE INDEX idx_drones_serial   ON drones.drones USING btree (serial_number);

Schema: dTwin View (drones.v_dtwin)

Read-only view that joins drones.drones with drones.dlb_drones on the dlb_guid foreign key. This is the authoritative dTwin data record — the single consistent view consumers should use when they need both RTM state and DLB identity together. The Custodian APIs serve responses that reflect this aggregated record.

-- drones.v_dtwin · /tenant/rtm-app-db/schema/v_dtwin.sql
-- dTwin view: joins drones.drones (RTM state) with drones.dlb_drones (DLB identity).
-- Use this view for any consumer that needs the full drone record.
CREATE OR REPLACE VIEW drones.v_dtwin AS
SELECT
  -- Core identity
  d.tenant_id,
  d.serial_number,
  d.dlb_guid,

  -- DLB identity (from dlb_drones; renamed for clarity)
  dlb.name                          AS drone_name,
  dlb.brand,
  dlb.model,
  dlb.drone_type,
  dlb.status,
  dlb.color,
  dlb.identification_number         AS "TC_Registration",   -- TC / regulatory registration
  dlb.inventory_number              AS "Callsign",           -- operator-assigned ADS-B callsign
  dlb.hardware_version,
  dlb.firmware_version,
  dlb.max_horizontal_speed,
  dlb.max_vertical_speed,
  dlb.max_flight_time,
  dlb.payload_capacity,
  dlb.weight,
  dlb.propulsion_type,

  -- Custodian configuration (RTM-managed)
  d.adapter_type,
  d.adapter_config,
  d.publish_rate_hz,

  -- OI defaults & FLYplan automation
  d.oi_automation_enabled,
  d.horizontal_speed_ms,
  d.vertical_speed_ms,
  d.flight_volume_m,
  d.contingency_vol_m,
  d.oi_automation_square_m,
  d.oi_automation_radius_m,
  d.oi_automation_amend_min_trigger_m,
  d.oi_automation_amend_max_alt_agl_m,
  d.oi_automation_amend_enabled,

  -- ADS-B provisioning
  d.adsb_in_enabled,
  d.adsb_out_enabled,
  d.adsb_surrogate_enabled,
  d.tisb_rebroadcast_enabled,
  d.ownership_flag_enabled,

  -- Live state
  d.position_lat,
  d.position_lon,
  d.position_alt,
  d.flight_mode,
  d.armed,
  d.battery_remaining_pct,
  d.link_rssi_dbm,
  d.adapter_connected,
  d.last_telemetry_at,

  -- Cross-references & timestamps
  d.keycloak_client_id,
  d.aadms_id,
  d.created_at,
  d.updated_at,
  d.retired_at

FROM drones.drones d
JOIN drones.dlb_drones dlb ON dlb.guid = d.dlb_guid;

Schema: AADMS Materialized View (aadms.drones)

Cross-tenant drone lookup table used by the ADS-B routing pipeline. In the current architecture this is a materialized view that aggregates drones.drones (joined to dlb_drones for callsign) from every tenant schema into a single flat surface. ADS-B records arrive carrying only callsign; AADMS resolves callsign → (tenant_id, serial_number) so the record can be routed to the correct tenant pipeline. Refreshed after each Import sync run.

-- aadms.drones · cross-tenant drone lookup
-- Materialized view aggregating all tenant drones.drones rows (joined to dlb_drones for callsign).
-- Refreshed after every Import sync. Used by ADS-B routing to resolve callsign → (tenant, serial).
CREATE SCHEMA IF NOT EXISTS aadms;

CREATE MATERIALIZED VIEW aadms.drones AS
  -- One UNION ALL block per tenant schema; extend as tenants are added.
  SELECT
    d.tenant_id,
    d.serial_number,
    d.dlb_guid                       AS guid,
    dlb.inventory_number             AS callsign,
    d.aadms_id                       AS id
  FROM tenant_airmarket.drones.drones d
  JOIN tenant_airmarket.drones.dlb_drones dlb ON dlb.guid = d.dlb_guid
  WHERE d.retired_at IS NULL

  UNION ALL

  SELECT
    d.tenant_id,
    d.serial_number,
    d.dlb_guid                       AS guid,
    dlb.inventory_number             AS callsign,
    d.aadms_id                       AS id
  FROM tenant_sait.drones.drones d
  JOIN tenant_sait.drones.dlb_drones dlb ON dlb.guid = d.dlb_guid
  WHERE d.retired_at IS NULL
  -- ... repeat for each tenant ...
;

CREATE UNIQUE INDEX idx_aadms_drones_callsign ON aadms.drones (callsign);
CREATE INDEX        idx_aadms_drones_serial   ON aadms.drones (serial_number);

How drones.dlb_drones and drones.drones work together

drones.dlb_drones and drones.drones are not alternatives — they are two complementary layers of the same pipeline, each with a distinct owner and purpose. drones.dlb_drones is the primary store for all raw DLB API data, written by the Import process and never touched by RTM. drones.drones holds only RTM state — configuration, live telemetry, and the dlb_guid foreign key that links it to dlb_drones. DLB identity data is never duplicated into drones.drones; consumers that need the full picture use the v_dtwin view.

Three distinct processes write to these tables at different times. Each process owns specific columns and must not write to columns owned by another. Breaking that boundary — for example, the Import process overwriting operator OI configuration, or the Custodian writing into dlb_drones — corrupts the data contract.

What the Import process writes from dlb_drones into drones.drones

The three field categories

The dTwin: what it actually is

The dTwin is the conceptual digital twin of one aircraft — the canonical answer to “what does FLYsafe.live believe is true about this drone right now?” It is the v_dtwin record for that drone: the join of drones.drones (RTM configuration and live state) with drones.dlb_drones (DLB identity). Consumers don’t need to know which table backs which field; they call the API and get a coherent record sourced from the view.

{
  "identity": {
    "serial_number":   "1581F5BBB1F2A",
    "tc_registration": "C-FAIRTL69",
    "callsign":        "AIRTL69",
    "tenant":          "airmarket",
    "adapter_type":    "mavlink"
  },
  "position":    { "lat": 53.5461, "lon": -113.4938, "alt_msl_m": 720.4 },
  "flight_mode": "AUTO",
  "armed":       true,
  "battery":     { "remaining_pct": 68 },
  "adsb": {
    "in_enabled": true,
    "out_enabled": true,
    "surrogate_enabled": false,
    "ownership_flagged": true           // see §⑨
  },
  "oi": {
    "automation_enabled": true,
    "default_distance_m": 300
  },
  "adapter_health": {
    "connected": true,
    "last_publish_ago_ms": 247
  },
  "timestamps": {
    "updated_at": "2026-06-16T18:42:18.523Z",
    "source_ts":  "2026-06-16T18:42:18.491Z"
  }
}

↑ Returned by GET /drones/{serial}. The Custodian's REST API serves this from the tenant.drones row + latest telemetry. There is no longer a canonical “dTwin payload schema” separate from the API response — the response is the schema.

⑤ Aircraft Custodian APIs

This is the catalog of API operations the Aircraft Custodian exposes. The same APIs are consumed by:

• The frontend (FSL RTM Map, JC) — for operator configuration changes and live state display.
• The Custodian itself — for writing telemetry-derived state back to tenant.drones.
• The MCP server — wrapping a curated subset as AI-callable tools so Aircraft AI, OCC AI, and Compliance AI agents can read and (where permission-scoped) write the same state.

All endpoints are tenant-scoped (the tenant is resolved from the JWT). The base path is /api/v1. Verbs use REST conventions: GET reads, POST creates/triggers, PUT updates, DELETE removes. Where a notification stream is useful, a WebSocket endpoint is offered as a parallel option to polling.

API surface — by category

OI Configuration — New Required Fields

Three new OI geometry parameters have been added to the drone configuration. These are stored in drones.drones and exposed through the OI Automation API endpoints.

MCP exposure

The MCP server wraps a curated subset of the above as AI-callable tools. The principle is read freely, write narrowly: agents can read drone state, OI status, ownership state, identity, and health without restriction; writes are scoped to operationally-safe toggles only, and require explicit per-tenant agent permissions.

Operations not on this list (retire, identity registration, mission binding writes, adapter-config changes, retire/restore) are deliberately not exposed via MCP in v1.6. They can be added incrementally as the agent permission model matures.

⑥ Identity Model — Four-Tier Layout

FLYsafe.live carries a drone’s identity across four systems. Each tier has a distinct purpose; mixing them up breaks the binding pipeline.

The four identifiers a drone carries

Serial number is the only one used as a binding key across the system. Callsign is set per-mission and used only for ADS-B inbound resolution via AADMS. ICAO hex is dynamic per session (uAvionix-aligned ADDRt) and is never bound to. TC registration is regulatory display.

⑦ FLYplan Workflow — What the OI Automation APIs Drive

The FLYplan process is the automated creation and maintenance of Operational Intents (OIs) for live flights. The Custodian APIs (§⑤A) are the surface that operators and AI agents use to turn this on, set its parameters, and observe its output.

⑧ Surveillance & Ownership Tagging

Flight_Live is the surveillance microservice that observes live_ads, live_community, and live_vision streams. In v1.6 it consults each drone’s ownership_flag_enabled (read from the Custodian API) to tag incoming records as own-aircraft or external.

Per-stream tagging algorithms and the full Flight_Live spec live in the 859ze-4217 wiki subpage. The reframed v1.6 contract is: Flight_Live emits a unified surveillance_traffic stream where every record carries ownership_flagged: bool and owner_serial if matched. Downstream consumers decide what to do with the flag.

⑨ Lifecycle & Operational Model

⑩ Open Questions & Next Steps

Tracked across the wiki subpages under TECH-002/FSL RTTP. Highlights for v1.6:

• API authentication design — one Keycloak realm per tenant; plugin auth via operator session, Custodian auth via service account, MCP agents via per-agent SA. Confirm scope mapping.
• Telemetry POST rate & payload schema — what frequency does the Custodian accept from the plugin? What is the canonical body schema for /drones/{serial}/telemetry? (Maykon + Tim)
• Mission Planner Plugin distribution — signed plugin published to Mission Planner’s plugin loader, or sideload-only for v1? (Tim)
• Chrome GCS Plugin store listing — published to Chrome Web Store, or distributed as enterprise extension? (Maykon)
• Plugin auto-update strategy — how do we ship plugin updates to operators in the field?
• InfluxDB schema for live state history — what columns/tags, what retention policies? (Brayden)
• WebSocket watch endpoint vs polling — do we ship WS endpoints in v1.6, or rely on polling for the first cut?
• Audit trail — transition from shared app_user to per-identity DB roles for human-driven writes; trace each updated_at back to its JWT.
• FLYplan post-flight review UX — what does the operator see when they review the OI history? Owner: JC + ops.
• MCP tool surface area for v1.6 — the list in §⑤ is a starting point; needs review against the agent permission model.
• Sprint allocation — Mission Planner Plugin (Tim) · Chrome GCS Plugin (Maykon) · Custodian server & APIs (Maykon) · drones schema + import (Brayden + Steve Smith) · deployment automation (Raman) · RTM Map UI for new APIs (JC).

📝 Changelog — v1.6 (Jun 16, 2026)