🚁 FLYsafe.live - v1 - 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.

1. 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 (§3), 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.

2. 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.

3. 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:

3.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

3.6 Data Source Monitoring — The Vigilance Obligation

Every Custodian is responsible for knowing whether data is actually arriving from the aircraft, and at what rate and latency. A silent source is worse than a failed source, because a silent source looks the same as a healthy one until an operator notices the position hasn’t moved. The Custodian’s Streaming obligation (§2) is discharged by continuously monitoring the source and surfacing its health through the state that lives in tenant.drones.

Status transitions

4. 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,     -- pilot-granted authority; see §5A (v1.10)
  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 (FV) / Contingency Volume (CV) buffers (v1.8; supersedes the v1.6–v1.7 scalar
  -- flight_volume_m / contingency_vol_m fields. Horizontal only as of v1.12 — vertical separation
  -- from other traffic is handled by the NMAC/SWC crewed/uncrewed minima below, not by FV/CV.)
  fv_buffer_m                       float8 DEFAULT 56.0 NOT NULL,    -- horizontal buffer around flight path
  cv_buffer_m                       float8 DEFAULT 150.0 NOT NULL,   -- additional horizontal buffer past FV edge

  -- 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,

  -- Flight monitoring (v1.10) — radius within which a mission waypoint is considered reached.
  -- Respected by Flink flight-monitoring jobs when advancing current_waypoint_index.
  waypoint_buffer_m                 float8 DEFAULT 50.0 NOT NULL,    -- valid 5–500

  -- Default pilot binding (v1.7) — pre-filled pilot when a mission is created without explicit selection
  default_pilot_name                text NULL,
  default_pilot_fs_guid             text NULL,               -- FLYsafe.software pilot GUID

  -- Separation defaults (v1.7; split into crewed/uncrewed × horizontal/vertical in v1.12) —
  -- per-drone conflict-evaluation minima, metres. Crewed = manned traffic; uncrewed = other drones.
  nmac_h_crewed_m                   float8 DEFAULT 150.0  NOT NULL,  -- NMAC horizontal, crewed traffic
  nmac_v_crewed_m                   float8 DEFAULT 30.0   NOT NULL,  -- NMAC vertical, crewed traffic
  nmac_h_uncrewed_m                 float8 DEFAULT 15.0   NOT NULL,  -- NMAC horizontal, uncrewed traffic
  nmac_v_uncrewed_m                 float8 DEFAULT 8.0    NOT NULL,  -- NMAC vertical, uncrewed traffic
  swc_h_crewed_m                    float8 DEFAULT 1500.0 NOT NULL,  -- SWC horizontal, crewed traffic
  swc_v_crewed_m                    float8 DEFAULT 150.0  NOT NULL,  -- SWC vertical, crewed traffic
  swc_h_uncrewed_m                  float8 DEFAULT 150.0  NOT NULL,  -- SWC horizontal, uncrewed traffic
  swc_v_uncrewed_m                  float8 DEFAULT 30.0   NOT NULL,  -- SWC vertical, uncrewed traffic
  eval_distance_m                   float8 DEFAULT 1852.0 NOT NULL,  -- Evaluation ring (~1 NM)

  -- 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

  -- Conspicuity / ADS-B detail (v1.13) — provisioning detail behind the flags above.
  -- ec_callsign and ec_tc_reg are NOT columns here: they are dlb_drones.inventory_number
  -- and dlb_drones.identification_number respectively, already exposed as Callsign /
  -- TC_Registration in v_dtwin. The RTM Map's "ec_*" fields are just local aliases for those.
  ec_adsb_hex                       text NULL,                       -- static ADS-B ICAO hex; set when adsb_hex_mode = 'static'
  adsb_out_device                   text NULL,                       -- transponder model, e.g. Ping978ec | Ping2020i | SkyEcho 2 | TISB | other
  adsb_hex_mode                     text DEFAULT 'dynamic'::text NOT NULL,   -- dynamic (ADDRt) | static (user-entered, see ec_adsb_hex)
  surveillance_mode                 text NULL,                       -- descriptive surveillance method, e.g. "MLAT + ADS-B", "ADS-B + Vision"
  daa_enabled                       bool DEFAULT false NOT NULL,     -- Detect-and-Avoid active for this drone
  broadcast_binding                 text NULL,                       -- e.g. Bound | Unbound — binding status between this drone and its broadcast identity
  networkid_streaming_enabled       bool DEFAULT false NOT NULL,     -- gates NetworkID into RTM viz + DAA; independent of tisb_rebroadcast_enabled

  -- Observed ADS-B state (read-only, v1.13) — from surveillance feeds, not the provisioning intent above
  adsb_observed_broadcasting            bool NULL,
  adsb_observed_last_icao_hex           text NULL,
  adsb_observed_last_seen_by_cifib_at   timestamptz NULL,             -- last seen by the CIFIB upstream gating pipeline

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

  -- Data source monitoring (v1.7) — the Custodian’s vigilance obligation; see §3.6
  data_source_mechanism             text NULL,               -- mp_plugin | chrome_fh2 | dji_cloud | adsb | multi
  data_source_rate_hz               float8 NULL,
  data_source_latency_ms_p50        float8 NULL,
  data_source_latency_ms_p95        float8 NULL,
  data_source_status                text NULL,               -- HEALTHY | DEGRADED | STALE | DISCONNECTED
  data_source_max_latency_ms        int4 DEFAULT 2000 NOT NULL,      -- expected envelope
  data_source_last_seen_at          timestamptz NULL,

  -- Current flight (v1.9) — the mission this drone is executing right now.
  -- Populated by FLYsafe.software on mission publish; progress fields updated by the Custodian from telemetry.
  current_mission_id                text NULL,
  current_flight_state              text NULL,               -- PLANNED | ACTIVE | COMPLETED | ABORTED
  current_flight_window_start       timestamptz NULL,
  current_flight_window_end         timestamptz NULL,
  current_waypoint_index            int4 NULL,
  current_waypoint_total            int4 NULL,
  current_progress_pct              int4 NULL,

  -- Current OI (v1.9) — the currently active Operational Intent for this drone.
  -- Written by the Flink OI Automation job on every generation/regeneration.
  current_oi_id                     text NULL,
  current_oi_state                  text NULL,               -- DRAFT | SUBMITTED | ACCEPTED | ACTIVE | COMPLETED | REJECTED
  current_oi_source                 text NULL,               -- AUTOMATED | MANUAL | MISSION_PUBLISH
  current_oi_window_start           timestamptz NULL,
  current_oi_window_end             timestamptz NULL,
  oi_last_regenerated_at            timestamptz NULL,
  oi_next_regeneration_at           timestamptz 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
  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.fv_buffer_m,
  d.cv_buffer_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,
  d.waypoint_buffer_m,

  -- Pilot & separation defaults (v1.7)
  d.default_pilot_name,
  d.default_pilot_fs_guid,
  d.nmac_h_crewed_m,
  d.nmac_v_crewed_m,
  d.nmac_h_uncrewed_m,
  d.nmac_v_uncrewed_m,
  d.swc_h_crewed_m,
  d.swc_v_crewed_m,
  d.swc_h_uncrewed_m,
  d.swc_v_uncrewed_m,
  d.eval_distance_m,

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

  -- Conspicuity / ADS-B detail (v1.13)
  d.ec_adsb_hex,
  d.adsb_out_device,
  d.adsb_hex_mode,
  d.surveillance_mode,
  d.daa_enabled,
  d.broadcast_binding,
  d.networkid_streaming_enabled,

  -- Observed ADS-B state (v1.13)
  d.adsb_observed_broadcasting,
  d.adsb_observed_last_icao_hex,
  d.adsb_observed_last_seen_by_cifib_at,

  d.ownership_flag_enabled,

  -- Data source monitoring (v1.7) — see §3.6
  d.data_source_mechanism,
  d.data_source_rate_hz,
  d.data_source_latency_ms_p50,
  d.data_source_latency_ms_p95,
  d.data_source_status,
  d.data_source_max_latency_ms,
  d.data_source_last_seen_at,

  -- Current flight & current OI (v1.9)
  d.current_mission_id,
  d.current_flight_state,
  d.current_flight_window_start,
  d.current_flight_window_end,
  d.current_waypoint_index,
  d.current_waypoint_total,
  d.current_progress_pct,
  d.current_oi_id,
  d.current_oi_state,
  d.current_oi_source,
  d.current_oi_window_start,
  d.current_oi_window_end,
  d.oi_last_regenerated_at,
  d.oi_next_regeneration_at,

  -- 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.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);

