Platform Map
Summary
LKCI is best understood as an operational platform with reusable primitives for data, execution, integrations, services, review surfaces, and UI/API apps. The repo layout is not incidental; it is the architectural map.
Problem
When a repo grows from useful automation into company infrastructure, it becomes easy to describe it as "the web app" or "the jobs repo." That framing hides the more important shape: different packages own different operational responsibilities and should remain composable.
Principle
Treat the repo as a living platform. Each layer should expose a clear capability and should leave room for future scale, new domains, and new execution modes.
Platform Shape
The main runtime apps live under app/: API, web, worker, scheduler, and CLI. Business and platform capabilities live under services/. Shared contracts and deterministic helpers live under libs/. Provider-specific adaptation belongs under integrations/. Deterministic data movement belongs under pipelines/. Thin executable automation entrypoints live under jobs/. Durable knowledge, architecture, runbooks, and decisions live under docs/.
This separation lets the same capability serve multiple surfaces. A data product can support a scheduled job, an API read model, an operator queue, and a future agent without every caller learning the same low-level details.
Source Evidence
docs/reference/architecture.mddocs/reference/operational-surface-ownership.mddocs/reference/service-package-categories.md
Tradeoffs
The platform map asks contributors to choose a layer before writing code. That slows one-off work slightly, but it prevents operational behavior from being buried in the first file that happened to need it.
Related Reading
docs/engineering/concepts/engineering-principles.mddocs/engineering/architecture/platform-layers.md