Value Stream Documentation¶
Value Stream is a configuration-driven, aggregate-first business intelligence platform. It loads file-based exports (typically Pega CDH Interaction History and Product Holdings), reduces raw rows to persisted mergeable aggregate statistics during one chunk pass, and serves reports, dashboards, aggregate chat, SDK queries, and SQL exports from those aggregates. Raw event rows never survive the chunk pass.
Find Your Path¶
| Reader | Start here | Then read | Reference when needed |
|---|---|---|---|
| Business user / analyst | Getting started | Running reports, Chat with data | FAQ, Business functionality |
| Product owner / stakeholder | Product overview | Business functionality | FAQ, Architecture overview |
| Workspace operator / data engineer | Pega export tutorial | Operations runbook | CLI reference, Readers & formats |
| Developer | Architecture overview | Architecture, Domain model, Replacement design | Processors, Algorithms, Expression DSL |
| Auditor / reviewer | Business functionality (governance) | Troubleshooting (escalation data) | FAQ, Domain model |
| Documentation maintainer | Documentation guide | — | — |
How These Docs Are Organized¶
The documentation follows the Diátaxis model: each page belongs to exactly one genre, and roles enter through the paths above rather than through per-role copies of the same content.
| Section | Genre | Question it answers |
|---|---|---|
| Tutorials | Learning-oriented | "Can I try it end to end?" — runnable, start to finish |
| Guides | Task-oriented | "How do I accomplish X?" — users, configuration, operations |
| Concepts | Understanding-oriented | "Why is it built like this?" — product, business, architecture, decisions |
| Reference | Information-oriented | "What exactly is X?" — CLI, DSL, processors, algorithms, charts, API, FAQ |
| Design docs | Engineering history | "What is the full intended design?" — the master replacement design |
Current Scope¶
| Area | Current status |
|---|---|
| Ingestion | File discovery, readers, transforms, chunk ledger, processor fan-out, and aggregate writes |
| Analytics | Binary outcomes, numeric distributions, score distributions, lifecycle, sets, funnels, and snapshots |
| Reports | Streamlit dashboards, report filters, chart rendering, inspection mode, and freshness metadata |
| Configuration | YAML catalog, validation, direct editors, shared KPI recipe library, deterministic builder, and AI-assisted draft flow |
| Operations | Validation, data load, run history, chunk detail, vacuum, and DuckDB export |
| Headless access | Local read-only stdio MCP and read-only FastAPI HTTP API; governed SQL is opt-in |
| Deferred | Remote HTTP MCP and multi-user/OIDC service deployment |
The Docs Are the Spec¶
These documents are the source of truth for Value Stream's behavior. Every behavior-changing pull request updates the relevant page in the same commit, and doc-only pull requests are first-class. The documentation guide defines the structure, conventions, completeness checklist, and maintenance rules.