# sipyourdrink-ltd/bernstein architecture

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

- Interactive diagram: https://gitdiagram.com/sipyourdrink-ltd/bernstein
- Repository: https://github.com/sipyourdrink-ltd/bernstein

## Overview

Bernstein is an AI-agent governance layer: users define policy and run plans, then a deterministic scheduler coordinates agents, gates deliverables, and records evidence for later verification. The graph also preserves documented product branches for task admission, tracker-based handoffs, compliance evidence, integrations, and the web dashboard. README statements support the high-level workflow; unsampled subsystems are represented at their exact enclosing directories, and their internal calls are not inferred.

Main entry points: [`src/bernstein/core/orchestration/tick_pipeline.py`](https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/core/orchestration/tick_pipeline.py) (Deterministic scheduler), [`src/bernstein/core/security/audit_chain.py`](https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/core/security/audit_chain.py) (Audit chain), [`src/bernstein/core/persistence/work_ledger.py`](https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/core/persistence/work_ledger.py) (Work ledger), [`src/bernstein/core/admission`](https://github.com/sipyourdrink-ltd/bernstein/tree/main/src/bernstein/core/admission) (Admission control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Run execution"]
  node_scheduler["Deterministic scheduler<br/>[tick_pipeline.py]"]
  node_tracker["Tracker handoffs"]
end

subgraph group_governance["Governance and evidence"]
  node_quality["Quality gates<br/>[quality_gates.py]"]
  node_policy["Policy engine<br/>[policy_engine.py]"]
  node_admission["Admission control"]
  node_audit[("Audit chain<br/>[audit_chain.py]")]
  node_lineage["Lineage tracking"]
  node_verification["Offline verification"]
  node_compliance["Compliance evidence"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["Bernstein CLI<br/>[main.py]"]
  node_web["Web dashboard<br/>[App.tsx]"]
  node_tasks["Task views<br/>[Tasks.tsx]"]
end

subgraph group_ecosystem["Integrations and agents"]
  node_adapters["Agent adapters"]
  node_sdk["Python SDK<br/>[client.py]"]
  node_jira["Jira webhook<br/>[app.py]"]
end

subgraph group_data["Data services"]
  node_workledger[("Work ledger<br/>[work_ledger.py]")]
  node_datasources["Data sources<br/>[engine.py]"]
end

node_user(("Operator"))

node_user -->|"defines and runs"| node_cli
node_cli -->|"runs plans"| node_scheduler
node_scheduler -->|"dispatches agents"| node_adapters
node_scheduler -->|"gates outputs"| node_quality
node_scheduler -->|"records run"| node_audit
node_scheduler -->|"records lineage"| node_lineage
node_audit -->|"verifies offline"| node_verification
node_scheduler -->|"claims backlog"| node_workledger
node_user -->|"configures handoffs"| node_tracker
node_admission -->|"projects ledger"| node_workledger
node_admission -.->|"optional audit"| node_audit
node_user -->|"views operations"| node_web
node_web -->|"routes tasks"| node_tasks
node_sdk -.->|"submits task requests"| node_user
node_jira -->|"uses task API"| node_sdk
node_datasources -.->|"reads data"| node_workledger
node_compliance -.->|"uses evidence"| node_audit
node_policy -.->|"governs execution"| node_scheduler

click node_cli "https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/cli/main.py"
click node_scheduler "https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/core/orchestration/tick_pipeline.py"
click node_tracker "https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/core/orchestration/tracker_pipeline.py"
click node_adapters "https://github.com/sipyourdrink-ltd/bernstein/tree/main/src/bernstein/adapters"
click node_quality "https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/core/quality/quality_gates.py"
click node_policy "https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/core/security/policy_engine.py"
click node_admission "https://github.com/sipyourdrink-ltd/bernstein/tree/main/src/bernstein/core/admission"
click node_audit "https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/core/security/audit_chain.py"
click node_lineage "https://github.com/sipyourdrink-ltd/bernstein/tree/main/src/bernstein/core/lineage"
click node_verification "https://github.com/sipyourdrink-ltd/bernstein/tree/main/verify_cli/bernstein_verify"
click node_workledger "https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/core/persistence/work_ledger.py"
click node_datasources "https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/core/datasources/engine.py"
click node_compliance "https://github.com/sipyourdrink-ltd/bernstein/tree/main/src/bernstein/compliance"
click node_sdk "https://github.com/sipyourdrink-ltd/bernstein/blob/main/sdk/python/src/bernstein_sdk/client.py"
click node_jira "https://github.com/sipyourdrink-ltd/bernstein/blob/main/integrations/jira_webhook/app.py"
click node_web "https://github.com/sipyourdrink-ltd/bernstein/blob/main/web/src/App.tsx"
click node_tasks "https://github.com/sipyourdrink-ltd/bernstein/blob/main/web/src/routes/Tasks.tsx"

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_scheduler,node_tracker toneBlue
class node_quality,node_policy,node_admission,node_audit,node_lineage,node_verification,node_compliance toneAmber
class node_cli,node_web,node_tasks toneMint
class node_adapters,node_sdk,node_jira toneRose
class node_workledger,node_datasources,node_user toneIndigo
```

## Components

### Run execution

- [Deterministic scheduler](https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/core/orchestration/tick_pipeline.py): `src/bernstein/core/orchestration/tick_pipeline.py`
- [Tracker handoffs](https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/core/orchestration/tracker_pipeline.py): `src/bernstein/core/orchestration/tracker_pipeline.py`

### Governance and evidence

- [Quality gates](https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/core/quality/quality_gates.py): `src/bernstein/core/quality/quality_gates.py`
- [Policy engine](https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/core/security/policy_engine.py): `src/bernstein/core/security/policy_engine.py`
- [Admission control](https://github.com/sipyourdrink-ltd/bernstein/tree/main/src/bernstein/core/admission): `src/bernstein/core/admission`
- [Audit chain](https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/core/security/audit_chain.py): `src/bernstein/core/security/audit_chain.py`
- [Lineage tracking](https://github.com/sipyourdrink-ltd/bernstein/tree/main/src/bernstein/core/lineage): `src/bernstein/core/lineage`
- [Offline verification](https://github.com/sipyourdrink-ltd/bernstein/tree/main/verify_cli/bernstein_verify): `verify_cli/bernstein_verify`
- [Compliance evidence](https://github.com/sipyourdrink-ltd/bernstein/tree/main/src/bernstein/compliance): `src/bernstein/compliance`

### User interfaces

- [Bernstein CLI](https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/cli/main.py): `src/bernstein/cli/main.py`
- [Web dashboard](https://github.com/sipyourdrink-ltd/bernstein/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Task views](https://github.com/sipyourdrink-ltd/bernstein/blob/main/web/src/routes/Tasks.tsx): `web/src/routes/Tasks.tsx`

### Integrations and agents

- [Agent adapters](https://github.com/sipyourdrink-ltd/bernstein/tree/main/src/bernstein/adapters): `src/bernstein/adapters`
- [Python SDK](https://github.com/sipyourdrink-ltd/bernstein/blob/main/sdk/python/src/bernstein_sdk/client.py): `sdk/python/src/bernstein_sdk/client.py`
- [Jira webhook](https://github.com/sipyourdrink-ltd/bernstein/blob/main/integrations/jira_webhook/app.py): `integrations/jira_webhook/app.py`

### Data services

- [Work ledger](https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/core/persistence/work_ledger.py): `src/bernstein/core/persistence/work_ledger.py`
- [Data sources](https://github.com/sipyourdrink-ltd/bernstein/blob/main/src/bernstein/core/datasources/engine.py): `src/bernstein/core/datasources/engine.py`

### Other components

- **Operator**

## Connections

- Operator → Bernstein CLI: defines and runs (evidence: `README.md`)
- Bernstein CLI → Deterministic scheduler: runs plans (evidence: `README.md`)
- Deterministic scheduler → Agent adapters: dispatches agents (evidence: `README.md`)
- Deterministic scheduler → Quality gates: gates outputs (evidence: `README.md`)
- Deterministic scheduler → Audit chain: records run (evidence: `README.md`)
- Deterministic scheduler → Lineage tracking: records lineage (evidence: `README.md`)
- Audit chain → Offline verification: verifies offline (evidence: `README.md`)
- Deterministic scheduler → Work ledger: claims backlog (evidence: `README.md`)
- Operator → Tracker handoffs: configures handoffs
- Admission control → Work ledger: projects ledger (evidence: `src/bernstein/core/admission/ledger.py`)
- Admission control → Audit chain: optional audit (evidence: `src/bernstein/core/admission/engine.py`)
- Operator → Web dashboard: views operations (evidence: `README.md`)
- Web dashboard → Task views: routes tasks (evidence: `web/src/App.tsx`)
- Python SDK → Operator: submits task requests (evidence: `sdk/python/src/bernstein_sdk/client.py`)
- Jira webhook → Python SDK: uses task API (evidence: `integrations/jira_webhook/app.py`)
- Data sources → Work ledger: reads data
- Compliance evidence → Audit chain: uses evidence
- Policy engine → Deterministic scheduler: governs execution
