Platform Layers

Summary

The platform layers separate runtime surfaces, capability services, shared contracts, external adapters, deterministic pipelines, executable jobs, and durable documentation.

Problem

Without layers, operational code tends to collapse into whoever called it first. A UI component can become a business service, a job can become the owner of state, or a provider API can leak into every workflow.

Principle

Each layer owns a different kind of change. New work should land where its responsibility will still make sense when another surface needs the same behavior.

Platform Shape

app/ owns runtime adapters: routes, pages, workers, scheduler, and CLI. services/ owns reusable capabilities and stateful domain behavior. libs/ owns pure contracts and deterministic helpers. integrations/ owns external system adaptation. pipelines/ owns ETL. jobs/ owns thin executable entrypoints. infra/ owns migrations, hooks, and deployment support. docs/ owns durable explanation and reference.

This is not a microservice layout. It is a modular monorepo layout that makes future physical splits easier because conceptual boundaries are already visible.

Source Evidence

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

Tradeoffs

Layering creates more files than a script-first approach. The payoff is that the repo can grow across domains without every feature inventing its own local platform.

  • docs/engineering/architecture/monorepo-as-operational-platform.md
  • docs/engineering/reference/thin-jobs-fat-services.md