# nucleoledger/nucleo architecture

> Architecture diagram of the GitHub repository nucleoledger/nucleo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nucleoledger/nucleo
- Repository: https://github.com/nucleoledger/nucleo

## Overview

Núcleo is a local cryptographic transparency log, exposed primarily through a per-invocation CLI. The main workflow seals application records into a signed, chained ledger, then issues portable receipts that recipients can verify offline; operators can also reconcile live records, synchronize checkpoints with witnesses, and manage encrypted storage and erasure. The graph includes the Go runtime and the documented TypeScript, PHP, and web verification surfaces. Some command implementations and subsystems were not excerpted, so their documented capabilities are shown without speculative internal call edges.

Main entry points: [`cmd/nucleo/main.go`](https://github.com/nucleoledger/nucleo/blob/main/cmd/nucleo/main.go) (Núcleo CLI), [`sdk/ts/src/receipt.ts`](https://github.com/nucleoledger/nucleo/blob/main/sdk/ts/src/receipt.ts) (TypeScript verifier), [`cmd/nucleo/seal.go`](https://github.com/nucleoledger/nucleo/blob/main/cmd/nucleo/seal.go) (Seal records), [`internal/store/store.go`](https://github.com/nucleoledger/nucleo/blob/main/internal/store/store.go) (SQLite store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI operations"]
  node_cli["Núcleo CLI<br/>[main.go]"]
  node_seal["Seal records<br/>[seal.go]"]
  node_receiptcmd["Issue receipts<br/>[verify_receipt.go]"]
  node_reconcilecmd["Reconcile<br/>[reconcile.go]"]
  node_synccmd["Sync checkpoint<br/>[sync.go]"]
  node_erasecmd["Erase content<br/>[erase.go]"]
end

subgraph group_ledger["Sealing and storage"]
  node_ledgercore["Signed ledger<br/>[block.go]"]
  node_store[("SQLite store<br/>[store.go]")]
  node_integrity["Store integrity<br/>[integrity.go]"]
  node_vault["Encrypted vault<br/>[vault.go]"]
end

subgraph group_proof["Proof and attestation"]
  node_receipt["Receipt format<br/>[receipt.go]"]
  node_proofverify["Receipt verifier<br/>[proof.go]"]
  node_checkpoint["Signed checkpoints<br/>[checkpoint.go]"]
  node_witness["Witness service<br/>[server.go]"]
  node_logsync["Witness sync<br/>[logsync.go]"]
end

subgraph group_ops["Operations and policy"]
  node_reconcile["Reconciliation engine<br/>[reconcile.go]"]
  node_policy["Verification policy<br/>[policy.go]"]
end

subgraph group_verify["Independent verifiers"]
  node_tsverify["TypeScript verifier<br/>[receipt.ts]"]
  node_tscrypto["TS crypto and formats<br/>[crypto.ts]"]
  node_tsmerkle["TS Merkle proofs<br/>[merkle.ts]"]
  node_tscheckpoint["TS checkpoints<br/>[checkpoint.ts]"]
  node_tspolicy["TS policy<br/>[policy.ts]"]
  node_tsbytes["TS byte utilities<br/>[bytes.ts]"]
  node_phpverify["PHP verifier<br/>[Verifier.php]"]
  node_phppolicy["PHP policy<br/>[Policy.php]"]
  node_phpbytes["PHP byte utilities<br/>[Bytes.php]"]
  node_phputf8["PHP UTF-8<br/>[Utf8.php]"]
  node_webverify["Browser verifier<br/>[nucleo-verify.js]"]
end

node_operator(("Operator / app"))
node_recipient(("Receipt recipient"))

node_operator -->|"runs commands"| node_cli
node_cli -->|"dispatches seal"| node_seal
node_cli -->|"dispatches receipt"| node_receiptcmd
node_cli -->|"dispatches reconcile"| node_reconcilecmd
node_cli -->|"dispatches sync"| node_synccmd
node_cli -->|"dispatches erase"| node_erasecmd
node_seal -->|"seals blocks"| node_ledgercore
node_seal -->|"persists ledger"| node_store
node_seal -->|"encrypts payloads"| node_vault
node_store -->|"checks on open"| node_integrity
node_receiptcmd -->|"issues receipt"| node_receipt
node_receipt -->|"uses proof format"| node_proofverify
node_proofverify -->|"verifies checkpoint"| node_checkpoint
node_recipient -->|"verifies offline"| node_tsverify
node_recipient -->|"verifies offline"| node_phpverify
node_recipient -->|"verifies offline"| node_webverify
node_synccmd -->|"requests attestation"| node_logsync
node_logsync -->|"sends checkpoint"| node_witness
node_witness -->|"cosigns checkpoint"| node_checkpoint
node_reconcilecmd -->|"compares records"| node_reconcile
node_reconcile -->|"reads sealed data"| node_store
node_erasecmd -->|"erases stored content"| node_store
node_erasecmd -->|"seals erasure event"| node_ledgercore
node_tsverify -->|"parses checkpoint"| node_tscheckpoint
node_tsverify -->|"validates policy"| node_tspolicy
node_tsverify -->|"checks signatures"| node_tscrypto
node_tsverify -->|"checks inclusion"| node_tsmerkle
node_tsverify -->|"uses byte helpers"| node_tsbytes
node_tspolicy -->|"uses byte helpers"| node_tsbytes
node_tscheckpoint -->|"uses byte helpers"| node_tsbytes
node_tsmerkle -->|"uses byte helpers"| node_tsbytes
node_phppolicy -->|"uses byte helpers"| node_phpbytes
node_phppolicy -->|"uses UTF-8 helpers"| node_phputf8

click node_cli "https://github.com/nucleoledger/nucleo/blob/main/cmd/nucleo/main.go"
click node_seal "https://github.com/nucleoledger/nucleo/blob/main/cmd/nucleo/seal.go"
click node_receiptcmd "https://github.com/nucleoledger/nucleo/blob/main/cmd/nucleo/verify_receipt.go"
click node_reconcilecmd "https://github.com/nucleoledger/nucleo/blob/main/cmd/nucleo/reconcile.go"
click node_synccmd "https://github.com/nucleoledger/nucleo/blob/main/cmd/nucleo/sync.go"
click node_erasecmd "https://github.com/nucleoledger/nucleo/blob/main/cmd/nucleo/erase.go"
click node_ledgercore "https://github.com/nucleoledger/nucleo/blob/main/internal/ledger/block.go"
click node_store "https://github.com/nucleoledger/nucleo/blob/main/internal/store/store.go"
click node_integrity "https://github.com/nucleoledger/nucleo/blob/main/internal/store/integrity.go"
click node_vault "https://github.com/nucleoledger/nucleo/blob/main/internal/vault/vault.go"
click node_receipt "https://github.com/nucleoledger/nucleo/blob/main/internal/receipt/receipt.go"
click node_proofverify "https://github.com/nucleoledger/nucleo/blob/main/internal/proof/proof.go"
click node_checkpoint "https://github.com/nucleoledger/nucleo/blob/main/internal/checkpoint/checkpoint.go"
click node_witness "https://github.com/nucleoledger/nucleo/blob/main/internal/witness/server.go"
click node_logsync "https://github.com/nucleoledger/nucleo/blob/main/internal/logsync/logsync.go"
click node_reconcile "https://github.com/nucleoledger/nucleo/blob/main/internal/reconcile/reconcile.go"
click node_policy "https://github.com/nucleoledger/nucleo/blob/main/internal/policy/policy.go"
click node_tsverify "https://github.com/nucleoledger/nucleo/blob/main/sdk/ts/src/receipt.ts"
click node_tscrypto "https://github.com/nucleoledger/nucleo/blob/main/sdk/ts/src/crypto.ts"
click node_tsmerkle "https://github.com/nucleoledger/nucleo/blob/main/sdk/ts/src/merkle.ts"
click node_tscheckpoint "https://github.com/nucleoledger/nucleo/blob/main/sdk/ts/src/checkpoint.ts"
click node_tspolicy "https://github.com/nucleoledger/nucleo/blob/main/sdk/ts/src/policy.ts"
click node_tsbytes "https://github.com/nucleoledger/nucleo/blob/main/sdk/ts/src/bytes.ts"
click node_phpverify "https://github.com/nucleoledger/nucleo/blob/main/sdk/php/src/Verifier.php"
click node_phppolicy "https://github.com/nucleoledger/nucleo/blob/main/sdk/php/src/Policy.php"
click node_phpbytes "https://github.com/nucleoledger/nucleo/blob/main/sdk/php/src/Bytes.php"
click node_phputf8 "https://github.com/nucleoledger/nucleo/blob/main/sdk/php/src/Utf8.php"
click node_webverify "https://github.com/nucleoledger/nucleo/blob/main/web/verify/nucleo-verify.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_seal,node_receiptcmd,node_reconcilecmd,node_synccmd,node_erasecmd toneBlue
class node_ledgercore,node_store,node_integrity,node_vault toneAmber
class node_receipt,node_proofverify,node_checkpoint,node_witness,node_logsync toneMint
class node_reconcile,node_policy toneRose
class node_tsverify,node_tscrypto,node_tsmerkle,node_tscheckpoint,node_tspolicy,node_tsbytes,node_phpverify,node_phppolicy,node_phpbytes,node_phputf8,node_webverify,node_operator,node_recipient toneIndigo
```

## Components

### CLI operations

- [Núcleo CLI](https://github.com/nucleoledger/nucleo/blob/main/cmd/nucleo/main.go): `cmd/nucleo/main.go`
- [Seal records](https://github.com/nucleoledger/nucleo/blob/main/cmd/nucleo/seal.go): `cmd/nucleo/seal.go`
- [Issue receipts](https://github.com/nucleoledger/nucleo/blob/main/cmd/nucleo/verify_receipt.go): `cmd/nucleo/verify_receipt.go`
- [Reconcile](https://github.com/nucleoledger/nucleo/blob/main/cmd/nucleo/reconcile.go): `cmd/nucleo/reconcile.go`
- [Sync checkpoint](https://github.com/nucleoledger/nucleo/blob/main/cmd/nucleo/sync.go): `cmd/nucleo/sync.go`
- [Erase content](https://github.com/nucleoledger/nucleo/blob/main/cmd/nucleo/erase.go): `cmd/nucleo/erase.go`

### Sealing and storage

- [Signed ledger](https://github.com/nucleoledger/nucleo/blob/main/internal/ledger/block.go): `internal/ledger/block.go`
- [SQLite store](https://github.com/nucleoledger/nucleo/blob/main/internal/store/store.go): `internal/store/store.go`
- [Store integrity](https://github.com/nucleoledger/nucleo/blob/main/internal/store/integrity.go): `internal/store/integrity.go`
- [Encrypted vault](https://github.com/nucleoledger/nucleo/blob/main/internal/vault/vault.go): `internal/vault/vault.go`

### Proof and attestation

- [Receipt format](https://github.com/nucleoledger/nucleo/blob/main/internal/receipt/receipt.go): `internal/receipt/receipt.go`
- [Receipt verifier](https://github.com/nucleoledger/nucleo/blob/main/internal/proof/proof.go): `internal/proof/proof.go`
- [Signed checkpoints](https://github.com/nucleoledger/nucleo/blob/main/internal/checkpoint/checkpoint.go): `internal/checkpoint/checkpoint.go`
- [Witness service](https://github.com/nucleoledger/nucleo/blob/main/internal/witness/server.go): `internal/witness/server.go`
- [Witness sync](https://github.com/nucleoledger/nucleo/blob/main/internal/logsync/logsync.go): `internal/logsync/logsync.go`

### Operations and policy

- [Reconciliation engine](https://github.com/nucleoledger/nucleo/blob/main/internal/reconcile/reconcile.go): `internal/reconcile/reconcile.go`
- [Verification policy](https://github.com/nucleoledger/nucleo/blob/main/internal/policy/policy.go): `internal/policy/policy.go`

### Independent verifiers

- [TypeScript verifier](https://github.com/nucleoledger/nucleo/blob/main/sdk/ts/src/receipt.ts): `sdk/ts/src/receipt.ts`
- [TS crypto and formats](https://github.com/nucleoledger/nucleo/blob/main/sdk/ts/src/crypto.ts): `sdk/ts/src/crypto.ts`
- [TS Merkle proofs](https://github.com/nucleoledger/nucleo/blob/main/sdk/ts/src/merkle.ts): `sdk/ts/src/merkle.ts`
- [TS checkpoints](https://github.com/nucleoledger/nucleo/blob/main/sdk/ts/src/checkpoint.ts): `sdk/ts/src/checkpoint.ts`
- [TS policy](https://github.com/nucleoledger/nucleo/blob/main/sdk/ts/src/policy.ts): `sdk/ts/src/policy.ts`
- [TS byte utilities](https://github.com/nucleoledger/nucleo/blob/main/sdk/ts/src/bytes.ts): `sdk/ts/src/bytes.ts`
- [PHP verifier](https://github.com/nucleoledger/nucleo/blob/main/sdk/php/src/Verifier.php): `sdk/php/src/Verifier.php`
- [PHP policy](https://github.com/nucleoledger/nucleo/blob/main/sdk/php/src/Policy.php): `sdk/php/src/Policy.php`
- [PHP byte utilities](https://github.com/nucleoledger/nucleo/blob/main/sdk/php/src/Bytes.php): `sdk/php/src/Bytes.php`
- [PHP UTF-8](https://github.com/nucleoledger/nucleo/blob/main/sdk/php/src/Utf8.php): `sdk/php/src/Utf8.php`
- [Browser verifier](https://github.com/nucleoledger/nucleo/blob/main/web/verify/nucleo-verify.js): `web/verify/nucleo-verify.js`

### Other components

- **Operator / app**
- **Receipt recipient**

## Connections

- Operator / app → Núcleo CLI: runs commands (evidence: `README.md`)
- Núcleo CLI → Seal records: dispatches seal (evidence: `README.md`)
- Núcleo CLI → Issue receipts: dispatches receipt (evidence: `README.md`)
- Núcleo CLI → Reconcile: dispatches reconcile (evidence: `README.md`)
- Núcleo CLI → Sync checkpoint: dispatches sync (evidence: `README.md`)
- Núcleo CLI → Erase content: dispatches erase (evidence: `README.md`)
- Seal records → Signed ledger: seals blocks (evidence: `README.md`)
- Seal records → SQLite store: persists ledger (evidence: `README.md`)
- Seal records → Encrypted vault: encrypts payloads (evidence: `README.md`)
- SQLite store → Store integrity: checks on open (evidence: `internal/store/integrity.go`)
- Issue receipts → Receipt format: issues receipt (evidence: `README.md`)
- Receipt format → Receipt verifier: uses proof format (evidence: `internal/receipt/receipt.go`)
- Receipt verifier → Signed checkpoints: verifies checkpoint (evidence: `internal/proof/proof.go`)
- Receipt recipient → TypeScript verifier: verifies offline (evidence: `README.md`)
- Receipt recipient → PHP verifier: verifies offline (evidence: `README.md`)
- Receipt recipient → Browser verifier: verifies offline (evidence: `README.md`)
- Sync checkpoint → Witness sync: requests attestation (evidence: `README.md`)
- Witness sync → Witness service: sends checkpoint (evidence: `internal/logsync/logsync.go`)
- Witness service → Signed checkpoints: cosigns checkpoint (evidence: `internal/witness/server.go`)
- Reconcile → Reconciliation engine: compares records (evidence: `README.md`)
- Reconciliation engine → SQLite store: reads sealed data (evidence: `internal/reconcile/reconcile.go`)
- Erase content → SQLite store: erases stored content (evidence: `README.md`)
- Erase content → Signed ledger: seals erasure event (evidence: `README.md`)
- TypeScript verifier → TS checkpoints: parses checkpoint (evidence: `sdk/ts/src/receipt.ts`)
- TypeScript verifier → TS policy: validates policy (evidence: `sdk/ts/src/receipt.ts`)
- TypeScript verifier → TS crypto and formats: checks signatures (evidence: `sdk/ts/src/receipt.ts`)
- TypeScript verifier → TS Merkle proofs: checks inclusion (evidence: `sdk/ts/src/receipt.ts`)
- TypeScript verifier → TS byte utilities: uses byte helpers (evidence: `sdk/ts/src/receipt.ts`)
- TS policy → TS byte utilities: uses byte helpers (evidence: `sdk/ts/src/policy.ts`)
- TS checkpoints → TS byte utilities: uses byte helpers (evidence: `sdk/ts/src/checkpoint.ts`)
- TS Merkle proofs → TS byte utilities: uses byte helpers (evidence: `sdk/ts/src/merkle.ts`)
- PHP policy → PHP byte utilities: uses byte helpers (evidence: `sdk/php/src/Policy.php`)
- PHP policy → PHP UTF-8: uses UTF-8 helpers (evidence: `sdk/php/src/Policy.php`)
