Threadline

CI: Runs on GitHub Actions.

Auditing for Phoenix, without a separate event system or black box.

Threadline is an open-source audit library for Elixir teams using Phoenix, Ecto, and PostgreSQL. It combines PostgreSQL trigger capture with application-level actor, intent, and correlation context.

New Phoenix integrations should use Threadline.Audit.transaction/3; see Getting started §6.

Use it when you want the audit layer in your app, not a separate event system or a black box.

Start here

Pick the row that matches what you want to do. Each lane points at its canonical landing and the next guide to read.

I want to...	Start here	Then read
Evaluate — see what Threadline proves in-repo, and what you must prove in staging.	guides/evaluating-threadline.md	how-threadline-works.md
Adopt — install, capture one real write, and mount the operator surface in the first hour. Wire it into a Phoenix app.	guides/getting-started-saas.md	configuration and commands
Operate — investigate row changes, actor history, and evidence in the /audit console.	guides/operator-surface.md	incident-playbook.md
Contribute — set up the repo, run mix ci.all, and follow the contribution gate.	CONTRIBUTING.md	guides/adoption-pilot-backlog.md

HexDocs remains the complete API reference.

Evidence plane

Use Threadline's evidence to answer a practical operator question: is the audit system configured and behaving the way your team expects right now?

Threadline can persist evidence about its own governance surfaces such as trigger coverage, redaction posture, retention runs, export delivery, and the support-lane posture around mounted capabilities. That evidence plane stays host-owned on authorization and product scope: Threadline does not become a legal hold system, an immutable-storage guarantee beyond the host runtime/storage contract, a generic compliance pack, a vendor-specific reporting suite, or a Threadline-owned RBAC or tenancy DSL.

For the canonical non-goals list, read guides/how-threadline-works.md. For the named lane contract, including separately authorized /audit/evidence, read guides/upgrade-path.md. For the public verdict vocabulary (claim_assessment, proven, inferred_posture, unsupported), read guides/domain-reference.md.

What you get

• Capture: trigger-backed row-change history in PostgreSQL with Threadline.Plug.
• Semantics: Threadline.Audit.transaction/3 as the recommended audited write path (actor, intent, correlation, and request context); Threadline.record_action/2 is the semantic primitive the helper wraps.
• Exploration: timelines and history with Threadline.timeline/2, Threadline.timeline_page/2, and Threadline.row_history/3.
• Operations: exports, snapshots, coverage checks, retention, redaction, and health tooling via Threadline.export_json/2 and Threadline.as_of/4.

The broader public surface includes Threadline.Plug, Threadline.record_action/2, and Threadline.incident_bundle/2; the domain reference maps each job to the API to use first.

Quick Start

Add the current Threadline package coordinate to your dependencies:

{:threadline, "~> 1.1.0"}

Then follow Getting started with Threadline in a Phoenix SaaS app for the single runnable install, configuration, first audited write, and first query path. When you need the exhaustive supported settings and command boundaries, use the configuration and command reference. The domain reference keeps the canonical "which public API first?" table.

Operator Surface

Threadline ships an optional, in-tree LiveView operator console for Find, Verify, and Prove workflows, with no asset build step. Mounting is fail-closed: the host supplies authentication and authorization, and must declare the optional Phoenix surface dependencies. The Threadline UI currently ships as an optional in-tree dependency; the Operator Surface guide is the sole owner for the supported threadline_operator_surface/2 mount, authentication callbacks, screen inventory, and mount-specific configuration. The Upgrade Path owns its support guarantees.

Daytime and bright-environment teams can mount with theme: :system to auto-follow each operator's OS light/dark preference (pure CSS, no JS); see the Operator Surface guide for the full :dark | :light | :system triad.

Continue with the canonical first-hour Phoenix walkthrough, then use the Operator Surface guide for fail-closed authorization and the integration contracts for host/framework boundaries. For current support claims, stay with the Upgrade Path rather than inferring broader compatibility from the README.

Notes

• Supported versions: Elixir 1.15 floor / 1.17.3 current, OTP 26 min / 27 current, PostgreSQL 15 min / 16 current. CI's min lane runs the full suite on Elixir 1.15 / OTP 26 / PostgreSQL 15; current and latest CI versions are in the toolchain support policy table. The latest lane is tested on, not a new support floor.
• Threadline names four support lanes — the canonical capture-only, phoenix-surface, phx-gen-auth-reference, and sigra-reference matrix — in guides/upgrade-path.md. Phoenix auth (reference lanes, pick one): phx.gen.auth integration · Sigra integration; neither is required.
• Threadline works with PgBouncer transaction pooling.
• Redaction drift uses three states: Config matches deployed, Drift detected, and Could not introspect; rerun mix threadline.gen.triggers if the latter two appear.
• Redaction, retention, export, and continuity live in the guides and HexDocs.
• Next operator reads after the first install are guides/performance.md and guides/incident-playbook.md.

Documentation

Quick destinations: Evaluate · Adopt · Operate · Contribute

• HexDocs — the generated API reference.

Evaluate

• How Threadline works
• Code walkthrough
• Evaluating Threadline
• Domain reference

Adopt

• Getting started with Phoenix SaaS
• Production checklist
• Brownfield continuity
• Integration contracts
• Local Docker DX
• Support lanes and upgrade path
• Upgrading to 0.11

Operate

• Operator surface
• Incident playbook
• Performance
• Audit indexing
• Adoption evidence playbook
• Telemetry

Integrations

• phx.gen.auth integration
• Sigra integration (reference lane)

Contribute

• CONTRIBUTING.md
• Adoption pilot backlog
• CHANGELOG.md