# v1b3x0r/mds architecture

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

- Interactive diagram: https://gitdiagram.com/v1b3x0r/mds
- Repository: https://github.com/v1b3x0r/mds

## Overview

MDS is a deterministic TypeScript runtime for small semantic worlds. Its central workflow is: an application supplies context and authored `.mdm` materials; the World turns that input into entity and world state, where behavior can produce speech, logs, and effects. The graph preserves the README’s major capabilities—ontology, physics, cognition, communication, linguistics, resources, networking, rendering, and persistence. Several feature connections are documented but their internal dispatch is not shown in the excerpts, so those links are omitted rather than inferred.

Main entry points: [`src/6-world/container.ts`](https://github.com/v1b3x0r/mds/blob/main/src/6-world/container.ts) (World Container), [`src/0-foundation/entity.ts`](https://github.com/v1b3x0r/mds/blob/main/src/0-foundation/entity.ts) (Entities), [`src/0-foundation/engine.ts`](https://github.com/v1b3x0r/mds/blob/main/src/0-foundation/engine.ts) (Simulation Engine), [`src/7-interface/io/mdm-parser.ts`](https://github.com/v1b3x0r/mds/blob/main/src/7-interface/io/mdm-parser.ts) (MDM Materials)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["World Runtime"]
  node_world["World Container<br/>[container.ts]"]
  node_engine["Simulation Engine<br/>[engine.ts]"]
end

subgraph group_state["Entity State"]
  node_entity["Entities<br/>[entity.ts]"]
  node_ontology["Memory, Emotion, Intent"]
  node_relationships["Relationships"]
end

subgraph group_behavior["World Capabilities"]
  node_physics["Physics and Weather"]
  node_learning["Learning and Skills"]
  node_worldmind["Collective Intelligence"]
  node_dialogue["Dialogue<br/>[manager.ts]"]
  node_language["Language Generation<br/>[generator.ts]"]
  node_semantics["Semantic Similarity<br/>[embeddings.ts]"]
  node_network["Peer Network"]
  node_resources["Resource Fields<br/>[field.ts]"]
  node_linguistics["Proto-language"]
end

subgraph group_interfaces["Inputs and Outputs"]
  node_materials["MDM Materials<br/>[mdm-parser.ts]"]
  node_context["Context Providers"]
  node_llm["Optional LLM Bridge<br/>[llmAdapter.ts]"]
  node_render["Render Adapters"]
  node_worldfile["Worldfile Persistence<br/>[worldfile.ts]"]
  node_logger["World Logger<br/>[logger.ts]"]
end

node_app(("Host Application"))

node_app -->|"feeds context"| node_world
node_app -->|"spawns materials"| node_world
node_materials -->|"defines responses"| node_world
node_context -->|"supplies context"| node_world
node_world -->|"manages state"| node_entity
node_world -->|"uses logger"| node_logger
node_engine -->|"spawns"| node_entity
node_world -.->|"produces speech"| node_dialogue
node_world -.->|"generates utterances"| node_linguistics
node_world -.->|"renders world"| node_render
node_world -.->|"saves state"| node_worldfile
node_world -.->|"applies effects"| node_physics
node_world -.->|"updates state"| node_ontology
node_world -.->|"updates bonds"| node_relationships
node_world -.->|"supports learning"| node_learning
node_world -.->|"supports collectives"| node_worldmind
node_world -.->|"models resources"| node_resources
node_world -.->|"supports peers"| node_network
node_world -.->|"uses similarity"| node_semantics
node_world -.->|"requests generation"| node_llm

click node_world "https://github.com/v1b3x0r/mds/blob/main/src/6-world/container.ts"
click node_engine "https://github.com/v1b3x0r/mds/blob/main/src/0-foundation/engine.ts"
click node_entity "https://github.com/v1b3x0r/mds/blob/main/src/0-foundation/entity.ts"
click node_ontology "https://github.com/v1b3x0r/mds/tree/main/src/1-ontology"
click node_relationships "https://github.com/v1b3x0r/mds/tree/main/src/1-ontology/relationships"
click node_physics "https://github.com/v1b3x0r/mds/tree/main/src/2-physics"
click node_learning "https://github.com/v1b3x0r/mds/tree/main/src/3-cognition"
click node_worldmind "https://github.com/v1b3x0r/mds/tree/main/src/3-cognition/world-mind"
click node_dialogue "https://github.com/v1b3x0r/mds/blob/main/src/4-communication/dialogue/manager.ts"
click node_language "https://github.com/v1b3x0r/mds/blob/main/src/4-communication/language/generator.ts"
click node_semantics "https://github.com/v1b3x0r/mds/blob/main/src/4-communication/semantics/embeddings.ts"
click node_network "https://github.com/v1b3x0r/mds/tree/main/src/5-network"
click node_resources "https://github.com/v1b3x0r/mds/blob/main/src/6-world/resources/field.ts"
click node_linguistics "https://github.com/v1b3x0r/mds/tree/main/src/6-world/linguistics"
click node_materials "https://github.com/v1b3x0r/mds/blob/main/src/7-interface/io/mdm-parser.ts"
click node_context "https://github.com/v1b3x0r/mds/tree/main/src/7-interface/context"
click node_llm "https://github.com/v1b3x0r/mds/blob/main/src/7-interface/io/llmAdapter.ts"
click node_render "https://github.com/v1b3x0r/mds/tree/main/src/7-interface/render"
click node_worldfile "https://github.com/v1b3x0r/mds/blob/main/src/7-interface/io/worldfile.ts"
click node_logger "https://github.com/v1b3x0r/mds/blob/main/src/6-world/logger.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_world,node_engine toneBlue
class node_entity,node_ontology,node_relationships toneAmber
class node_physics,node_learning,node_worldmind,node_dialogue,node_language,node_semantics,node_network,node_resources,node_linguistics toneMint
class node_materials,node_context,node_llm,node_render,node_worldfile,node_logger toneRose
class node_app toneIndigo
```

## Components

### World Runtime

- [World Container](https://github.com/v1b3x0r/mds/blob/main/src/6-world/container.ts): `src/6-world/container.ts`
- [Simulation Engine](https://github.com/v1b3x0r/mds/blob/main/src/0-foundation/engine.ts): `src/0-foundation/engine.ts`

### Entity State

- [Entities](https://github.com/v1b3x0r/mds/blob/main/src/0-foundation/entity.ts): `src/0-foundation/entity.ts`
- [Memory, Emotion, Intent](https://github.com/v1b3x0r/mds/tree/main/src/1-ontology): `src/1-ontology`
- [Relationships](https://github.com/v1b3x0r/mds/tree/main/src/1-ontology/relationships): `src/1-ontology/relationships`

### World Capabilities

- [Physics and Weather](https://github.com/v1b3x0r/mds/tree/main/src/2-physics): `src/2-physics`
- [Learning and Skills](https://github.com/v1b3x0r/mds/tree/main/src/3-cognition): `src/3-cognition`
- [Collective Intelligence](https://github.com/v1b3x0r/mds/tree/main/src/3-cognition/world-mind): `src/3-cognition/world-mind`
- [Dialogue](https://github.com/v1b3x0r/mds/blob/main/src/4-communication/dialogue/manager.ts): `src/4-communication/dialogue/manager.ts`
- [Language Generation](https://github.com/v1b3x0r/mds/blob/main/src/4-communication/language/generator.ts): `src/4-communication/language/generator.ts`
- [Semantic Similarity](https://github.com/v1b3x0r/mds/blob/main/src/4-communication/semantics/embeddings.ts): `src/4-communication/semantics/embeddings.ts`
- [Peer Network](https://github.com/v1b3x0r/mds/tree/main/src/5-network): `src/5-network`
- [Resource Fields](https://github.com/v1b3x0r/mds/blob/main/src/6-world/resources/field.ts): `src/6-world/resources/field.ts`
- [Proto-language](https://github.com/v1b3x0r/mds/tree/main/src/6-world/linguistics): `src/6-world/linguistics`

### Inputs and Outputs

- [MDM Materials](https://github.com/v1b3x0r/mds/blob/main/src/7-interface/io/mdm-parser.ts): `src/7-interface/io/mdm-parser.ts`
- [Context Providers](https://github.com/v1b3x0r/mds/tree/main/src/7-interface/context): `src/7-interface/context`
- [Optional LLM Bridge](https://github.com/v1b3x0r/mds/blob/main/src/7-interface/io/llmAdapter.ts): `src/7-interface/io/llmAdapter.ts`
- [Render Adapters](https://github.com/v1b3x0r/mds/tree/main/src/7-interface/render): `src/7-interface/render`
- [Worldfile Persistence](https://github.com/v1b3x0r/mds/blob/main/src/7-interface/io/worldfile.ts): `src/7-interface/io/worldfile.ts`
- [World Logger](https://github.com/v1b3x0r/mds/blob/main/src/6-world/logger.ts): `src/6-world/logger.ts`

### Other components

- **Host Application**

## Connections

- Host Application → World Container: feeds context (evidence: `README.md`)
- Host Application → World Container: spawns materials (evidence: `README.md`)
- MDM Materials → World Container: defines responses (evidence: `README.md`)
- Context Providers → World Container: supplies context (evidence: `README.md`)
- World Container → Entities: manages state (evidence: `README.md`)
- World Container → World Logger: uses logger (evidence: `src/6-world/container.ts`)
- Simulation Engine → Entities: spawns (evidence: `src/0-foundation/engine.ts`)
- World Container → Dialogue: produces speech
- World Container → Proto-language: generates utterances
- World Container → Render Adapters: renders world
- World Container → Worldfile Persistence: saves state
- World Container → Physics and Weather: applies effects
- World Container → Memory, Emotion, Intent: updates state
- World Container → Relationships: updates bonds
- World Container → Learning and Skills: supports learning
- World Container → Collective Intelligence: supports collectives
- World Container → Resource Fields: models resources
- World Container → Peer Network: supports peers
- World Container → Semantic Similarity: uses similarity
- World Container → Optional LLM Bridge: requests generation
