Satellite Database Architecture

Satellite Database Architecture — Single-Node Citus by Default

Principle

Every KuiperDesk deployment — hub or satellite — runs CNPG with Citus extension enabled. Schema is identical everywhere. The only difference is scale: single-node vs multi-node.

Why Citus Everywhere (Even Single-Node)

1. Schema portability — create_distributed_table('endpoints', 'tenant_id') works on single-node Citus (data stays local, distribution is logical). No schema forks between hub and satellite.
2. Seamless scale-up — tenant outgrows single node → add CNPG instances → Citus redistributes shards. Zero migration, zero downtime.
3. Query compatibility — co-located joins, distributed aggregates, reference tables all work identically on 1 node or 10.
4. Test-prod parity — developers run single-node Citus locally, production runs multi-node. Same queries, same behavior.

Satellite Tiers

Database Layout Per Satellite

CNPG Cluster: kuiperdesk-db (Citus-enabled)
  │
  ├─ Database: hashsvc
  │    Owner: hashsvc
  │    Tables: hash_metadata (distributed by tenant_id)
  │    Purpose: Content-addressable block dedup metadata
  │
  ├─ Database: twinsvc
  │    Owner: twinsvc
  │    Tables: tenants, endpoints, snapshots, snapshot_disks,
  │            snapshot_volumes, cloud_actions, backup_policies,
  │            file_change_log, file_latest_state, synthetic_images,
  │            live_instances, twin_change_journals, pending_commands,
  │            agent_connections, regions, tenant_hierarchy
  │    All distributed by tenant_id (co-located)
  │    Purpose: Digital twin catalog, command channel, file index
  │
  └─ Database: enrollsvc
       Owner: enrollsvc
       Tables: enrollment_keys, agent_versions, tenant_version_pins,
               tpm_challenges, computer_groups, computer_group_members,
               update_history, global_settings, proto_compatibility
       Purpose: Agent enrollment, version management

Citus Configuration

Single-Node (Default)

-- On satellite bootstrap, all distributed table calls succeed on single-node:
CREATE EXTENSION IF NOT EXISTS citus;
CREATE EXTENSION IF NOT EXISTS pg_trgm;

-- These work on single-node — data stays local, distribution is logical
SELECT create_distributed_table('endpoints', 'tenant_id');
SELECT create_distributed_table('snapshots', 'tenant_id', colocate_with => 'endpoints');
-- ... (all tables from 001_schema.sql)

-- On a satellite, there's only ONE tenant_id, so all data is on one shard anyway.
-- Citus overhead on single-node is negligible (< 1% CPU, < 10MB RAM).

Scale-Up to Multi-Node

When a satellite needs horizontal scaling:

# 1. Increase CNPG instances (Ansible/Helm)
helm upgrade kuiperdesk-satellite ... --set cnpg.instances=5

# 2. Add Citus workers (via citus_add_node on coordinator)
SELECT citus_add_node('kuiperdesk-db-2.kuiperdesk-db.kd-db.svc', 5432);
SELECT citus_add_node('kuiperdesk-db-3.kuiperdesk-db.kd-db.svc', 5432);

# 3. Rebalance shards across new workers
SELECT rebalance_table_shards();

# Zero downtime. No schema changes. Existing queries work unchanged.

Satellite-to-Hub Data Flow

Satellite (tenant's infra)              Hub (Arivaran infra)
┌──────────────────────────┐            ┌──────────────────────────┐
│ CNPG+Citus (kuiperdesk-db)│           │ CNPG+Citus (kuiperdesk-db)│
│  hashsvc DB              │            │  hashsvc DB              │
│  twinsvc DB              │            │  twinsvc DB              │
│  enrollsvc DB            │            │  enrollsvc DB            │
│                          │            │                          │
│ SeaweedFS (blocks + DBs) │            │                          │
│                          │            │                          │
│ Agent ←→ Local Services  │            │  Dashboard (aaDash)      │
└──────────┬───────────────┘            └──────────┬───────────────┘
           │                                       │
           │ satgw tunnel (TLS 1.3 mTLS)            │
           │                                       │
           └── Metadata sync ──────────────────────┘
               - Satellite status heartbeat
               - Aggregated backup metrics
               - Billing metering data
               - Alert escalation

               NOT synced:
               - Backup blocks (stay on satellite S3)
               - File indexes (stay on satellite PG)
               - Agent credentials (stay on satellite)

Data Sovereignty

This ensures compliance with data residency requirements (GDPR, sovereign cloud, FedRAMP boundary).

Backup & Recovery

Satellite Database Backup

Each satellite's CNPG cluster is configured with:

• WAL archiving to local SeaweedFS S3 (via barman-cloud)
• Scheduled base backups daily at 03:00 local time
• PITR (Point-in-Time Recovery) to any second within retention window
• Retention: 30 days (configurable per tenant)

Disaster Recovery

If a satellite is destroyed:

1. New satellite bootstrapped (same bootstrap token flow)
2. CNPG cluster bootstrapped from S3 backup (barman-cloud recovery)
3. Agents re-enroll (enrollment keys still valid on hub)
4. Data restored from S3 (blocks are immutable, SQLite DBs intact)

If satellite S3 is also destroyed:

• Hub has no copy of the data (by design — data sovereignty)
• Tenant must restore from their own offsite backup
• Recommendation: configure S3 cross-region replication for Tier A

Compliance Mapping

Revision History