NthLayer

An open-source reliability platform for SREs. NthLayer compiles your service reliability requirements — SLOs, alerts, dashboards, deployment gates, dependency graphs — into observable production infrastructure, then runs an autonomous reliability runtime that observes those services, judges their health, correlates incidents, responds to breaches, and learns from outcomes. Built on the OpenSRM specification.

This repository is the project front door + ecosystem hub. Implementation lives in the per-tier ecosystem repos described below; ecosystem-spanning artefacts (integration tests, demo materials, specifications, design docs, the GitHub Action, and the PyPI meta-package) live here.

What's in this repo

Beyond project documentation, this front-door hosts ecosystem-spanning artefacts:

• GitHub Action (action.yml) — wraps nthlayer-generate for CI/CD pipelines via uses: rsionnach/nthlayer@<tag>
• PyPI meta-package (meta-package/) — source for pip install nthlayer. Dependency-only; pins the four sub-packages at matching versions (e.g. ==1.0.0).
• Integration tests (test/) — three-tier integration test infrastructure (integration-three-tier.sh, fake-service exporters, docker-compose stack with Prometheus/Grafana/AlertManager) verifying the runtime architecture end-to-end
• Demo materials (demo/) — runnable cascading-failure scenario, demo orchestrator (demo.sh), and example OpenSRM specifications
• Specifications (docs/specs/) — current NthLayer architectural specs (Spec Index, Serve Mode v2.1, Bench v2.1, Common, Telemetry Envelope, Learn, Measure, Correlate)
• Roadmap (docs/roadmap/) — proposed/upcoming features (Discovery, Drift Detection, Execution & Change Events, Missing Capabilities)
• Archived specs (docs/archived-specs/) — historical record of superseded or shipped designs (see docs/archived-specs/README.md for archival criteria)
• Architectural design docs (docs/superpowers/) — per-phase plans and per-component design specs
• Operational docs (docs/) — testing conventions, cost optimisation, metrics contract
• Project-level Claude Code context (CLAUDE.md) — ecosystem orientation for AI-assisted development
• CI workflows (.github/workflows/) — docs site build, meta-package release, nightly cross-repo three-tier integration test, Docker image publish

The ecosystem

NthLayer spans seven active repositories: this front-door + ecosystem hub plus six implementation repos — one specification, one shared library, one compiler, and three runtime tiers:

Repo	Role
opensrm	The OpenSRM specification — the manifest format and language for declaring reliability.
nthlayer-common	Shared library: verdict model, manifest parser, LLM wrapper, error hierarchy, CoreAPIClient. Imported by every other repo.
nthlayer-generate	The deterministic compiler: specs → SLOs, alerts, dashboards, recording rules, Backstage entities. CI/CD gate via GitHub Action.
nthlayer-core	Tier 1 — reliability-critical state. HTTP API server, verdict store, case management, manifest catalogue.
nthlayer-workers	Tier 2 — background computation. Five worker modules: observe (SLO assessment), measure (judgment SLO eval), correlate (session-window event correlation), respond (incident response coordinator), learn (outcome resolution + retrospectives). All communicate with core via HTTP.
nthlayer-bench	Tier 3 — operator interface. Textual TUI for SREs: situation board, case bench, approval flows, on-call status.

Where to start

You want to evaluate NthLayer for your organisation. Start at opensrm for the architectural model, then read nthlayer-generate's README for the build-time experience and walk through the example service definitions there.

You want to stand up NthLayer's runtime tier on a fresh machine. Read nthlayer-core/docs/deploying.md — eight-step tutorial from uv tool install to a verdict round-tripping through the running server, plus reference and Litestream hardening.

You want to use NthLayer's GitHub Action in your CI pipeline. This repo's action.yml is the entry point — add uses: rsionnach/nthlayer@v1 (or pin to a specific tag) to your workflow. The action delegates to nthlayer-generate; see its README for the supported subcommands.

You want to contribute to a specific component. Each implementation repo has its own contributor guide, test suite, and CLAUDE.md. Pick the tier or layer relevant to your interest and open a PR there.

You want to understand the design decisions. Architectural decisions, RFCs, and migration plans live in docs/superpowers/. Notable: the three-tier architecture decision (2026-04-21) and the six-repo consolidation rationale (2026-04-21).

Current status

NthLayer is in v1.5 development. The three-tier architecture is being actively built; the six-repo consolidation completed 2026-04-26. Production-ready usage today centres on nthlayer-generate (the compiler — stable surface, CI/CD-ready) plus the OpenSRM spec.

The runtime tiers (nthlayer-core, nthlayer-workers, nthlayer-bench) are implemented and under integration testing for v1.5. Incremental release notes will land in each repo's CHANGELOG as the runtime layers stabilise.

Licence

MIT. See LICENSE.