Pipelines, Jobs, Services, Review Surfaces

Summary

The platform uses four recurring shapes to keep work organized: pipelines keep data correct, jobs do automatic work, services expose capabilities, and review surfaces handle stateful human intervention.

Problem

Many operational features need all four shapes. A domain may ingest source data, run scheduled automation, expose reusable policy, and pause for human repair. If those responsibilities collapse into one file or one abstraction, the platform becomes hard to reason about.

Principle

Choose the shape by responsibility. Do not make a pipeline interactive, do not hide durable review state inside a job, and do not let UI routes become service layers.

Platform Shape

Pipelines live under pipelines/ and perform deterministic ingestion and transforms. Jobs live under jobs/ as executable wrappers and use services, libs, integrations, or pipelines for real behavior. Services live under services/ and expose reusable capabilities. Review surfaces combine API, UI, services, and OLTP state to make ambiguity visible and repairable.

This creates a useful escalation path. Automated work can run as a job. If it hits business ambiguity, it records an issue or review task. A human works that state through a surface, and a job can resume after repair.

Source Evidence

• docs/reference/architecture.md
• docs/reference/job-layout.md
• docs/reference/operational-surface-ownership.md

Related Reading

• docs/engineering/concepts/failures-are-data.md
• docs/engineering/reference/thin-jobs-fat-services.md