mirror of
https://github.com/blackboxprogramming/BlackRoad-Operating-System.git
synced 2026-03-17 04:57:15 -05:00
feat: Add domain architecture and extract core services from Prism Console
## 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>
This commit is contained in:
111
services/analytics/README.md
Normal file
111
services/analytics/README.md
Normal file
@@ -0,0 +1,111 @@
|
||||
# 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/`
|
||||
Reference in New Issue
Block a user