Platform Foundation
Summary
LKCI is a living operational platform for a real company. That matters because the architecture is not optimized for demos, isolated scripts, or pure analytics. It is optimized for work that starts in messy external systems, passes through data products and automation, hits human judgment, produces auditable state, and sometimes writes back to providers or communicates outside the company.
The foundation is the vocabulary that keeps those workflows composable: pipelines keep data correct, services expose capabilities, integrations adapt providers, jobs move work forward, UI/API surfaces adapt human intent, and review surfaces make ambiguity repairable. A new feature should be judged by how clearly it fits that model, not by how quickly the first route or script can be written.
Reader Question
When an engineer adds a workflow, where should the durable state live, which layer owns each transition, and what happens when automation cannot safely continue?
Start With The Work
The platform is easiest to understand from recognizable work. A campaign needs authoring, audience materialization, review, delivery, actions, and attribution. A geo analysis needs source discovery, scoring, map inspection, and saved selections. A POA workflow needs document evidence, interpretation, repair, and external sync. A payroll review needs source refresh, operator correction, blockers, and provider dispatch. These are not just screens. They are operational state machines.
The foundation asks each workflow the same questions. What facts arrive from outside? Which facts are analytical history? Which facts are current interactive state? Which side effects leave the platform? Which decisions need an actor? Which failures should become retryable state or review issues? If those answers are clear, the package layout usually follows naturally.
This posture keeps LKCI from becoming a collection of good local solutions that cannot compose. A route handler can call a provider directly. A job can join raw tables and send an email. A component can hide a state transition in an on-click handler. Each shortcut may work once. The platform foundation exists to make those shortcuts unnecessary and visible when they appear.
Platform Primitives
Pipelines are deterministic data machinery. They ingest, canonicalize, enrich, and publish datasets. They do not own human review, pause for operators, or send provider commands as hidden side effects. When pipeline output is not safe enough for a workflow, it should publish a signal or feed a reviewable state machine.
Jobs are automated execution wrappers. They run on schedules or triggers, parse explicit parameters, call services, and record execution results. Jobs should be thin enough that their behavior can also be invoked by tests, APIs, or future agents through the underlying service layer. A job that contains the real domain logic is a sign that the capability is not yet reusable.
Services are the main composition layer. A service should expose a capability: load a read model, create an issue, materialize an audience, dispatch a command, render an artifact, validate a payload, or publish a serving snapshot. It should not force callers to understand table internals or vendor payloads. Shared deterministic contracts belong in libs; persistence-backed behavior belongs in services.
Integrations live at the edge. They normalize external systems inward and return internal results with enough diagnostics for retry and repair. Domain services should not become vendor clients. Provider details can be messy; the mess should stop at the boundary.
UI/API surfaces are adapters, not owners of business truth. Routes establish tenant and actor context, validate requests, call services, and map responses. UI surfaces show queues, cases, artifacts, diagnostics, available actions, and read models. They should make state visible without becoming the state machine.
Failure As Data
The central rule is that business ambiguity should become data. A stale source fact, low-confidence geocode, missing template field, uncertain document interpretation, blocked customer target, provider rejection, or incomplete morning brief payload is not the same thing as a programmer error. It needs status, diagnostics, retry policy, review state, or a repair action.
This is the difference between automation and an operating platform. Automation can stop when reality is messy. A platform should pause visibly, explain what it knows, and let a person or later job resume from the right place. That is why review surfaces, issue records, timelines, delivery attempts, action executions, and run history are architectural primitives rather than optional UI conveniences.
The rule also applies to future AI and agentic work. An agent should observe the same state a human sees, propose or request actions through the same contracts, and leave audit evidence. It should not gain power by bypassing the service, provider, or review boundaries that make human operations safe.
Data And State Ownership
The platform currently uses one Postgres database with multiple schemas, but ownership is conceptual first. Lakehouse schemas carry source history, canonical entities, and analytical products. Domain OLTP schemas carry interactive workflow state. The ops schema carries execution and support state such as job runs, DAG runs, schedules, LLM audit, sync operations, and messaging support. Those responsibilities should remain distinct even before the database is physically split.
This separation is visible in real workflows. Marketing runtime rows are not raw analytics facts. Geo score rows are not marketing campaign members. A POA review decision is not a lakehouse rebuild. A notification delivery attempt is not the same as the domain event that requested communication. The foundation works when each fact has an owner and each transition has a boundary.
Extension Checklist
Before adding a feature, identify the entry surface. Is this an operator workflow, a scheduled refresh, an event-triggered job, a provider command, a data publication, or a review/repair surface? Then identify the durable object and the allowed state transitions. If the feature can fail, decide what the repairable state looks like before writing the happy path.
Next, place the logic in the smallest reusable layer. Deterministic transformations and shared contracts go in libs. Capability and workflow state go in services. Provider adaptation goes in integrations. Thin execution wrappers go in jobs. API routes adapt requests. UI components consume read models and available actions. Pipelines publish data products.
Finally, make context explicit. Tenant, actor, run, source, provider, prompt, artifact, idempotency, and freshness context are not decoration. They are what let another engineer or support person explain what happened months later.
What Good Extensions Look Like
A good extension feels boring at the boundary even if the domain problem is new. A new provider integration normalizes outward mess into internal contracts and returns structured diagnostics. A new job parses parameters, loads environment, calls a service, and records progress. A new review surface shows state that already exists in the domain model. A new analytics product publishes through a named data product and exposes freshness. A new AI feature records generated evidence and lets the owning workflow validate or reject it.
The opposite pattern is usually easy to spot. Business policy appears in a route file. A UI component joins analytical tables. A job contains the only copy of a workflow transition. A provider client leaks into a domain service or page handler. A model response is treated as a decision without validation. Those choices may ship quickly, but they make the platform less explainable.
The foundation does not require every feature to become large. It requires the smallest version of the feature to land in the right layer with enough state for repair, audit, and reuse.
That is the standard this engineering site should reinforce. Every strong domain post should make the same contract visible in a concrete workflow, with examples specific enough to guide implementation.
Visual
The current visual is the source-backed graph neighborhood. The intended mental visual is a layered operating map: sources and providers at the edge; pipelines, integrations, and services in the middle; jobs and UI/API surfaces as execution adapters; domain state machines and review surfaces as the place where work becomes auditable; operations and guardrails underneath.
Why This Is Durable
The foundation is durable because it is not tied to one domain's current shape. Marketing, geo, POA, precon, payroll, notifications, and operations all look different to users, but they reuse the same posture: explicit state, capability services, provider boundaries, thin jobs, data publication, reviewable failures, and tests around behavior. When a new domain arrives, it should inherit that posture instead of inventing a private architecture.
Documentation is part of the foundation. The engineering site, graph, inventory, visuals, and content checks are not separate from the platform. They are how a future engineer or agent learns the boundaries before changing them.
Source Evidence
docs/reference/architecture.mdAGENTS.mddocs/reference/operational-surface-ownership.md