mirror of
https://github.com/blackboxprogramming/BlackRoad-Operating-System.git
synced 2026-03-17 07:57:19 -05:00
9644737ba7
## Domain Architecture - Complete domain-to-service mapping for 16 verified domains - Subdomain architecture for blackroad.systems and blackroad.io - GitHub organization mapping (BlackRoad-OS repos) - Railway service-to-domain configuration - DNS configuration templates for Cloudflare ## Extracted Services ### AIops Service (services/aiops/) - Canary analysis for deployment validation - Config drift detection - Event correlation engine - Auto-remediation with runbook mapping - SLO budget management ### Analytics Service (services/analytics/) - Rule-based anomaly detection with safe expression evaluation - Cohort analysis with multi-metric aggregation - Decision engine with credit budget constraints - Narrative report generation ### Codex Governance (services/codex/) - 82+ governance principles (entries) - Codex Pantheon with 48+ agent archetypes - Manifesto defining ethical framework ## Integration Points - AIops → infra.blackroad.systems (blackroad-os-infra) - Analytics → core.blackroad.systems (blackroad-os-core) - Codex → operator.blackroad.systems (blackroad-os-operator) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
BlackRoad OS - Analytics Service
Business intelligence, anomaly detection, and decision automation
Overview
The Analytics service provides intelligent business analytics, anomaly detection, cohort analysis, and automated decision planning for BlackRoad OS.
Features
Anomaly Detection (anomaly_rules.py)
- Rule-based metric anomaly detection
- Safe expression evaluation with AST visitor pattern
- Configurable severity levels
- Percentage drop and delta threshold detection
- Time series analysis with trailing window
Cohort Analysis (cohorts.py)
- User segmentation and cohort tracking
- Multi-metric aggregation:
- Revenue
- Gross margin percentage
- NPS (Net Promoter Score)
- Return rate
- Uptime
- MTTR (Mean Time To Recovery)
- Period-based bucketing (Monthly, Weekly, Quarterly)
Decision Engine (decide.py)
- Action heuristics mapping
- Credit budget constraints
- Goal-based action selection
- RACI matrix generation
- Impact-scored decision optimization
- Multi-goal support
Narrative Generation (narrative.py)
- Automated report generation (Markdown, PPTX)
- Executive summaries with structured sections:
- What happened
- Why it matters
- What we're doing
- Risks & Next Steps
- Schema validation for outputs
Configuration
Config files expected at:
configs/analytics/
├── rules.yaml # Anomaly detection rules
├── goals.yaml # Business goals
├── constraints.yaml # Decision constraints
└── cohorts.yaml # Cohort definitions
Usage
from services.analytics import anomaly_rules, decide, narrative
# Detect anomalies
anomalies = anomaly_rules.run_rules(rules_path, "7d")
# Plan actions based on anomalies
plan_path = decide.plan_actions(anomalies_path, goals_path, constraints_path)
# Generate narrative report
report = narrative.generate(data, template="executive")
Integration
Railway Deployment
- Service:
blackroad-os-core - Domain:
core.blackroad.systems - Health:
GET /health
Endpoints
POST /v1/analytics/anomalies- Detect anomaliesGET /v1/analytics/cohorts/:id- Get cohort metricsPOST /v1/analytics/decide- Plan actionsPOST /v1/analytics/report- Generate narrative
Artifacts
All operations generate artifacts in:
artifacts/
├── anomalies/
│ ├── YYYYMMDDHHMMSS.json
│ ├── YYYYMMDDHHMMSS.md
│ └── latest.json
├── decisions/
│ └── plan_YYYYMMDDHHMMSS.json
└── reports/
└── YYYYMMDDHHMMSS.md
Decision Heuristics
Built-in action mappings:
| Metric | Action | Bot | Credits | Impact |
|---|---|---|---|---|
| uptime | SRE mitigation | sre_bot | 8 | 4 |
| revenue | Adjust Pricing | pricing_bot | 10 | 5 |
Source
Extracted from: blackroad-prism-console/analytics/