Where OI geometry is actually stored (v1.13)

fv_buffer_m/cv_buffer_m on drones.drones are configuration — a single horizontal buffer distance used to compute a volume. They are not the volume itself. Every time the Flink OI Automation job generates or regenerates an OI, it computes three distinct geometries (Flight Volume, Contingency Volume, Submitted Volume) from those buffers plus the predicted trajectory.

Schema: DAA Rules Store (drones.daa_rules)

(v1.13) One row per Detect-and-Avoid rule per drone — the ordered rule set the mockup's Conspicuity/DAA panel edits as daa_rules[]. Rules are evaluated in sort_order; each can be individually enabled/disabled without deleting it.

-- drones.daa_rules · one row per DAA rule per drone
-- Read/written by the Custodian API's DAA endpoints; evaluated by the DAA service at runtime.
CREATE TABLE drones.daa_rules (
  tenant_id             text NOT NULL,
  serial_number         text NOT NULL,
  rule_id                text NOT NULL,                             -- e.g. R1, R2, R3

  condition_text        text NOT NULL,                              -- human-readable trigger condition, e.g. "Target within NMAC radius"
  action_text            text NOT NULL,                              -- action taken when triggered, e.g. "RTH — Immediate"
  priority                text NOT NULL,                              -- critical | high | medium | low
  enabled                 bool NOT NULL DEFAULT true,
  sort_order             int4 NOT NULL DEFAULT 0,                    -- evaluation / display order

  PRIMARY KEY (tenant_id, serial_number, rule_id),
  FOREIGN KEY (tenant_id, serial_number) REFERENCES drones.drones(tenant_id, 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 §9
  },
  "pilot": {                                    // v1.7 — default pilot binding
    "default_name":    "Jane Chen",
    "default_fs_guid": "pilot-8f3a2e19-4c1a-4e6b-9c17-2b9e5d3f7a0c"
  },
  "oi": {
    "automation_enabled": true,      // pilot-granted; see §5A (v1.10)
    "default_distance_m": 300,
    "waypoint_buffer_m":  50.0      // v1.10 — radius: drone "reached" waypoint when within
  },
  "volumes": {                                  // v1.8; horizontal-only as of v1.12 — see current_oi.geometry_ref for the actual computed polygons
    "flight_volume":      { "buffer_m": 56.0 },
    "contingency_volume": { "buffer_m": 150.0 }
  },
  "separation": {                               // v1.7; split into crewed/uncrewed × horizontal/vertical in v1.12
    "nmac_crewed_m":   { "h": 150.0,  "v": 30.0 },
    "nmac_uncrewed_m": { "h": 15.0,   "v": 8.0 },
    "swc_crewed_m":    { "h": 1500.0, "v": 150.0 },
    "swc_uncrewed_m":  { "h": 150.0,  "v": 30.0 },
    "eval_distance_m": 1852.0
  },
  "data_source": {                              // v1.7 — see §3.6
    "mechanism":      "mp_plugin",
    "rate_hz":        4.0,
    "latency_ms_p50": 180,
    "latency_ms_p95": 420,
    "max_latency_ms": 2000,
    "status":         "HEALTHY",
    "last_seen_at":   "2026-06-16T18:42:18.315Z"
  },
  "current_flight": {                           // v1.9 — the mission this drone is executing right now
    "mission_id": "mission-airmarket-2026061618420",
    "state":      "ACTIVE",             // PLANNED | ACTIVE | COMPLETED | ABORTED
    "window": { "start": "2026-06-16T18:30:00Z", "end": "2026-06-16T19:15:00Z" },
    "waypoints": { "current_index": 5, "total": 12 },
    "progress_pct": 42
  },
  "current_oi": {                               // v1.9 — the active Operational Intent for this drone
    "oi_id":  "oi-airmarket-2026061618421",
    "state":  "ACTIVE",               // DRAFT | SUBMITTED | ACCEPTED | ACTIVE | COMPLETED | REJECTED
    "source": "AUTOMATED",            // AUTOMATED | MANUAL | MISSION_PUBLISH
    "last_regenerated_at": "2026-06-16T18:41:15Z",
    "next_regeneration_at": "2026-06-16T18:41:45Z",
    "geometry_ref": {                           // v1.11 — three distinct stored geometries, not one
      "flight_volume":       "/api/v1/drones/1581F5BBB1F2A/oi/current/flight-volume",
      "contingency_volume":  "/api/v1/drones/1581F5BBB1F2A/oi/current/contingency-volume",
      "submitted_volume":    "/api/v1/drones/1581F5BBB1F2A/oi/current"          // FV + CV combined; what was sent to FLYrtm DSS
    }
  },
  "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. Cheaper subset endpoints (/state, /current-flight, /current-oi, /data-source) exist for consumers that don’t want the full payload every time.

5. 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. They can be added incrementally as the agent permission model matures.

6. 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.

7. 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 (§5A) are the surface that operators and AI agents use to turn this on, set its parameters, and observe its output.

8. 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.

9. Lifecycle & Operational Model

10. Open Questions & Next Steps

Tracked across the wiki subpages under TECH-002/FSL RTTP.

• 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)
• 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 — the list in §5 is a starting point; needs review against the agent permission model.
• DM-DI — ADS-B field split. v1 uses a single surrogate boolean for ADS-B provisioning; splitting into distinct in/out/runtime fields is anticipated but not yet scheduled.
• Sprint allocation — Mission Planner Plugin (Tim) · Chrome GCS Plugin (Maykon) · Cloud Broker (Maykon) · Custodian server & APIs (Maykon) · drones schema + import (Brayden + Steve Smith) · deployment automation (Raman) · RTM Map UI for new APIs (JC).

