# e-ai-model/shadowseed-pro architecture

> Architecture diagram of the GitHub repository e-ai-model/shadowseed-pro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/e-ai-model/shadowseed-pro
- Repository: https://github.com/e-ai-model/shadowseed-pro

## Overview

Shadowseed Pro is a model-independent memory and validation engine, with a local Workbench as its first complete client. The principal workflow prepares authorized context, lets the host or Workbench call a model, then observes the answer to detect and intake candidate seeds, handle recurrence, and route evidence or contradictions through the Validation Gate. Workbench services add chat management, inspection, comparison, feedback, scenarios, and export. The graph follows the README and sampled orchestration/API excerpts; links into unsampled runtime subsystems are limited to documented responsibilities.

Main entry points: [`src/shadowseed/chat.py`](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/chat.py) (Turn orchestration), [`src/shadowseed/workbench/controller.py`](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/workbench/controller.py) (Workbench controller), [`src/shadowseed/engine.py`](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/engine.py) (Engine API), [`src/shadowseed/application/sessions.py`](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/application/sessions.py) (Session service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Engine integration"]
  node_engine["Engine API<br/>[engine.py]"]
  node_chat["Turn orchestration<br/>[chat.py]"]
end

subgraph group_pipeline["SSL pipeline"]
  node_manager["Seed registry<br/>[manager.py]"]
  node_detection["Answer detection<br/>[model_detector.py]"]
  node_intake["Seed intake<br/>[intake.py]"]
  node_recurrence["Recurrence handling<br/>[recurrence.py]"]
  node_gate["Validation Gate<br/>[runtime_adapter.py]"]
  node_lifecycle["Seed lifecycle<br/>[lifecycle.py]"]
  node_auth["Influence authorization<br/>[agent_contract.py]"]
end

subgraph group_workbench["Local Workbench"]
  node_workbench_ui["Workbench UI<br/>[app.py]"]
  node_controller["Workbench controller<br/>[controller.py]"]
  node_prod_controller["Production controls"]
  node_sessions["Session service<br/>[sessions.py]"]
  node_inspection["Inspection<br/>[inspection.py]"]
  node_comparison["Comparison<br/>[comparison.py]"]
  node_exports["Reports and export<br/>[exports.py]"]
  node_feedback["Tester feedback<br/>[feedback.py]"]
  node_scenarios["Scenarios<br/>[scenarios.py]"]
end

subgraph group_runtime["State and providers"]
  node_workspace[("SQLite workspace<br/>[sqlite.py]")]
  node_ollama["Ollama adapter<br/>[ollama_client.py]"]
  node_openai["OpenAI adapter<br/>[openai_client.py]"]
end

subgraph group_retrieval["Retrieval bridge"]
  node_probe["Seed retrieval probe<br/>[retrieval_probe.py]"]
  node_vectorstore["Vector store<br/>[base.py]"]
end

node_host(("Host application"))
node_model(("Language model"))

node_host -->|"prepares turn"| node_engine
node_engine -->|"delegates turns"| node_chat
node_engine -->|"returns context"| node_host
node_host -->|"generates answer"| node_model
node_host -->|"submits answer"| node_engine
node_chat -->|"orchestrates state"| node_manager
node_chat -->|"detects candidates"| node_detection
node_chat -->|"intakes candidates"| node_intake
node_chat -->|"handles recurrence"| node_recurrence
node_chat -->|"routes validation"| node_gate
node_chat -->|"advances lifecycle"| node_lifecycle
node_chat -->|"checks influence"| node_auth
node_workbench_ui -->|"dispatches actions"| node_controller
node_prod_controller -->|"wraps controls"| node_controller
node_controller -->|"manages sessions"| node_sessions
node_controller -->|"requests comparison"| node_comparison
node_controller -->|"requests views"| node_inspection
node_controller -->|"requests exports"| node_exports
node_controller -->|"records feedback"| node_feedback
node_controller -->|"runs scenarios"| node_scenarios
node_sessions -->|"runs turns"| node_chat
node_sessions -->|"persists state"| node_workspace
node_ollama -.->|"requests generation"| node_model
node_openai -.->|"requests generation"| node_model
node_probe -->|"searches vectors"| node_vectorstore
node_auth -->|"checks Gate authority"| node_gate

click node_engine "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/engine.py"
click node_chat "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/chat.py"
click node_workbench_ui "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/workbench/app.py"
click node_controller "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/workbench/controller.py"
click node_prod_controller "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/workbench/production_controller.py"
click node_sessions "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/application/sessions.py"
click node_inspection "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/application/inspection.py"
click node_comparison "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/application/comparison.py"
click node_exports "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/application/exports.py"
click node_feedback "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/application/feedback.py"
click node_scenarios "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/application/scenarios.py"
click node_manager "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/manager.py"
click node_detection "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/detection/model_detector.py"
click node_intake "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/intake.py"
click node_recurrence "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/recurrence.py"
click node_gate "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/gate/runtime_adapter.py"
click node_lifecycle "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/lifecycle.py"
click node_auth "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed_agent/agent_contract.py"
click node_workspace "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/storage/sqlite.py"
click node_ollama "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/adapters/ollama_client.py"
click node_openai "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/adapters/openai_client.py"
click node_probe "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/retrieval_probe.py"
click node_vectorstore "https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/vectorstore/base.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_engine,node_chat toneBlue
class node_manager,node_detection,node_intake,node_recurrence,node_gate,node_lifecycle,node_auth toneAmber
class node_workbench_ui,node_controller,node_prod_controller,node_sessions,node_inspection,node_comparison,node_exports,node_feedback,node_scenarios toneMint
class node_workspace,node_ollama,node_openai toneRose
class node_probe,node_vectorstore,node_host,node_model toneIndigo
```

## Components

### Engine integration

- [Engine API](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/engine.py): `src/shadowseed/engine.py`
- [Turn orchestration](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/chat.py): `src/shadowseed/chat.py`

### SSL pipeline

- [Seed registry](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/manager.py): `src/shadowseed/manager.py`
- [Answer detection](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/detection/model_detector.py): `src/shadowseed/detection/model_detector.py`
- [Seed intake](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/intake.py): `src/shadowseed/intake.py`
- [Recurrence handling](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/recurrence.py): `src/shadowseed/recurrence.py`
- [Validation Gate](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/gate/runtime_adapter.py): `src/shadowseed/gate/runtime_adapter.py`
- [Seed lifecycle](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/lifecycle.py): `src/shadowseed/lifecycle.py`
- [Influence authorization](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed_agent/agent_contract.py): `src/shadowseed_agent/agent_contract.py`

### Local Workbench

- [Workbench UI](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/workbench/app.py): `src/shadowseed/workbench/app.py`
- [Workbench controller](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/workbench/controller.py): `src/shadowseed/workbench/controller.py`
- [Production controls](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/workbench/production_controller.py): `src/shadowseed/workbench/production_controller.py`
- [Session service](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/application/sessions.py): `src/shadowseed/application/sessions.py`
- [Inspection](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/application/inspection.py): `src/shadowseed/application/inspection.py`
- [Comparison](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/application/comparison.py): `src/shadowseed/application/comparison.py`
- [Reports and export](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/application/exports.py): `src/shadowseed/application/exports.py`
- [Tester feedback](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/application/feedback.py): `src/shadowseed/application/feedback.py`
- [Scenarios](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/application/scenarios.py): `src/shadowseed/application/scenarios.py`

### State and providers

- [SQLite workspace](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/storage/sqlite.py): `src/shadowseed/storage/sqlite.py`
- [Ollama adapter](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/adapters/ollama_client.py): `src/shadowseed/adapters/ollama_client.py`
- [OpenAI adapter](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/adapters/openai_client.py): `src/shadowseed/adapters/openai_client.py`

### Retrieval bridge

- [Seed retrieval probe](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/retrieval_probe.py): `src/shadowseed/retrieval_probe.py`
- [Vector store](https://github.com/e-ai-model/shadowseed-pro/blob/main/src/shadowseed/vectorstore/base.py): `src/shadowseed/vectorstore/base.py`

### Other components

- **Host application**
- **Language model**

## Connections

- Host application → Engine API: prepares turn
- Engine API → Turn orchestration: delegates turns
- Engine API → Host application: returns context
- Host application → Language model: generates answer
- Host application → Engine API: submits answer
- Turn orchestration → Seed registry: orchestrates state
- Turn orchestration → Answer detection: detects candidates
- Turn orchestration → Seed intake: intakes candidates
- Turn orchestration → Recurrence handling: handles recurrence
- Turn orchestration → Validation Gate: routes validation
- Turn orchestration → Seed lifecycle: advances lifecycle
- Turn orchestration → Influence authorization: checks influence
- Workbench UI → Workbench controller: dispatches actions
- Production controls → Workbench controller: wraps controls
- Workbench controller → Session service: manages sessions
- Workbench controller → Comparison: requests comparison
- Workbench controller → Inspection: requests views
- Workbench controller → Reports and export: requests exports
- Workbench controller → Tester feedback: records feedback
- Workbench controller → Scenarios: runs scenarios
- Session service → Turn orchestration: runs turns
- Session service → SQLite workspace: persists state
- Ollama adapter → Language model: requests generation
- OpenAI adapter → Language model: requests generation
- Seed retrieval probe → Vector store: searches vectors
- Influence authorization → Validation Gate: checks Gate authority