# darksleep1983/living-software-organism architecture

> Architecture diagram of the GitHub repository darksleep1983/living-software-organism, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/darksleep1983/living-software-organism
- Repository: https://github.com/darksleep1983/living-software-organism

## Overview

Living Software Organism (LSO) combines Project Corpus, a standalone project-identity and continuity substrate, with an organism layer that derives bounded health and recovery evidence. The principal workflow is a developer invoking the LSO CLI in a project to inspect status/context and plan or rehearse recovery; Corpus supplies project-owned records, while organism evidence does not grant authority. The graph preserves documented retrieval, governance, migration, transaction, and experimental capabilities. Some subsystem connections are omitted because their callers were not visible in the sampled source.

Main entry points: [`components/organism/cli.js`](https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/cli.js) (LSO CLI), [`components/project-corpus/src/project_corpus/transactions.py`](https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/transactions.py) (Safe Transactions), [`components/organism/src/corpus-adapter.js`](https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/src/corpus-adapter.js) (Corpus Adapter), [`components/project-corpus/src/project_corpus/context/index.py`](https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/context/index.py) (Context Index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_organism["Organism Evidence"]
  node_lso_cli["LSO CLI<br/>[cli.js]"]
  node_organism_api["Organism API<br/>[index.js]"]
  node_context_runtime["Context Runtime<br/>[context.js]"]
  node_corpus_adapter["Corpus Adapter<br/>[corpus-adapter.js]"]
  node_health["Health Assessment<br/>[homeostasis.js]"]
  node_recovery["Recovery Evidence<br/>[recovery.js]"]
  node_history["History Evidence<br/>[history.js]"]
  node_repair["Repair Evidence<br/>[repair.js]"]
  node_experimental["Experimental Systems<br/>[experimental.js]"]
end

subgraph group_corpus["Project Corpus"]
  node_corpus_cli["Corpus CLI<br/>[cli.py]"]
  node_mcp["MCP Transport<br/>[mcp_stdio.py]"]
  node_discovery["Project Discovery<br/>[discovery.py]"]
  node_migration["Corpus Migration<br/>[migration.py]"]
  node_doctor["Corpus Diagnostics<br/>[doctor.py]"]
end

subgraph group_context["Context Retrieval"]
  node_context_index["Context Index<br/>[index.py]"]
  node_context_retrieval["Context Retrieval<br/>[retrieval.py]"]
  node_context_compiler["Context Compiler<br/>[compiler.py]"]
  node_context_eval["Context Evaluation<br/>[eval.py]"]
end

subgraph group_governance["Safety and Changes"]
  node_authority["Authority Decisions<br/>[authority.py]"]
  node_policy_trust["Policy and Trust<br/>[policy.py]"]
  node_transactions["Safe Transactions<br/>[transactions.py]"]
  node_platform["Filesystem Backend<br/>[factory.py]"]
  node_security_scan["Security Scan<br/>[security_scan.py]"]
end

node_developer(("Developer"))
node_project[("Adopted Project")]
node_git(("Declared Git Origin"))

node_developer -->|"invokes"| node_lso_cli
node_lso_cli -->|"inspects project"| node_project
node_lso_cli -.->|"verifies origin"| node_git
node_context_runtime -->|"reads state"| node_corpus_adapter
node_corpus_adapter -->|"reads corpus"| node_project
node_context_retrieval -->|"ranks indexed items"| node_context_index
node_policy_trust -->|"supplies grants"| node_authority
node_transactions -->|"checks authority"| node_authority
node_transactions -->|"publishes changes"| node_platform
node_context_index -->|"collects project records"| node_project

click node_lso_cli "https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/cli.js"
click node_organism_api "https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/src/index.js"
click node_context_runtime "https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/src/context.js"
click node_corpus_adapter "https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/src/corpus-adapter.js"
click node_health "https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/src/homeostasis.js"
click node_recovery "https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/src/recovery.js"
click node_history "https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/src/history.js"
click node_repair "https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/src/repair.js"
click node_experimental "https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/src/experimental.js"
click node_corpus_cli "https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/cli.py"
click node_mcp "https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/mcp_stdio.py"
click node_discovery "https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/discovery.py"
click node_migration "https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/migration.py"
click node_doctor "https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/doctor.py"
click node_context_index "https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/context/index.py"
click node_context_retrieval "https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/context/retrieval.py"
click node_context_compiler "https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/context/compiler.py"
click node_context_eval "https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/context/eval.py"
click node_authority "https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/authority.py"
click node_policy_trust "https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/policy.py"
click node_transactions "https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/transactions.py"
click node_platform "https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/platform/factory.py"
click node_security_scan "https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/security_scan.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_lso_cli,node_organism_api,node_context_runtime,node_corpus_adapter,node_health,node_recovery,node_history,node_repair,node_experimental toneBlue
class node_corpus_cli,node_mcp,node_discovery,node_migration,node_doctor,node_project toneAmber
class node_context_index,node_context_retrieval,node_context_compiler,node_context_eval toneMint
class node_authority,node_policy_trust,node_transactions,node_platform,node_security_scan toneRose
class node_developer,node_git toneIndigo
```

## Components

### Organism Evidence

- [LSO CLI](https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/cli.js): `components/organism/cli.js`
- [Organism API](https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/src/index.js): `components/organism/src/index.js`
- [Context Runtime](https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/src/context.js): `components/organism/src/context.js`
- [Corpus Adapter](https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/src/corpus-adapter.js): `components/organism/src/corpus-adapter.js`
- [Health Assessment](https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/src/homeostasis.js): `components/organism/src/homeostasis.js`
- [Recovery Evidence](https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/src/recovery.js): `components/organism/src/recovery.js`
- [History Evidence](https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/src/history.js): `components/organism/src/history.js`
- [Repair Evidence](https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/src/repair.js): `components/organism/src/repair.js`
- [Experimental Systems](https://github.com/darksleep1983/living-software-organism/blob/main/components/organism/src/experimental.js): `components/organism/src/experimental.js`

### Project Corpus

- [Corpus CLI](https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/cli.py): `components/project-corpus/src/project_corpus/cli.py`
- [MCP Transport](https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/mcp_stdio.py): `components/project-corpus/src/project_corpus/mcp_stdio.py`
- [Project Discovery](https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/discovery.py): `components/project-corpus/src/project_corpus/discovery.py`
- [Corpus Migration](https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/migration.py): `components/project-corpus/src/project_corpus/migration.py`
- [Corpus Diagnostics](https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/doctor.py): `components/project-corpus/src/project_corpus/doctor.py`

### Context Retrieval

- [Context Index](https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/context/index.py): `components/project-corpus/src/project_corpus/context/index.py`
- [Context Retrieval](https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/context/retrieval.py): `components/project-corpus/src/project_corpus/context/retrieval.py`
- [Context Compiler](https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/context/compiler.py): `components/project-corpus/src/project_corpus/context/compiler.py`
- [Context Evaluation](https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/context/eval.py): `components/project-corpus/src/project_corpus/context/eval.py`

### Safety and Changes

- [Authority Decisions](https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/authority.py): `components/project-corpus/src/project_corpus/authority.py`
- [Policy and Trust](https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/policy.py): `components/project-corpus/src/project_corpus/policy.py`
- [Safe Transactions](https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/transactions.py): `components/project-corpus/src/project_corpus/transactions.py`
- [Filesystem Backend](https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/platform/factory.py): `components/project-corpus/src/project_corpus/platform/factory.py`
- [Security Scan](https://github.com/darksleep1983/living-software-organism/blob/main/components/project-corpus/src/project_corpus/security_scan.py): `components/project-corpus/src/project_corpus/security_scan.py`

### Other components

- **Developer**
- **Adopted Project**
- **Declared Git Origin**

## Connections

- Developer → LSO CLI: invokes
- LSO CLI → Adopted Project: inspects project
- LSO CLI → Declared Git Origin: verifies origin
- Context Runtime → Corpus Adapter: reads state
- Corpus Adapter → Adopted Project: reads corpus
- Context Retrieval → Context Index: ranks indexed items
- Policy and Trust → Authority Decisions: supplies grants
- Safe Transactions → Authority Decisions: checks authority
- Safe Transactions → Filesystem Backend: publishes changes
- Context Index → Adopted Project: collects project records