Data To Review Surface
Summary
This thread answers the question that sits between the lakehouse and the operator console: how does trustworthy data become reviewable operational state? The answer is not "let the UI query more tables." Source data becomes useful to a human when the platform publishes bounded state, creates issues when ambiguity matters, exposes artifacts and actions, and gives automation a resumable path after a person intervenes.
The thread connects data boundaries to review primitives. It starts with canonical source evidence, moves through serving projections and read models, then reaches cases, issues, review tasks, repair actions, and workflow resumption.
Reader Question
How does a platform convert canonical facts into a queue, detail view, repair surface, or approval decision without blurring analytics, OLTP state, and human workflow responsibility?
Surface Or Workflow
The entry point is an operator-facing surface: identity resolution review, POA repair, precon solicitation review, payroll exception review, or a future domain queue. The operator is not trying to inspect a warehouse. They need to know what is blocked, what evidence supports the system's interpretation, what actions are available, and what happens after they decide.
That means the data handoff must produce serving state rather than forcing a page to assemble operational truth from raw analytical joins. API routes should adapt request context and call services. Services should return read models and action descriptors. Jobs should publish review cases or resume blocked work after state changes.
Lifecycle
The lifecycle begins with source intake and canonicalization. Pipelines and lakehouse services establish source-backed facts, identities, crosswalks, and freshness signals. A publish step then decides which facts become eligible for interactive use.
From there, a domain service or shared workflow service turns the signal into reviewable state. That state may be a case, issue, event, artifact, review task, action request, or domain-specific queue item. The important boundary is that the review surface owns user-facing state and auditability; the upstream pipeline remains rebuildable and non-interactive.
When the operator acts, the decision is recorded with actor context. The result may close an issue, update domain state, enqueue a follow-on job, or resume a previously blocked dependency. The workflow should be able to explain both the original automated interpretation and the human correction that made resumption safe.
Child Threads
cases-issues-events: when ambiguity becomes durable state.review-queues: how queue eligibility differs from raw data availability.artifact-viewers: how evidence is shown without turning UI into storage logic.repair-actions: how human decisions become validated state transitions.approval-and-actor-context: why every mutation needs tenant and actor context.workflow-resumption: how jobs continue after review without losing idempotency.issue-taxonomy: how repeated ambiguity becomes diagnosable.
Implementation Boundaries
services/workflow contains shared cases, issues, events, read models, locks, commands, and resumption concepts. app/api/workflow adapts those capabilities to HTTP surfaces such as identity resolution. jobs/workflow owns scheduled or resumptive entrypoints that publish review cases or execute approved transfers. Domain systems such as POA and precon remain responsible for their own business semantics even when they reuse the same review vocabulary.
Tests under tests/workflow are part of the architecture. They protect review API contracts, queue/detail read models, resumption behavior, and decision services. Without those tests, a review surface can appear correct while quietly breaking audit or resume semantics.
Tradeoffs
This model adds a layer between analytical truth and UI state. That layer is intentional. It prevents operators from depending on unstable analytical joins, keeps pipelines rebuildable, and lets humans repair state without mutating source facts. The cost is extra modeling: queues, issues, artifacts, actions, and resumption hooks all need names. The benefit is that every blocked automation path can become visible and repairable.
Visual
The current visual is a graph neighborhood tying this thread to workflow services, domain docs, and source evidence. The target first-level visual is a data-to-review lifecycle diagram: source fact, publish step, review state, human action, resumed automation, and audit trail.
Source Evidence
docs/reference/architecture.mddocs/domains/poa.mddocs/domains/preconstruction.mdservices/workflowapp/api/workflowjobs/workflowtests/workflow