Current section
Files
Jump to
Current section
Files
threadline
README.md
README.md
<picture>
<source media="(prefers-color-scheme: dark)" srcset="brandbook/logo-primary.svg">
<img alt="Threadline" src="brandbook/logo-primary-light.svg" width="420">
</picture>
# Threadline
[](https://github.com/szTheory/threadline/actions/workflows/ci.yml)
[](https://hex.pm/packages/threadline)
[](https://hexdocs.pm/threadline)
**CI:** Runs on [GitHub Actions](https://github.com/szTheory/threadline/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](guides/getting-started-saas.md) §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](guides/evaluating-threadline.md) | [how-threadline-works.md](guides/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](guides/getting-started-saas.md) | [configuration and commands](guides/configuration-and-commands.md) |
| **Operate** — investigate row changes, actor history, and evidence in the `/audit` console. | [guides/operator-surface.md](guides/operator-surface.md) | [incident-playbook.md](guides/incident-playbook.md) |
| **Contribute** — set up the repo, run `mix ci.all`, and follow the contribution gate. | [`CONTRIBUTING.md`](CONTRIBUTING.md) | [guides/adoption-pilot-backlog.md](guides/adoption-pilot-backlog.md) |
[HexDocs](https://hexdocs.pm/threadline) 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](guides/how-threadline-works.md). For the
named lane contract, including separately authorized `/audit/evidence`, read
[guides/upgrade-path.md](guides/upgrade-path.md). For the public verdict
vocabulary (`claim_assessment`, `proven`, `inferred_posture`, `unsupported`),
read [guides/domain-reference.md](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.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](guides/domain-reference.md) maps each job to the API to use first.
## Quick Start
Add the current Threadline package coordinate to your dependencies:
```elixir
{:threadline, "~> 0.11.0"}
```
Then follow [Getting started with Threadline in a Phoenix SaaS app](guides/getting-started-saas.md)
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](guides/configuration-and-commands.md).
The [domain reference](guides/domain-reference.md) 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](guides/operator-surface.md)
is the sole owner for the supported `threadline_operator_surface/2` mount,
authentication callbacks, screen inventory, and mount-specific configuration.
The [Upgrade Path](guides/upgrade-path.md) 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](guides/operator-surface.md#theme) for the full
`:dark | :light | :system` triad.
Continue with the [canonical first-hour Phoenix walkthrough](guides/getting-started-saas.md),
then use the [Operator Surface guide](guides/operator-surface.md) for fail-closed
authorization and the [integration contracts](guides/integration-contracts.md)
for host/framework boundaries. For current support claims, stay with the
[Upgrade Path](guides/upgrade-path.md) 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 **14 min / 16 current**. The CI `min` lane runs the full suite on Elixir 1.15 / OTP 26 / PostgreSQL 14 so the published floor remains enforced. CI also runs the suite on the newest stable Elixir, OTP and PostgreSQL (the `latest` lane, pinned in `.github/workflows/ci.yml`): Threadline is **tested on** those versions, which is **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](guides/upgrade-path.md). Phoenix auth (reference lanes, pick one): [phx.gen.auth integration](guides/integrations/phx-gen-auth.md) · [Sigra integration](guides/integrations/sigra.md); 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](guides/performance.md) and [guides/incident-playbook.md](guides/incident-playbook.md).
## Documentation
Quick destinations: [Evaluate](guides/evaluating-threadline.md) ·
[Adopt](guides/getting-started-saas.md) ·
[Operate](guides/operator-surface.md) ·
[Contribute](CONTRIBUTING.md)
<details>
<summary>All guides</summary>
- [HexDocs](https://hexdocs.pm/threadline) — the generated API reference.
**Evaluate**
- [How Threadline works](guides/how-threadline-works.md)
- [Code walkthrough](guides/code-walkthrough.md)
- [Evaluating Threadline](guides/evaluating-threadline.md)
- [Domain reference](guides/domain-reference.md)
**Adopt**
- [Getting started with Phoenix SaaS](guides/getting-started-saas.md)
- [Production checklist](guides/production-checklist.md)
- [Brownfield continuity](guides/brownfield-continuity.md)
- [Integration contracts](guides/integration-contracts.md)
- [Local Docker DX](guides/local-docker-dx.md)
- [Support lanes and upgrade path](guides/upgrade-path.md)
- [Upgrading to 0.11](guides/upgrading-to-0.11.md)
**Operate**
- [Operator surface](guides/operator-surface.md)
- [Incident playbook](guides/incident-playbook.md)
- [Performance](guides/performance.md)
- [Audit indexing](guides/audit-indexing.md)
- [Adoption evidence playbook](guides/adoption-evidence-playbook.md)
**Integrations**
- [phx.gen.auth integration](guides/integrations/phx-gen-auth.md)
- [Sigra integration (reference lane)](guides/integrations/sigra.md)
**Contribute**
- [CONTRIBUTING.md](CONTRIBUTING.md)
- [Adoption pilot backlog](guides/adoption-pilot-backlog.md)
- [CHANGELOG.md](CHANGELOG.md)
</details>