Recently Resolved

📝 Changelog — v1.13 (Aug 20, 2026)

📝 Changelog — v1.12 (Aug 20, 2026)

📝 Changelog — v1.11 (Jun 22, 2026)

📝 Changelog — v1.10 (Jun 20, 2026)

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

📐 Reference — Polygon Generation API Requirements (Owner: JC)

§4 established that three geometries — Flight Volume, Contingency Volume, and the Submitted Volume — are stored in flights_binding (v1.13) and exposed via the §5A endpoints. This section specifies the API that actually computes those three polygons from a predicted trajectory and the drone’s FV/CV buffer defaults. It does not yet exist; JC is building it. Everything below is the requirements contract for that work — not a description of a shipped API.

Request contract

{
  "tenant_id": "airmarket",
  "serial_number": "1581F5BBB1F2A",
  "trajectory": [                              // predicted path, ordered, ≥ 2 points
    { "lat": 53.5461, "lon": -113.4938, "alt_msl_m": 720.4, "t": "2026-06-16T18:42:00Z" },
    { "lat": 53.5480, "lon": -113.4901, "alt_msl_m": 725.1, "t": "2026-06-16T18:43:30Z" }
    // ...
  ],
  "fv_buffer_m": 56.0,                          // horizontal only (v1.12)
  "cv_buffer_m": 150.0
}

Response contract

{
  "flight_volume":      { "type": "Polygon", "coordinates": [ /* GeoJSON PolygonZ */ ] },
  "contingency_volume": { "type": "Polygon", "coordinates": [ /* GeoJSON PolygonZ */ ] },
  "submitted_volume":   { "type": "Polygon", "coordinates": [ /* GeoJSON PolygonZ — see open question below */ ] },
  "computed_at": "2026-06-16T18:42:18.600Z"
}

Functional requirements