paragonie/chronicle

How paragonie/chronicle works

Chronicle is a self-hosted HTTP service for authorized clients to publish signed messages into an append-only cryptographic ledger, then query and export its records. The main path is HTTP request → route and signature validation → publish handler → hash-chain append → database. Administrators can register and revoke clients; public endpoints expose ledger lookups and replica information. The README also documents cross-signing and replication. The sampled source confirms the replication process; cross-signing and other handler internals were not sampled, so their wiring is shown only where supported.

Main entry points: routes.php Routes · Chronicle.php Chronicle core · Replicate.php Replication process · index.php HTTP entry

Components 21

HTTP API

HTTP entry public/index.php
Routes src/routes.php
Publish src/Chronicle/Handlers/Publish.php
Lookup src/Chronicle/Handlers/Lookup.php
API index src/Chronicle/Handlers/Index.php
Mirror list src/Chronicle/Handlers/Mirrors.php
Replica API src/Chronicle/Handlers/Replica.php

Authorization

Client signature src/Chronicle/Middleware/CheckClientSignature.php
Admin signature src/Chronicle/Middleware/CheckAdminSignature.php
Register client src/Chronicle/Handlers/Register.php
Revoke client src/Chronicle/Handlers/Revoke.php

Ledger

Chronicle core src/Chronicle/Chronicle.php
Database setup src/database.php
Ledger database

Federation

Cross-signing src/Chronicle/Process/CrossSign.php
Attestation src/Chronicle/Process/Attest.php
Replication process src/Chronicle/Process/Replicate.php
Scheduled tasks src/Chronicle/Scheduled.php

Other components

API client
Administrator
Upstream Chronicle

Connections 27

API client → HTTP entry: sends request
Administrator → HTTP entry: sends request
HTTP entry → Routes: runs routes
Routes → Client signature: guards publish
Routes → Admin signature: guards admin
Routes → Publish: dispatches
Routes → Register client: dispatches
Routes → Revoke client: dispatches
Routes → Lookup: dispatches
Routes → API index: dispatches
Routes → Mirror list: dispatches
Routes → Replica API: dispatches
Client signature → Chronicle core: verifies client
Admin signature → Chronicle core: verifies admin
Publish → Chronicle core: appends entry
Register client → Chronicle core: manages clients
Revoke client → Chronicle core: manages clients
Lookup → Chronicle core: queries ledger
Replica API → Chronicle core: serves replica data
API index → Chronicle core: reads client access
Database setup → Chronicle core: sets database
Chronicle core → Ledger database: reads and writes
Replication process → Ledger database: reads and writes replica
Replication process → Upstream Chronicle: fetches signed updates
Scheduled tasks → Replication process: runs replication
Cross-signing → Upstream Chronicle: cross-signs
Attestation → Replication process: attests replica

More PHP diagrams: kyon147/laravel-shopify · laksa19/mikhmonv3 · consolibyte/quickbooks-php · ronknight/inventorysystem · neorazorx/facturascripts

Drawn by GitDiagram on September 26, 2026 from the repository's file tree, README and source files. Read as Markdown ·