Constellation Overwatch

Open source Edge C4ISR Server Mesh for drone/robotic communication, telemetry streaming, and real-time command & control.

About

Constellation Overwatch is a distributed, event-driven C4ISR (Command, Control, Communications, and Intelligence) server mesh for managing fleets of autonomous systems including drones, robots, IoT sensors, and edge computing devices. Built on NATS JetStream for reliable, low-latency messaging with atomic operations and durable streams.

⚠️ Warning: This software is under active development. While functional, it may contain bugs and undergo breaking changes. Use caution with production deployments and ensure you have proper backups.

Features and Roadmap

• Real-time Pub/Sub Messaging for low-latency communication between edge devices and control systems
• Durable Event Streams using NATS JetStream for reliable message delivery and persistence
• Multi-Entity Fleet Support for managing drones, robots, sensors, and other autonomous systems
• RESTful API with bearer token authentication for secure HTTP access
• Embedded NATS Server providing self-contained messaging with no external dependencies
• High-Frequency Telemetry streaming with efficient handling of sensor data
• Real-time Web Dashboard powered by Server-Sent Events (SSE) and Datastar framework
• Type-Safe Templates using Templ for reactive Go-based web components
• libSQL Database with auto-initialization and schema management
• Event-Driven Architecture with workers for entities, commands, telemetry, and events

The following features are on our current roadmap:

• Enhanced SSE Integration with PatchElements and PatchSignal for KV watcher on /overwatch
• Interactive Maps using Mapbox or MapLibre web components with global KV watcher
• Video Stream Proxy for 1:n video streaming to web UI
• TLS 1.3 Encryption for enhanced NATS security
• Unified API Layer consolidating REST and SSE endpoints
• Logging Stream UI for centralized log viewing
• WebSocket Support for alternative real-time communication
• Kubernetes Deployment manifests and Helm charts
• Prometheus Metrics integration for observability
• Edge Client SDKs for Go, Python, and Rust

Architecture

API Service Diagram

graph LR
    subgraph "Client Layer"
        C1[Web Dashboard]
        C2[Mobile App]
        C3[CLI Tools]
        C4[Edge Devices]
    end
    
    subgraph "API Gateway"
        API[REST API<br/>:8080]
        AUTH[Bearer Auth<br/>Middleware]
    end
    
    subgraph "Core Services"
        OS[Organization<br/>Service]
        ES[Entity<br/>Service]
    end
    
    subgraph "Data Layer"
        DB[(libSQL/Turso DB)]
        NATS[(NATS JetStream<br/>CONSTELLATION_GLOBAL_STATE KV:entity_id)]
    end
    
    subgraph "NATS Streams"
        S1[CONSTELLATION_ENTITIES]
        S2[CONSTELLATION_EVENTS]
        S3[CONSTELLATION_TELEMETRY]
        S4[CONSTELLATION_COMMANDS]
    end
    
    C1 & C2 & C3 --> API
    C4 <--> NATS
    API --> AUTH
    AUTH --> OS & ES
    OS & ES --> DB
    ES --> NATS
    NATS --> S1 & S2 & S3 & S4
    
    style API fill:#4CAF50
    style NATS fill:#2196F3
    style DB fill:#FF9800

Data Flow Sequence Diagram

sequenceDiagram
    participant D as Drone/Robot
    participant N as NATS JetStream
    participant KV as KV Store<br/>(CONSTELLATION_GLOBAL_STATE)
    participant W as Workers<br/>(Entity/Telemetry/Event)
    participant A as API Service
    participant DB as libSQL DB
    participant UI as Web UI<br/>(SSE)

    Note over D,UI: Entity Registration Flow
    UI->>A: POST /api/v1/entities
    A->>DB: INSERT entity
    A->>N: Publish entity.created event
    A->>KV: Sync entity to KV[entity_id]
    A-->>UI: Return Entity
    N->>W: EntityWorker processes event
    W->>DB: Log entity creation
    W-->>UI: SSE update (if subscribed)

    Note over D,UI: Telemetry Publishing Flow
    D->>N: Publish to constellation.telemetry.{org_id}.{entity_id}
    N->>N: Store in CONSTELLATION_TELEMETRY stream
    N->>W: TelemetryWorker receives message
    W->>KV: Update entity state with latest telemetry
    KV-->>UI: KV watcher triggers SSE update
    UI->>UI: Datastar patches UI elements

    Note over D,UI: Real-time State Sync
    D->>N: Publish status/position update
    N->>W: EventWorker processes update
    W->>DB: Update entity record
    W->>KV: Sync to KV[entity_id]
    KV-->>UI: SSE PatchElements with new state

    Note over D,UI: Command Flow
    UI->>A: POST command
    A->>N: Publish to constellation.commands.{org_id}.{entity_id}
    N->>N: Store in CONSTELLATION_COMMANDS stream
    N->>D: CommandWorker delivers command
    D->>N: Publish command.ack
    N->>W: Process acknowledgment
    W->>KV: Update command status
    KV-->>UI: SSE notification

    Note over D,UI: Web Dashboard Live Updates
    UI->>A: GET /sse/stream (SSE connection)
    A->>N: Subscribe to constellation.>
    loop Real-time Updates
        N->>A: New message on any subject
        A->>UI: SSE PatchElements (Datastar)
        UI->>UI: Update DOM without reload
    end

