# lexicoding-systems/lexecon-demo architecture

> Architecture diagram of the GitHub repository lexicoding-systems/lexecon-demo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lexicoding-systems/lexecon-demo
- Repository: https://github.com/lexicoding-systems/lexecon-demo

## Overview

1. **Overall shape**
   Lexecon is a Python package that sits between an agent’s tool request and the actual tool execution. Its core responsibility is to decide whether a requested action is allowed, blocked, or escalated, and to write a tamper-evident audit trail for that decision.

2. **Primary control point**
   The architectural gate is `lexecon/enforcement/interceptor.py`. Every agent tool call is expected to enter through `Interceptor.intercept()`. That method is the trust boundary: it receives a normalized tool-call payload, asks policy for a decision, records the result, and only then permits execution.

3. **Policy evaluation layer**
   `lexecon/enforcement/policy_engine.py` implements deterministic policy checks driven by YAML files in `lexecon/policies/`. The repository ships with `default_policy.yaml` and `demo_policy.yaml`, so policy is configuration-driven rather than hardcoded in the execution path.

4. **Decision model**
   `lexecon/enforcement/decision.py` defines the small decision vocabulary: `ALLOW`, `BLOCK`, and `ESCALATE`. This keeps enforcement logic and downstream handling simple: execution is only allowed on `ALLOW`, while malformed or risky inputs fail closed.

5. **Tool execution boundary**
   Actual command execution lives in `lexecon/tools/shell.py`. This layer is intentionally separate from enforcement; it should be called only after an allow decision. The README explicitly warns that direct calls to the tools layer bypass policy and audit entirely.

6. **Audit trail subsystem**
   The audit path is split into three concerns: `record.py` defines the canonical record shape and hashing, `ledger.py` appends records to a JSONL ledger with hash chaining, and `signer.py` handles Ed25519 signing. The audit trail is local-file based and designed to be append-only and verifiable after the fact.

7. **Offline verification**
   `lexecon/audit/verifier.py` replays the ledger offline to check three things: record hash integrity, `previous_hash` continuity, and signature validity. This is what turns the audit log into a tamper-evident artifact rather than just an event log.

8. **External adapter boundary**
   `lexecon/adapters/anthropic_adapter.py` is the integration seam for Anthropic-style agent payloads. Its role is to normalize provider-specific tool-call structures into Lexecon’s internal request shape so the same interceptor and policy engine can be reused regardless of upstream model provider.

9. **CLI and demo flows**
   `lexecon/cli.py` exposes three operational entry points: `init-keys`, `demo`, and `verify`. The demo path exercises the full chain end to end: agent request → interception → policy decision → signed ledger entry → optional execution. The included example script in `examples/` shows the same blocked-destructive-command scenario.

10. **Key management and local state**
   Keys are generated locally into `.lexecon/` as Ed25519 PEM files. This keeps the demo self-contained and offline, but also makes the trust model intentionally local; the repository does not include enterprise key management, HSM/KMS integration, or remote attestation.

11. **Failure mode and security stance**
   The system is designed to fail closed. Tests cover malformed payloads and unsupported tool shapes at both the policy engine and interceptor levels, ensuring that bad inputs block execution rather than slipping through. This is central to the architecture because the main safety guarantee depends on rejecting ambiguous requests.

12. **Testing and CI posture**
   The test suite covers the main subsystems separately and together: policy normalization, interceptor behavior, audit signing/verifying, ledger concurrency, malformed inputs, and the full demo flow. The GitHub Actions workflow runs these checks as the repo’s primary regression guard.

13. **What is intentionally out of scope**
   The repository is about control and verifiable logging, not OS sandboxing or deep command understanding. The README is explicit that direct subprocess use outside the interceptor, advanced command obfuscation, and distributed transparency mechanisms are not solved here. Those are important boundaries to show in any architecture diagram.

