RevRisk transforms raw business data into prioritized decisions by combining automated analytics, explainable risk scoring, and AI-generated executive reporting.
Live App → nithink-pixelrevrisk.streamlit.app GitHub → github.com/nithink-pixel/revrisk
A Business Operations Manager opens eight dashboards every Monday morning. They pull numbers from three different sources, build a slide manually, and spend two hours answering: "How did we do last week, and why?"
RevRisk collapses that workflow into one system. Open it, and in 60 seconds you know what happened, why it happened, and what to do next.
Raw Transactional Data (61K+ records, 3 years)
↓
ETL Pipeline (12 validation rules, quarantine layer)
↓
DuckDB Warehouse (6 production tables)
↓
Metrics Engine (single source of truth for all KPIs)
↓
Analytics Engine
├── KPI Drift Detector (z-score anomaly detection)
├── Business Risk Index (multi-factor, explainable scoring)
└── Opportunity Finder (potential revenue estimation)
↓
Canonical Signals Table (everything downstream reads this)
↓
Decision Prioritization (Impact × Confidence × Urgency)
↓
Context Builder (structured JSON — models compute, LLM communicates)
↓
Claude API (executive brief generation)
↓
Streamlit Dashboard (6-tab analyst workflow) + PDF Export
1. Canonical Signals Table Every downstream component — dashboard, AI brief, PDF export — reads from one schema. The dashboard does not read KPI tables. The AI does not read KPI tables. Everything reads Signals. This is how real analytics platforms are built.
2. Explainable Risk Scoring The Business Risk Index is not a black box. Every score shows exactly which factors drove it and by how much:
Risk Score: 0.71
↓ Revenue Trend: 0.38 weight × 0.82 score = 0.31
↓ Order Trend: 0.27 weight × 0.71 score = 0.19
↓ Margin Trend: 0.19 weight × 0.42 score = 0.08
↑ Volatility: 0.16 weight × 0.81 score = 0.13
If an interviewer asks "why is SMB ranked #1?", the answer is traceable to the source data in under 30 seconds.
3. Decision Prioritization The system does not produce 25 alerts. It produces 3 priorities.
Priority Score = Business Impact × Confidence × Urgency
Executives get what they need: not data, decisions.
4. AI Architecture The analytics engine computes. Claude communicates. The context builder packages only the top 10 signals into structured JSON before calling the API. Claude never receives raw tables. Every number in the AI brief is traceable to a validated source.
| Tab | Question Answered |
|---|---|
| Overview | How are we doing? |
| Monitor | What is abnormal? |
| Investigate | Why did this happen? |
| Prioritize | What should we address first? |
| Recommend | What does leadership need to know? |
| Data Quality | Can we trust these numbers? |
Detects revenue drops, margin shifts, order anomalies, and return rate spikes using a 30-day rolling baseline and z-score threshold (≥2.0 standard deviations). Lookback window is configurable. Anomalies are scored by severity (Critical ≥4σ, High ≥3σ, Medium ≥2.5σ, Low ≥2σ) and linked directly to the root cause investigation tab.
Multi-factor composite score (0–1) computed for every segment, region, and product category. Four weighted factors:
| Factor | Weight | Measures |
|---|---|---|
| Revenue Trend | 38% | Recent 3-month vs prior 3-month revenue change |
| Order Trend | 27% | Same comparison for order volume |
| Margin Trend | 19% | Margin compression or expansion |
| Volatility | 16% | Coefficient of variation of last 6 months |
Every score is fully explainable: each factor's raw score and weighted contribution are stored in the signals table.
Surfaces three opportunity types with estimated potential revenue:
- Growth Segments — Potential Revenue = Current Revenue × Growth Rate × Expansion Factor
- Underperforming Regions — Revenue gap vs portfolio average × customer count
- High Margin, Low Volume Categories — Volume gap × average order value
Every opportunity includes a confidence score and specific suggested action.
Synthetic but realistic ecommerce dataset generated to reflect genuine business patterns:
- 61,437 transactions across 3 years (Jan 2022 – Dec 2024)
- 500 customers across 3 segments, 5 regions, 6 acquisition channels
- 50 products across 5 categories with realistic price and margin structure
- Seasonal patterns: 60% uplift in Nov-Dec, 25% reduction in Jan-Feb
- Year-over-year growth: 18% annually
- 4 injected anomalies the analytics engine is designed to find:
- Northeast revenue drop (March 2023, –55%)
- Electronics margin collapse (Q3 2023, cost spike +55%)
- SMB churn spike (October 2024, –65% transaction volume)
- Paid Search revenue drop (June 2024, –40% effective price)
12 validation rules enforced on every ETL run. Records failing any rule are quarantined before reaching the warehouse.
| Rule | What It Checks |
|---|---|
| R01 | No null transaction_id |
| R02 | No null date |
| R03 | No null customer_id |
| R04 | No null product_id |
| R05 | Revenue not excessively high (>$50K) |
| R06 | Cost non-negative |
| R07 | Quantity ≥ 1 |
| R08 | Valid is_return flag (0 or 1) |
| R09 | No null region |
| R10 | No null channel |
| R11 | No null segment |
| R12 | No duplicate transaction_id |
| Layer | Tool |
|---|---|
| Data Warehouse | DuckDB |
| ETL & Validation | Python, Pandas |
| Anomaly Detection | NumPy, SciPy |
| Risk Scoring | Scikit-learn (weighted composite) |
| AI Brief | Anthropic Claude API |
| Dashboard | Streamlit, Plotly |
| Testing | Pytest (17 tests, 100% passing) |
| Version Control | Git, GitHub |
git clone https://github.com/nithink-pixel/revrisk.git
cd revrisk
pip install -r requirements.txt
# Generate data and run ETL
python data/generate_data.py
python etl/run_etl.py
python analytics/signals_engine.py
# Run tests
python -m pytest tests/ -v
# Launch dashboard
streamlit run dashboard/app.pyFor AI-powered executive briefs, set your API key:
export ANTHROPIC_API_KEY=your_key_hereThe dashboard works fully without an API key — the AI brief falls back to a data-driven template using real signals.
revrisk/
├── data/
│ ├── generate_data.py ← synthetic data generator
│ └── raw/ ← generated CSVs
├── etl/
│ └── run_etl.py ← 12-rule validation + DuckDB loading
├── analytics/
│ ├── metrics.py ← single source of truth for KPIs
│ ├── anomaly_detector.py ← z-score drift detection
│ ├── risk_scorer.py ← Business Risk Index (explainable)
│ ├── opportunity_finder.py ← potential revenue estimation
│ └── signals_engine.py ← canonical signals table + prioritization
├── ai/
│ ├── context_builder.py ← structured JSON packaging for Claude
│ └── brief_generator.py ← AI executive brief generation
├── dashboard/
│ └── app.py ← 6-tab Streamlit dashboard
├── tests/
│ └── test_revrisk.py ← 17 tests across all modules
├── requirements.txt
└── README.md
Built RevRisk, an end-to-end analytics platform using Python, DuckDB, SQL, and Streamlit that processed 61K+ transactions across three years to detect KPI anomalies, generate explainable business risk scores, prioritize revenue opportunities, and automate executive reporting through AI-generated decision briefs — validated by 17 automated tests and deployed as a live application.
Most analytics projects answer "what happened." This one answers "what should we do about it."
The design choice I'm most proud of is the canonical Signals table. Every module — anomaly detection, risk scoring, opportunity finding — writes to one schema. The dashboard, AI, and PDF all read from that one schema. It is a simple constraint that forces coherence across the entire system. Without it, every new feature would need to know where every other feature stores its data. With it, the system can grow without getting messy.
The second choice I'm proud of: the AI never calculates. The context builder packages validated signals into structured JSON, and Claude translates numbers into recommendations. The brief is accurate because the numbers come from tested code, not from a language model's intuition.