Getting Started

Please see the Quick Start Guide below for detailed usage examples.

# Clone the repository
git clone https://github.com/Constellation-Overwatch/constellation-overwatch.git
cd constellation-overwatch

# Install dependencies
go mod download

# Run in development mode (recommended)
task dev

# OR run directly
go run ./cmd/microlith/main.go

# macOS
brew install go-task/tap/go-task

# Linux
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin

# Windows (using Scoop)
scoop install task

task dev  # Auto-rebuilds templ templates on changes

# Build image
task docker-build

# Run with Docker Compose
task docker-run

# Stop service
task docker-stop

Configuration

Create a .env file in the project root (copy from .env.example):

cp .env.example .env

Configuration options:

• API_BEARER_TOKEN - Bearer token for API authentication (default: constellation-dev-token)
• PORT - HTTP server port (default: 8080)
• DB_PATH - libSQL database path (default: ./db/constellation.db)
• NATS_PORT - NATS server port (default: 4222)
• NATS_DATA_DIR - NATS data directory (default: ./data/overwatch)
• WEB_UI_PASSWORD - Password for Web UI access (leave empty to disable)

Example .env file:

API_BEARER_TOKEN=constellation-dev-token
PORT=8080
DB_PATH=./db/constellation.db
NATS_PORT=4222
NATS_DATA_DIR=./data/overwatch
WEB_UI_PASSWORD=your-secure-password

Web UI Authentication

The Web UI supports optional password-based authentication. When WEB_UI_PASSWORD is set in your .env file, users must authenticate before accessing the dashboard.

To enable Web UI authentication:

# In your .env file
WEB_UI_PASSWORD=your-secure-password

When enabled:

• Accessing any protected route redirects to /login
• Sessions are stored in-memory with 24-hour expiration
• Logout is available at /logout

To disable Web UI authentication:

Leave WEB_UI_PASSWORD empty or unset. The dashboard will be accessible without login.

API Authentication