Main entry points: [`lexecon/enforcement/interceptor.py`](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/enforcement/interceptor.py) (Interceptor), [`lexecon/cli.py`](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/cli.py) (CLI), [`lexecon/enforcement/policy_engine.py`](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/enforcement/policy_engine.py) (Policy engine), [`lexecon/audit/signer.py`](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/audit/signer.py) (Signer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_enforcement["Enforcement"]
  node_node_interceptor{{"Interceptor<br/>trust boundary<br/>[interceptor.py]"}}
  node_node_policy_engine["Policy engine<br/>deterministic checks<br/>[policy_engine.py]"]
  node_node_decision(("Decision model<br/>enum<br/>[decision.py]"))
end

subgraph group_group_audit["Audit"]
  node_node_record["Audit record<br/>record schema<br/>[record.py]"]
  node_node_ledger[("Ledger<br/>append-only log<br/>[ledger.py]")]
  node_node_signer["Signer<br/>Ed25519<br/>[signer.py]"]
  node_node_verifier["Verifier<br/>offline check<br/>[verifier.py]"]
end

subgraph group_group_adapters["Adapters"]
  node_node_adapter["Anthropic adapter<br/>normalizer"]
end

subgraph group_group_runtime["Runtime"]
  node_node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_node_demo["Demo flow<br/>scenario"]
  node_node_shell["Shell tools<br/>executor<br/>[shell.py]"]
  node_node_init_keys["Key init<br/>cli command<br/>[cli.py]"]
  node_node_verify_cmd["Verify cmd<br/>cli command<br/>[cli.py]"]
  node_node_demo_cmd["Demo cmd<br/>cli command<br/>[cli.py]"]
end

subgraph group_group_policy["Policies"]
  node_node_default_policy["Default policy<br/>yaml policy"]
  node_node_demo_policy["Demo policy<br/>yaml policy<br/>[demo_policy.yaml]"]
end

node_node_demo -->|"normalize"| node_node_adapter
node_node_adapter -->|"submit"| node_node_interceptor
node_node_cli -->|"init-keys"| node_node_init_keys
node_node_cli -->|"demo"| node_node_demo_cmd
node_node_cli -->|"verify"| node_node_verify_cmd
node_node_demo_cmd -->|"request"| node_node_adapter
node_node_interceptor -->|"evaluate"| node_node_policy_engine
node_node_policy_engine -->|"load"| node_node_default_policy
node_node_policy_engine -->|"load"| node_node_demo_policy
node_node_policy_engine -->|"decide"| node_node_decision
node_node_interceptor -->|"shape"| node_node_record
node_node_record -->|"hash"| node_node_signer
node_node_signer -->|"append"| node_node_ledger
node_node_interceptor -->|"write"| node_node_ledger
node_node_interceptor -->|"allow only"| node_node_shell
node_node_ledger -->|"replay"| node_node_verifier
node_node_signer -->|"validate"| node_node_verifier
node_node_cli -->|"run"| node_node_verifier
node_node_interceptor -->|"gate"| node_node_decision

click node_node_cli "https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/cli.py"
click node_node_demo "https://github.com/lexicoding-systems/lexecon-demo/blob/main/examples/block_destructive_shell.py"
click node_node_adapter "https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/adapters/anthropic_adapter.py"
click node_node_interceptor "https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/enforcement/interceptor.py"
click node_node_policy_engine "https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/enforcement/policy_engine.py"
click node_node_decision "https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/enforcement/decision.py"
click node_node_default_policy "https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/policies/default_policy.yaml"
click node_node_demo_policy "https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/policies/demo_policy.yaml"
click node_node_shell "https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/tools/shell.py"
click node_node_record "https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/audit/record.py"
click node_node_ledger "https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/audit/ledger.py"
click node_node_signer "https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/audit/signer.py"
click node_node_verifier "https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/audit/verifier.py"
click node_node_init_keys "https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/cli.py"
click node_node_verify_cmd "https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/cli.py"
click node_node_demo_cmd "https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/cli.py"

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_node_interceptor,node_node_policy_engine,node_node_decision toneBlue
class node_node_record,node_node_ledger,node_node_signer,node_node_verifier toneAmber
class node_node_adapter toneMint
class node_node_cli,node_node_demo,node_node_shell,node_node_init_keys,node_node_verify_cmd,node_node_demo_cmd toneRose
class node_node_default_policy,node_node_demo_policy toneIndigo
```

## Components

### Enforcement

Trust boundary, policy evaluation, and decisioning for tool calls.

- [Interceptor](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/enforcement/interceptor.py): trust boundary · Primary gate that receives tool calls, consults policy, records decisions, and permits or blocks execution. · `lexecon/enforcement/interceptor.py`
- [Policy engine](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/enforcement/policy_engine.py): deterministic checks · Evaluates normalized requests against configured policy rules. · `lexecon/enforcement/policy_engine.py`
- [Decision model](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/enforcement/decision.py): enum · ALLOW, BLOCK, and ESCALATE decision vocabulary. · `lexecon/enforcement/decision.py`

### Audit

Append-only record, signing, and offline verification.

- [Audit record](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/audit/record.py): record schema · Canonical audit record shape and hashing inputs. · `lexecon/audit/record.py`
- [Ledger](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/audit/ledger.py): append-only log · JSONL ledger with hash chaining for recorded decisions. · `lexecon/audit/ledger.py`
- [Signer](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/audit/signer.py): Ed25519 · Signs audit records for tamper evidence. · `lexecon/audit/signer.py`
- [Verifier](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/audit/verifier.py): offline check · Replays the ledger to validate hashes, continuity, and signatures. · `lexecon/audit/verifier.py`

### Adapters

Provider-specific payload normalization into Lexecon's internal request shape.

- [Anthropic adapter](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/adapters/anthropic_adapter.py): normalizer · Converts provider payloads into Lexecon's internal tool-call shape. · `lexecon/adapters/anthropic_adapter.py`

### Runtime

Tool execution boundary and demo entry points.

- [CLI](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/cli.py): entrypoint · Operational commands for key init, demo, and verification. · `lexecon/cli.py`
- [Demo flow](https://github.com/lexicoding-systems/lexecon-demo/blob/main/examples/block_destructive_shell.py): scenario · End-to-end example of interception, audit, and optional execution. · `examples/block_destructive_shell.py`
- [Shell tools](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/tools/shell.py): executor · Actual command execution layer that must only run after allow decisions. · `lexecon/tools/shell.py`
- [Key init](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/cli.py): cli command · Generates local Ed25519 key material under .lexecon/. · `lexecon/cli.py`
- [Verify cmd](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/cli.py): cli command · Runs offline audit verification over the ledger. · `lexecon/cli.py`
- [Demo cmd](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/cli.py): cli command · Executes the demo scenario end to end. · `lexecon/cli.py`

### Policies

YAML policy inputs used by deterministic enforcement.

- [Default policy](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/policies/default_policy.yaml): yaml policy · Built-in policy configuration for normal enforcement. · `lexecon/policies/default_policy.yaml`
- [Demo policy](https://github.com/lexicoding-systems/lexecon-demo/blob/main/lexecon/policies/demo_policy.yaml): yaml policy · Policy variant used by the demo flow. · `lexecon/policies/demo_policy.yaml`

## Connections

- Demo flow → Anthropic adapter: normalize · Example payload is adapted into the internal request form.
- Anthropic adapter → Interceptor: submit · Normalized tool-call payload enters the trust boundary.
- CLI → Key init: init-keys · CLI exposes local key generation.
- CLI → Demo cmd: demo · CLI launches the end-to-end demo flow.
- CLI → Verify cmd: verify · CLI launches offline ledger verification.
- Demo cmd → Anthropic adapter: request · Demo path begins with a provider-style tool call.
- Interceptor → Policy engine: evaluate · Interceptor asks policy for a decision.
- Policy engine → Default policy: load · Default policy provides the baseline rules.
- Policy engine → Demo policy: load · Demo policy is an alternate configuration.
- Policy engine → Decision model: decide · Policy engine returns an allow, block, or escalate result.
- Interceptor → Audit record: shape · Decision is converted into a canonical audit record.
- Audit record → Signer: hash · Record contents are hashed before signing.
- Signer → Ledger: append · Signed record is appended to the JSONL ledger.
- Interceptor → Ledger: write · Interceptor persists the decision trail.
- Interceptor → Shell tools: allow only · Execution proceeds only after an allow decision.
- Ledger → Verifier: replay · Verifier replays ledger entries for integrity checks.
- Signer → Verifier: validate · Verifier checks signature validity.
- CLI → Verifier: run · Verify command invokes offline verification.
- Interceptor → Decision model: gate · Execution is blocked or escalated unless decision is allow.
