Bifrost - Communications Gateway & MCP Admin Portal

Version: 1.0.0
Status: Production
Owner: Nate Walker
URLs:

• Admin UI: https://bifrost.ravenhelm.dev
• API: https://bifrost-api.ravenhelm.dev

---

Overview

Bifrost is the Rainbow Bridge connecting Norns AI agents to all communication realms. It serves as:

1. MCP Gateway - Centralized tool management and execution routing
2. Communications Hub - Slack, email, and webhook channel management
3. AIOps Platform - Alert ingestion, CMDB, discovery, and incident management
4. Admin Portal - Web UI for managing agents, tools, and integrations

---

Architecture

                    ┌────────────────────────────────────────────────────────┐
                    │                     Bifrost                             │
                    │  ┌──────────────────────────────────────────────────┐  │
                    │  │              bifrost-admin (Next.js)              │  │
                    │  │    Auth · Dashboard · CMDB · AIOps · Settings     │  │
                    │  └──────────────────────────┬───────────────────────┘  │
                    │                             │                          │
                    │  ┌──────────────────────────▼───────────────────────┐  │
                    │  │              bifrost-api (FastAPI)                │  │
                    │  │  MCP Protocol · Channels · Webhooks · Discovery  │  │
                    │  └──────────────────────────┬───────────────────────┘  │
                    └─────────────────────────────┼──────────────────────────┘
                                                  │
         ┌────────────────┬───────────────────────┼───────────────────────┬────────────────┐
         │                │                       │                       │                │
    ┌────▼────┐     ┌─────▼─────┐          ┌─────▼─────┐          ┌──────▼──────┐   ┌─────▼─────┐
    │ Norns   │     │   n8n     │          │ PostgreSQL │          │ Docker/     │   │  GitLab   │
    │ Agent   │     │ Workflows │          │  + Redis   │          │ Prometheus  │   │   API     │
    └─────────┘     └───────────┘          └───────────┘          │ + Traefik   │   └───────────┘
                                                                   └─────────────┘

---

Components

bifrost-api (FastAPI)

Core API service providing:

