# joeydd032995-pixel/yeslumby architecture

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

- Interactive diagram: https://gitdiagram.com/joeydd032995-pixel/yeslumby
- Repository: https://github.com/joeydd032995-pixel/yeslumby

## Overview

Meta-Ecosystem Runtime compiles versioned Architecture Genomes into executable AI organizations. The primary workflow is to select a genome, execute a durable run, stream its progress and result, then assess and evolve genome versions through mutation, comparison, breeding, and promotion. The runtime separates run-scoped context from ecosystem knowledge and evolutionary memory. The README documents benchmarking as a major capability, but the provided tree contains no benchmark package, so it is not expanded into an implementation node. Edges are limited to explicit README statements and shown source references; several UI and evolution relationships are documented rather than excerpted in implementation detail.

Main entry points: [`packages/runtime/src/machine.ts`](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/machine.ts) (Round machine), [`packages/genome/src/schema.ts`](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/genome/src/schema.ts) (Genome schema), [`packages/evolution/src/evolve.ts`](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/evolution/src/evolve.ts) (Evolution engine), [`packages/runtime/src/orchestrator.ts`](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/orchestrator.ts) (Run orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_web_surface["Ecosystem UI<br/>[page.tsx]"]
  node_evolution_ui["Evolution UI<br/>[page.tsx]"]
  node_run_route["Run stream route<br/>[route.ts]"]
end

subgraph group_genomes["Genome modeling"]
  node_genome_model["Genome schema<br/>[schema.ts]"]
  node_genome_validation["Genome validation<br/>[validate.ts]"]
  node_genome_patches["Genome patches<br/>[patches.ts]"]
  node_templates["Genome templates<br/>[templates.ts]"]
end

subgraph group_execution["Run execution"]
  node_orchestrator["Run orchestrator<br/>[orchestrator.ts]"]
  node_round_machine["Round machine<br/>[machine.ts]"]
  node_run_journal["Durable journal<br/>[journal.ts]"]
  node_context_stage["Context stage<br/>[context.ts]"]
  node_proposal_stage["Proposal stage<br/>[proposals.ts]"]
  node_challenge_stage["Challenge stage<br/>[challenges.ts]"]
  node_falsify_stage["Falsification stage<br/>[falsification.ts]"]
  node_synthesis_stage["Synthesis stage<br/>[synthesis.ts]"]
  node_watcher_stage["Watcher evaluation<br/>[watcher.ts]"]
end

subgraph group_learning["Memory and evolution"]
  node_memory["Knowledge memory<br/>[recall.ts]"]
  node_consolidation["Memory consolidation<br/>[consolidate.ts]"]
  node_evolution["Evolution engine<br/>[evolve.ts]"]
  node_mutation["Mutation engine<br/>[mutate.ts]"]
  node_breeding["Genome breeding<br/>[breed.ts]"]
  node_recommendation["Genome recommendation<br/>[recommend.ts]"]
end

subgraph group_persistence["Persistence and providers"]
  node_database[("Postgres stores<br/>[runs.ts]")]
  node_gateway["Model gateway<br/>[gateway.ts]"]
  node_simulator["Deterministic provider<br/>[simulator.ts]"]
  node_openrouter["OpenRouter provider<br/>[openrouter.ts]"]
  node_ai_gateway["AI Gateway provider<br/>[ai-gateway.ts]"]
end

node_user(("Operator"))

node_user -->|"configures ecosystem"| node_web_surface
node_user -->|"reviews evolution"| node_evolution_ui
node_web_surface -->|"loads genome"| node_genome_model
node_evolution_ui -->|"views versions"| node_genome_model
node_run_route -->|"loads run"| node_database
node_run_route -->|"parses genome"| node_genome_model
node_run_route -->|"starts run"| node_orchestrator
node_orchestrator -->|"executes rounds"| node_round_machine
node_round_machine -->|"dispatches stage"| node_context_stage
node_round_machine -->|"dispatches stage"| node_proposal_stage
node_round_machine -->|"dispatches stage"| node_challenge_stage
node_round_machine -->|"dispatches stage"| node_falsify_stage
node_round_machine -->|"dispatches stage"| node_synthesis_stage
node_round_machine -->|"dispatches stage"| node_watcher_stage
node_context_stage -->|"recalls knowledge"| node_memory
node_orchestrator -->|"finishes run"| node_database
node_round_machine -->|"replays steps"| node_run_journal
node_context_stage -->|"persists stage"| node_run_journal
node_evolution -->|"proposes mutation"| node_mutation
node_evolution -->|"runs generation"| node_orchestrator
node_evolution -->|"records lessons"| node_consolidation
node_evolution -->|"promotes version"| node_database
node_mutation -->|"applies patches"| node_genome_patches
node_mutation -->|"uses evolutionary memory"| node_memory
node_breeding -->|"combines genomes"| node_genome_model
node_recommendation -.->|"uses learned structures"| node_memory
node_gateway -->|"selects provider"| node_simulator
node_gateway -->|"selects provider"| node_openrouter
node_gateway -->|"selects provider"| node_ai_gateway
node_templates -->|"builds genome"| node_genome_model
node_genome_validation -->|"validates genome"| node_genome_model

click node_web_surface "https://github.com/joeydd032995-pixel/yeslumby/blob/main/apps/web/src/app/e/%5Bid%5D/page.tsx"
click node_evolution_ui "https://github.com/joeydd032995-pixel/yeslumby/blob/main/apps/web/src/app/e/%5Bid%5D/evolution/page.tsx"
click node_run_route "https://github.com/joeydd032995-pixel/yeslumby/blob/main/apps/web/src/app/api/runs/%5BrunId%5D/stream/route.ts"
click node_genome_model "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/genome/src/schema.ts"
click node_genome_validation "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/genome/src/validate.ts"
click node_genome_patches "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/genome/src/patches.ts"
click node_templates "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/genome/src/templates.ts"
click node_orchestrator "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/orchestrator.ts"
click node_round_machine "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/machine.ts"
click node_run_journal "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/journal.ts"
click node_context_stage "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/stages/context.ts"
click node_proposal_stage "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/stages/proposals.ts"
click node_challenge_stage "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/stages/challenges.ts"
click node_falsify_stage "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/stages/falsification.ts"
click node_synthesis_stage "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/stages/synthesis.ts"
click node_watcher_stage "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/stages/watcher.ts"
click node_memory "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/memory/src/recall.ts"
click node_consolidation "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/memory/src/consolidate.ts"
click node_evolution "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/evolution/src/evolve.ts"
click node_mutation "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/evolution/src/mutate.ts"
click node_breeding "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/evolution/src/breed.ts"
click node_recommendation "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/evolution/src/recommend.ts"
click node_database "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/db/src/repositories/runs.ts"
click node_gateway "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/gateway/src/gateway.ts"
click node_simulator "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/gateway/src/simulator.ts"
click node_openrouter "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/gateway/src/openrouter.ts"
click node_ai_gateway "https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/gateway/src/ai-gateway.ts"

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_web_surface,node_evolution_ui,node_run_route toneBlue
class node_genome_model,node_genome_validation,node_genome_patches,node_templates toneAmber
class node_orchestrator,node_round_machine,node_run_journal,node_context_stage,node_proposal_stage,node_challenge_stage,node_falsify_stage,node_synthesis_stage,node_watcher_stage toneMint
class node_memory,node_consolidation,node_evolution,node_mutation,node_breeding,node_recommendation toneRose
class node_database,node_gateway,node_simulator,node_openrouter,node_ai_gateway,node_user toneIndigo
```

## Components

### Web application

- [Ecosystem UI](https://github.com/joeydd032995-pixel/yeslumby/blob/main/apps/web/src/app/e/%5Bid%5D/page.tsx): `apps/web/src/app/e/[id]/page.tsx`
- [Evolution UI](https://github.com/joeydd032995-pixel/yeslumby/blob/main/apps/web/src/app/e/%5Bid%5D/evolution/page.tsx): `apps/web/src/app/e/[id]/evolution/page.tsx`
- [Run stream route](https://github.com/joeydd032995-pixel/yeslumby/blob/main/apps/web/src/app/api/runs/%5BrunId%5D/stream/route.ts): `apps/web/src/app/api/runs/[runId]/stream/route.ts`

### Genome modeling

- [Genome schema](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/genome/src/schema.ts): `packages/genome/src/schema.ts`
- [Genome validation](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/genome/src/validate.ts): `packages/genome/src/validate.ts`
- [Genome patches](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/genome/src/patches.ts): `packages/genome/src/patches.ts`
- [Genome templates](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/genome/src/templates.ts): `packages/genome/src/templates.ts`

### Run execution

- [Run orchestrator](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/orchestrator.ts): `packages/runtime/src/orchestrator.ts`
- [Round machine](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/machine.ts): `packages/runtime/src/machine.ts`
- [Durable journal](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/journal.ts): `packages/runtime/src/journal.ts`
- [Context stage](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/stages/context.ts): `packages/runtime/src/stages/context.ts`
- [Proposal stage](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/stages/proposals.ts): `packages/runtime/src/stages/proposals.ts`
- [Challenge stage](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/stages/challenges.ts): `packages/runtime/src/stages/challenges.ts`
- [Falsification stage](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/stages/falsification.ts): `packages/runtime/src/stages/falsification.ts`
- [Synthesis stage](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/stages/synthesis.ts): `packages/runtime/src/stages/synthesis.ts`
- [Watcher evaluation](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/runtime/src/stages/watcher.ts): `packages/runtime/src/stages/watcher.ts`

### Memory and evolution

- [Knowledge memory](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/memory/src/recall.ts): `packages/memory/src/recall.ts`
- [Memory consolidation](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/memory/src/consolidate.ts): `packages/memory/src/consolidate.ts`
- [Evolution engine](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/evolution/src/evolve.ts): `packages/evolution/src/evolve.ts`
- [Mutation engine](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/evolution/src/mutate.ts): `packages/evolution/src/mutate.ts`
- [Genome breeding](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/evolution/src/breed.ts): `packages/evolution/src/breed.ts`
- [Genome recommendation](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/evolution/src/recommend.ts): `packages/evolution/src/recommend.ts`

### Persistence and providers

- [Postgres stores](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/db/src/repositories/runs.ts): `packages/db/src/repositories/runs.ts`
- [Model gateway](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/gateway/src/gateway.ts): `packages/gateway/src/gateway.ts`
- [Deterministic provider](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/gateway/src/simulator.ts): `packages/gateway/src/simulator.ts`
- [OpenRouter provider](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/gateway/src/openrouter.ts): `packages/gateway/src/openrouter.ts`
- [AI Gateway provider](https://github.com/joeydd032995-pixel/yeslumby/blob/main/packages/gateway/src/ai-gateway.ts): `packages/gateway/src/ai-gateway.ts`

### Other components

- **Operator**

## Connections

- Operator → Ecosystem UI: configures ecosystem (evidence: `apps/web/src/app/e/[id]/page.tsx`)
- Operator → Evolution UI: reviews evolution (evidence: `apps/web/src/app/e/[id]/evolution/page.tsx`)
- Ecosystem UI → Genome schema: loads genome (evidence: `apps/web/src/app/e/[id]/page.tsx`)
- Evolution UI → Genome schema: views versions (evidence: `apps/web/src/app/e/[id]/evolution/page.tsx`)
- Run stream route → Postgres stores: loads run (evidence: `apps/web/src/app/api/runs/[runId]/stream/route.ts`)
- Run stream route → Genome schema: parses genome (evidence: `apps/web/src/app/api/runs/[runId]/stream/route.ts`)
- Run stream route → Run orchestrator: starts run (evidence: `apps/web/src/app/api/runs/[runId]/stream/route.ts`)
- Run orchestrator → Round machine: executes rounds (evidence: `packages/runtime/src/orchestrator.ts`)
- Round machine → Context stage: dispatches stage (evidence: `packages/runtime/src/machine.ts`)
- Round machine → Proposal stage: dispatches stage (evidence: `packages/runtime/src/machine.ts`)
- Round machine → Challenge stage: dispatches stage (evidence: `packages/runtime/src/machine.ts`)
- Round machine → Falsification stage: dispatches stage (evidence: `packages/runtime/src/machine.ts`)
- Round machine → Synthesis stage: dispatches stage (evidence: `packages/runtime/src/machine.ts`)
- Round machine → Watcher evaluation: dispatches stage (evidence: `packages/runtime/src/machine.ts`)
- Context stage → Knowledge memory: recalls knowledge (evidence: `packages/runtime/src/stages/context.ts`)
- Run orchestrator → Postgres stores: finishes run (evidence: `packages/runtime/src/orchestrator.ts`)
- Round machine → Durable journal: replays steps (evidence: `packages/runtime/src/machine.ts`)
- Context stage → Durable journal: persists stage (evidence: `packages/runtime/src/stages/context.ts`)
- Evolution engine → Mutation engine: proposes mutation (evidence: `packages/evolution/src/evolve.ts`)
- Evolution engine → Run orchestrator: runs generation (evidence: `packages/evolution/src/evolve.ts`)
- Evolution engine → Memory consolidation: records lessons (evidence: `packages/evolution/src/evolve.ts`)
- Evolution engine → Postgres stores: promotes version (evidence: `packages/evolution/src/evolve.ts`)
- Mutation engine → Genome patches: applies patches (evidence: `packages/evolution/src/mutate.ts`)
- Mutation engine → Knowledge memory: uses evolutionary memory (evidence: `packages/evolution/src/mutate.ts`)
- Genome breeding → Genome schema: combines genomes (evidence: `packages/evolution/src/breed.ts`)
- Genome recommendation → Knowledge memory: uses learned structures
- Model gateway → Deterministic provider: selects provider (evidence: `packages/gateway/src/index.ts`)
- Model gateway → OpenRouter provider: selects provider
- Model gateway → AI Gateway provider: selects provider
- Genome templates → Genome schema: builds genome (evidence: `packages/genome/src/templates.ts`)
- Genome validation → Genome schema: validates genome (evidence: `packages/genome/src/validate.ts`)
