Key Concepts

Let's understand CitadelMesh's core concepts in 5 minutes.

The Problem: Buildings Can't Think

Modern commercial buildings have lots of smart systems:

• 🚪 Access control (badge readers, door locks)
• 📹 Video surveillance (cameras, analytics)
• ❄️ HVAC (heating, cooling, air quality)
• 💡 Lighting and energy management

The Problem? These systems don't talk to each other or make intelligent decisions:

❌ Fire alarm goes off
   → HVAC keeps running (spreads smoke!)
   → Doors stay locked (blocks evacuation!)
   → No coordination between systems

❌ Security breach detected
   → HVAC wastes energy cooling locked-down areas
   → Energy system unaware of security state
   → Manual intervention required

❌ Energy demand response event
   → Reduces power to security cameras
   → Security effectiveness degraded
   → Uncoordinated decisions

The Solution: Multi-Agent Intelligence

CitadelMesh uses AI agents to give buildings intelligence:

✅ Fire alarm goes off
   → Security Agent: Unlock all exits
   → Energy Agent: HVAC smoke evacuation mode
   → Orchestrator: Coordinate emergency response
   → Result: Safe evacuation in 2 seconds

✅ Security breach detected
   → Security Agent: Lock perimeter, activate cameras
   → Energy Agent: Reduce non-essential HVAC
   → Orchestrator: Security takes priority
   → Result: Secure response + energy efficiency

✅ Energy demand response
   → Energy Agent: Reduce 50 kW consumption
   → Security Agent: Maintain camera power
   → Orchestrator: Check conflicts
   → Result: Revenue earned + security maintained

Core Concept 1: AI Agents

What is an agent?

An agent is a software program that:

1. Perceives its environment (monitors events)
2. Reasons about what to do (threat analysis, optimization)
3. Acts to achieve goals (lock doors, adjust HVAC)
4. Learns from results (improves over time)

CitadelMesh has three main agents:

🛡️ Security Agent

• Goal: Protect people and property
• Monitors: Cameras, door sensors, access logs
• Reasons: Threat detection, pattern analysis
• Acts: Lock/unlock doors, camera control, alerts
• Example: "Unauthorized person detected → lock perimeter → alert security"

⚡ Energy Agent

• Goal: Minimize energy costs while maintaining comfort
• Monitors: Power meters, weather, occupancy, rates
• Reasons: Mathematical optimization (scipy)
• Acts: HVAC setpoints, demand response participation
• Example: "Peak rate period → increase temp 4°F → save $15/hour"

🎯 Building Orchestrator

• Goal: Coordinate agents, resolve conflicts
• Monitors: All agent actions and system state
• Reasons: Priority hierarchy (Safety > Security > Comfort > Cost)
• Acts: Conflict resolution, resource allocation, escalation
• Example: "Security needs HVAC + Energy wants to reduce → Security wins"

Core Concept 2: Zero-Trust Safety

The Challenge: How do we ensure agents don't do unsafe things?

CitadelMesh's Answer: Policy-Based Safety with Open Policy Agent (OPA)

# Every agent action is validated by policies

Agent: "I want to lock door-server-room"
↓
OPA Policy Check:
  - Is this agent authorized?
  - Is the door lockable?
  - Are there people inside?
  - Is this an emergency exit?
  - Does this violate safety rules?
↓
Result: ✅ Allow or ❌ Deny

Key Safety Rules:

• ❌ Can't lock emergency exits during occupancy
• ❌ Can't set HVAC outside safe temperature bounds (60°F - 85°F)
• ❌ Can't exceed agent rate limits (prevent runaway behavior)
• ❌ Can't bypass safety policies (no backdoors)
• ✅ All actions logged for audit trail

Fail-Safe Default: If policy check fails, deny the action.

Core Concept 3: Vendor Integration

Buildings use equipment from many vendors:

• Schneider Electric (EcoStruxure Building Operation)
• Avigilon (Video Analytics)
• Honeywell, Johnson Controls, Siemens, etc.

CitadelMesh uses MCP (Model Context Protocol) adapters to integrate any vendor:

Agent (wants to lock door)
    ↓
MCP Adapter (translates to Schneider API)
    ↓
Schneider EcoStruxure (executes command)

Benefits:

• ✅ Vendor-neutral (not locked into one brand)
• ✅ Standardized interface (agents don't care about vendor details)
• ✅ Easy to add new vendors (just write an MCP adapter)

Core Concept 4: Edge-First Architecture

Where does CitadelMesh run?

At the building edge (on-premises), not in the cloud:

🏢 Building Edge:
   - CitadelMesh platform (K3s cluster)
   - All agents running locally
   - NATS event bus
   - PostgreSQL database
   - OPA policy engine

☁️ Cloud (Optional):
   - Configuration sync
   - Monitoring dashboards
   - Analytics and reporting
   - Multi-site coordination

Why Edge-First?

• ⚡ Low Latency: Security responses in less than 200ms
• 🔒 Privacy: Building data stays on-premises
• 💪 Autonomy: Works offline (no internet dependency)
• 📊 Compliance: Data sovereignty requirements

Putting It All Together

Here's a complete example:

Scenario: After-Hours Intrusion

11:30 PM: Motion detected in office (should be empty)

1. 📹 Avigilon Camera
   → Detects person
   → Sends CloudEvent to NATS

2. 🛡️ Security Agent
   → Receives motion event
   → Analyzes: "After-hours + person = intrusion"
   → Decides: Lock doors, alert security
   → Checks OPA policy: ✅ Allowed
   → Executes via MCP

3. ⚡ Energy Agent
   → Receives coordination event
   → Decides: Restore lighting in affected zones
   → Maintains energy savings in other areas
   → Checks OPA policy: ✅ Allowed
   → Executes via MCP

4. 🎯 Orchestrator
   → Coordinates Security + Energy
   → Resolves conflicts (Security takes priority)
   → Monitors execution
   → Escalates if needed

5. 📊 Result
   → Doors locked: 2 seconds
   → Security alerted: 3 seconds
   → Lighting restored: 4 seconds
   → Energy savings maintained elsewhere
   → All actions logged and auditable

Key Takeaways

1. Agents = Specialized Intelligence

   • Security, Energy, and Orchestration agents work together

2. Safety = Policy Enforcement

   • Every action validated, fail-safe defaults, complete audit trail

3. Integration = MCP Adapters

   • Vendor-neutral, standardized, extensible

4. Architecture = Edge-First

   • Low latency, privacy, autonomy, compliance

---

Next: See it in action! → Quick Tour