Endpoint Group	Purpose
/api/v1/channels	Slack/email channel management
/api/v1/tools	MCP tool definitions and execution
/api/v1/agents	Registered agent management
/api/v1/aiops/*	Alert sources, rules, incidents
/api/v1/cmdb/*	Entity discovery and recommendations
/api/v1/rbac/*	Role-based access control
/mcp/tools/*	MCP protocol endpoints
/webhooks/*	Grafana, Slack, GitLab webhooks

bifrost-admin (Next.js 16)

Admin portal with pages:

Page	Description
/	Dashboard with system overview
/agents	Registered agents, health status, permissions
/aiops	AIOps dashboard: alerts, incidents, rules, integrations
/cmdb	Infrastructure entities with discovery status
/recommendations	Monitoring recommendations catalog
/channels	Communication channel management
/tools	MCP tool definitions
/connections	API connection configurations
/discovery	Discovery sources and run history

---

AIOps Module

Alert Engine

• Sources: Grafana, Alertmanager, generic webhooks
• Rules: Condition-based routing with actions (notify, escalate, trigger workflow)
• States: firing → acknowledged → resolved
• Executions: n8n workflow orchestration

CMDB (Configuration Management Database)

Automatic discovery of infrastructure entities:

Source	Entities Discovered
Docker	Containers, images, networks
Prometheus	Scrape targets, job metadata
Traefik	Services, routers, hostnames

Current inventory:

• 52 Docker containers
• 6 Prometheus targets
• 29 Traefik services

Monitoring Recommendations

Auto-suggested alerts per entity type:

Entity Type	Recommendations
Container	High memory (>90%), restart loop detection
Database	Connection pool exhaustion, replication lag
Network Service	Uptime checks, TLS certificate expiry

GitLab Integration

Automatic incident tracking:

• Create GitLab issues for critical alerts
• Timeline entries for agent actions
• Auto-resolve with RCA summary
• Configured for: gitlab.ravenhelm.dev project #6
• Labels: incident, aiops-managed, severity::*

---

Registered Agents

Agent	Type	Status	Description
norns-agent	norns	Healthy	Primary AI assistant
voice-agent	voice_gateway	Unknown	Voice/telephony gateway
spire-agent	custom	Unknown	SPIFFE/SPIRE identity agent

---

API Examples

List Agents

curl https://bifrost-api.ravenhelm.dev/api/v1/agents

AIOps Overview

curl https://bifrost-api.ravenhelm.dev/api/v1/aiops/overview

List CMDB Entities

curl "https://bifrost-api.ravenhelm.dev/api/v1/cmdb/entities?type=container&limit=10"

Trigger Discovery

curl -X POST https://bifrost-api.ravenhelm.dev/api/v1/cmdb/discovery/trigger \
  -H "Content-Type: application/json" \
  -d '{"source_type": "docker"}'

List Recommendations

curl https://bifrost-api.ravenhelm.dev/api/v1/cmdb/recommendations

---

Configuration

Environment Variables

# Database
BIFROST_DB_HOST=postgres
BIFROST_DB_NAME=ravenmaskos
BIFROST_DB_USER=ravenhelm

# Redis
BIFROST_REDIS_HOST=redis
BIFROST_REDIS_PORT=6379

# Norns Integration
BIFROST_NORNS_URL=http://docs/AI-ML-Platform/norns-agent:8000
BIFROST_NORNS_API_KEY=xxx

# Zitadel SSO
BIFROST_ZITADEL_ISSUER=https://auth.ravenhelm.dev

# OpenFGA Authorization
BIFROST_OPENFGA_API_URL=http://openfga:8080
BIFROST_OPENFGA_STORE_ID=xxx

# Discovery (AIOps)
BIFROST_DOCKER_HOST=http://dockerproxy:2375
BIFROST_PROMETHEUS_URL=http://prometheus:9090
BIFROST_TRAEFIK_API_URL=http://traefik:8080

Docker Compose

services:
  bifrost-api:
    build: ./api
    container_name: bifrost-api
    networks:
      - ravenhelm_net
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.bifrost-api.rule=Host(`bifrost-api.ravenhelm.dev`)"
      - "traefik.http.services.bifrost-api.loadbalancer.server.port=8000"

  bifrost-admin:
    build: ./admin
    container_name: bifrost-admin
    networks:
      - ravenhelm_net
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.bifrost-admin.rule=Host(`bifrost.ravenhelm.dev`)"
      - "traefik.http.services.bifrost-admin.loadbalancer.server.port=3000"
    depends_on:
      - bifrost-api

---

Database Schema

Key tables in ravenmaskos database:

Core

• organizations - Multi-tenant org management
• tool_definitions - MCP tool registry
• tool_executions - Execution audit log
• channels - Communication channels
• registered_agents - Agent registry

AIOps

• aiops_alert_sources - Webhook endpoints
• aiops_alert_instances - Alert occurrences
• aiops_routing_rules - Alert routing
• aiops_incidents - Incident lifecycle
• aiops_workflow_executions - n8n execution tracking
• aiops_gitlab_config - GitLab integration settings

CMDB

• entity_types - Container, host, database, etc.
• entities - Infrastructure items
• entity_relationships - Dependencies
• discovery_sources - Docker, Prometheus, Traefik
• discovery_runs - Discovery audit log
• monitoring_recommendations - Alert templates
• entity_monitors - Applied recommendations

---

Deployment

# Build and deploy
cd ~/ravenhelm/services/bifrost
docker compose build
docker compose up -d

# View logs
docker logs -f bifrost-api
docker logs -f bifrost-admin

# Restart
docker compose restart bifrost-api bifrost-admin

---

Health Checks

# API health
curl https://bifrost-api.ravenhelm.dev/health

# Database connectivity
curl https://bifrost-api.ravenhelm.dev/health/db

# Redis connectivity
curl https://bifrost-api.ravenhelm.dev/health/docs/infrastructure/redis

---

Related Documentation

• [[AI-ML-Platform]] - Norns agent integration
• [[AIOps-Platform]] - AIOps architecture overview
• [[AIOps-GitLab-Integration]] - GitLab incident tracking
• [[Identity-Management-OpenFGA]] - Authorization model
• [[Observability]] - Grafana/Prometheus integration