All REST API endpoints (/api/v1/*) require Bearer token authentication:

curl -H "Authorization: Bearer constellation-dev-token" \
     http://localhost:8080/api/v1/organizations

Quick Start Examples

export TOKEN="constellation-dev-token"  # or your custom token from .env

curl -s -X POST http://localhost:8080/api/v1/organizations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Fleet",
    "org_type": "civilian",
    "description": "Test drone fleet"
  }'

{
  "success": true,
  "data": {
    "org_id": "ae9c65d0-b5f3-4cec-8ffa-68ff1173e050",
    "name": "My Fleet",
    "org_type": "civilian",
    "metadata": "{}",
    "created_at": "2025-10-22T11:34:29.195678-05:00",
    "updated_at": "2025-10-22T11:34:29.195678-05:00"
  }
}

export ORG_ID='ae9c65d0-b5f3-4cec-8ffa-68ff1173e050'
curl -s -X POST "http://localhost:8080/api/v1/entities?org_id=$ORG_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Drone-001",
    "entity_type": "aircraft_multirotor",
    "description": "Primary vegetation inspection drone",
    "metadata": {
      "model": "DJI-M300",
      "serial": "ABC123456"
    }
  }'

{
  "success": true,
  "data": {
    "entity_id": "5458eec0-b0e3-4290-8db5-17936dbbfc64",
    "org_id": "ae9c65d0-b5f3-4cec-8ffa-68ff1173e050",
    "entity_type": "aircraft_multirotor",
    "status": "unknown",
    "priority": "normal",
    "is_live": false
  }
}

# Extract entity_id from response
export ENTITY_ID='5458eec0-b0e3-4290-8db5-17936dbbfc64'

# List all entities in organization
curl -s "http://localhost:8080/api/v1/entities?org_id=$ORG_ID" \
  -H "Authorization: Bearer $TOKEN" | jq

# Get specific entity details
curl -s "http://localhost:8080/api/v1/entities?org_id=$ORG_ID&entity_id=$ENTITY_ID" \
  -H "Authorization: Bearer $TOKEN" | jq

# Update entity status
curl -s -X PUT "http://localhost:8080/api/v1/entities?org_id=$ORG_ID&entity_id=$ENTITY_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "metadata": {
      "location": "lat:37.7749,lon:-122.4194",
      "battery": "85%"
    }
  }' | jq

API Endpoints

Organizations

• POST /api/v1/organizations - Create organization
• GET /api/v1/organizations - List organizations
• GET /api/v1/organizations?org_id=xxx - Get organization

Entities

• POST /api/v1/entities?org_id=xxx - Create entity
• GET /api/v1/entities?org_id=xxx - List entities
• GET /api/v1/entities?org_id=xxx&entity_id=yyy - Get entity
• PUT /api/v1/entities?org_id=xxx&entity_id=yyy - Update entity
• DELETE /api/v1/entities?org_id=xxx&entity_id=yyy - Delete entity

Health Check

• GET /health - Service health status

NATS Subjects

Entity Events

• constellation.entities.{org_id}.created
• constellation.entities.{org_id}.updated
• constellation.entities.{org_id}.deleted
• constellation.entities.{org_id}.status

Telemetry

• constellation.telemetry.{org_id}.{entity_id}

Commands

• constellation.commands.{org_id}.{entity_id}
• constellation.commands.{org_id}.broadcast

Project Structure

constellation-overwatch/
├── cmd/
│   └── microlith/              # Main application entry point
├── api/
│   ├── handlers/               # API-specific handlers (health, orgs, entities)
│   ├── middleware/             # HTTP middleware (auth, CORS, logging)
│   ├── services/               # Business logic services (entities, organizations)
│   └── router.go               # API router definition
├── db/
│   ├── service.go              # Database service with auto-initialization
│   ├── schema.sql              # libSQL database schema
│   └── constellation.db        # libSQL database (auto-created)
├── pkg/
│   ├── ontology/               # Core domain models and entity types
│   ├── shared/                 # Shared types, constants, and NATS subjects
│   └── services/
│       ├── embedded-nats/      # Embedded NATS JetStream server
│       ├── logger/             # Centralized logging service
│       ├── workers/            # Background event processors (entity, command, telemetry, event)
│       └── web/                # Web UI and SSE services
│           ├── handlers/       # Web-specific handlers (pages, datastar, overwatch)
│           ├── datastar/       # Datastar framework integration
│           ├── templates/      # Templ templates (*.templ files)
│           ├── static/         # Static assets (CSS, JS, images)
│           ├── router.go       # Web router and API mounting
│           ├── server.go       # HTTP server lifecycle
│           └── sse_handler.go  # Server-Sent Events handler
├── prd/
│   └── design/                 # Product requirements and design docs
│       ├── API.md              # API specification
│       ├── CLIENT_DESIGN.md    # Client design documentation
│       ├── CONSTELLATION_TAK_ONTOLOGY.md  # Entity ontology definitions
│       └── VENDOR_CAMERA.md    # Camera vendor specifications
├── tests/
│   └── publish-simulations/    # NATS publish simulation tests
├── bin/                        # Compiled binaries (auto-generated)
├── data/                       # NATS JetStream data directory (auto-generated)
├── logs/                       # Application logs (auto-generated)
└── nats.conf                   # NATS server configuration

Development

# Development mode (auto-rebuild templ templates)
task dev

# Generate templ templates
task templ-generate

# Watch templ files for changes
task templ-watch

# Build the binary
task build
# OR manually: go build -o bin/overwatch ./cmd/microlith

# Run the binary
task run
# OR manually: ./bin/overwatch

# Run tests
go test ./...

# Format code
go fmt ./...

# Run go vet
go vet ./...

# List all available tasks
task --list

Security

NATS_AUTH_ENABLED=true
NATS_USER=your_username
NATS_PASSWORD=your_password

task generate-certs

NATS_TLS_ENABLED=true
NATS_TLS_CERT=/path/to/server.crt
NATS_TLS_KEY=/path/to/server.key

Contributing

We welcome contributions to Constellation Overwatch! Please check out our contribution guidelines to get started.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow Go best practices and conventions
• Add tests for new features
• Update documentation as needed
• Run go fmt ./... and go vet ./... before committing
• Ensure all tests pass with go test ./...

License

This project is licensed under the MIT License.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Constellation Overwatch by you shall be licensed as MIT, without any additional terms or conditions.