mirror of
https://github.com/blackboxprogramming/BlackRoad-Operating-System.git
synced 2026-03-17 03:57:13 -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>
112 lines
2.8 KiB
Markdown
112 lines
2.8 KiB
Markdown
# 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
|
|
|
|
```python
|
|
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 anomalies
|
|
- `GET /v1/analytics/cohorts/:id` - Get cohort metrics
|
|
- `POST /v1/analytics/decide` - Plan actions
|
|
- `POST /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/`
|