Skip to main content

Architecture Overview

CitadelMesh delivers an autonomous “digital nervous system” for buildings by combining edge-first infrastructure, safety-bound AI agents, and an open integration fabric. This page summarizes how the pieces fit together and points you to the deeper dives that justify each design decision.

Differentiation at a Glance​

Multi-Agent Autonomy​

Specialized agents collaborate through LangGraph state machines and Orleans microservices, so security, energy, and orchestration domains evolve independently while sharing a replayable decision history. See Agent Topology for the full mesh and implementation patterns.

Edge-First Zero Trust​

Every building runs a self-sufficient k3s stack with SPIFFE/SPIRE identities enforcing mutual TLS even when disconnected from the cloud. Offline resilience, WASI-sandboxed adapters, and policy-bound command paths are detailed in Edge Architecture and Identity Foundation.

Defense-in-Depth Safing​

Actions traverse static constraints, OPA/Rego evaluation, shadow rehearsals, human approvals, and circuit breakers—not the single approval gates common in legacy BMS platforms. Explore the layered flow in Safety Guardrails.

Unified Knowledge Graph​

A federated ontology reconciles telemetry, assets, people, and policies into a single queryable twin, enabling contextual automation, analytics, and incident investigations. Architecture specifics live in Digital Twin.

Open Integration Fabric​

CloudEvents, protobuf/gRPC contracts, and Model Context Protocol (MCP) adapters expose vendor systems to any agent, IDE, or automation flow. MCP Adapter Architecture explains how we keep tooling agnostic while preserving auditability.

Built-In Observability & Compliance​

End-to-end OpenTelemetry metrics, CloudEvents audit trails, and GitOps-managed policy artifacts make readiness measurable and attestable. The platform’s instrumentation story is covered in Observability and reinforced throughout the safety documentation.

Edge-to-Cloud Topology​

Gateway Modernization Highlights​

CapabilityStatusNotes
Security Incidentsâś… Live/security/incidents, /security/incidents/{id}, /security/incidents/{id}/acknowledgements served by ASP.NET Core gateway with SPIFFE auth, audit logs, OTEL counters
Camerasâś… Live/security/cameras, /security/cameras/{id}/stream proxy orchestrator camera services
Door Controlâś… LiveOPA-guarded lock/unlock commands routed to Schneider MCP adapter
Incidents Escalation/Ackâś… LiveOrchestrator-backed escalations + acknowledgement API
Energy Routesâś… Live/agents/energy/*, /energy/* delivered via ASP.NET Core gateway with OTEL counters and automatic legacy fallback when the orchestrator is unavailable

Metrics & Observability​

The gateway exports OpenTelemetry metrics under:

  • citadel.gateway.incidents → citadel_incident_reads, citadel_incident_escalations, citadel_incident_acknowledgements
  • citadel.gateway.energy → citadel_energy_zone_reads, citadel_energy_zone_controls, citadel_energy_demand_response_actions, citadel_energy_optimization_requests

These counters feed Grafana dashboards tracking MTTA/MTTR, energy optimization impact, and demand response readiness—aligning with knowledge graph KPIs and compliance evidence.

Alignment With Vision​

  • Unified Control Fabric: ASP.NET Core gateway + Orleans orchestrator deliver the .NET-native ingress layer.
  • Knowledge Graph Integration: Incidents/cameras data feeds the graph and dashboards through OTEL metrics.
  • Policy Guardrails: SPIFFE-authenticated gateway requests hit OPA before actuation, with audit events published via NATS.
  • Safety Simulation Lab Ready: Structured metrics and audit trails enable simulation replay and scenario scoring.
  1. Agent Topology — in-depth look at the autonomous mesh.
  2. Edge Architecture — how offline-first deployments stay safe and maintainable.
  3. Safety Guardrails — detailed defense-in-depth flow.
  4. Digital Twin — knowledge graph and ontology foundations.
  5. MCP Adapter Architecture — open integration strategy and tooling story.