# open-worker-2077/atom architecture

> Architecture diagram of the GitHub repository open-worker-2077/atom, 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/open-worker-2077/atom
- Repository: https://github.com/open-worker-2077/atom

## Overview

Atom is an executable, evolving fact world: people, Agents, and Programs read and change shared facts through Web or CLI interactions. The principal path is an interaction entering the shared world service, executing Program logic when requested, and committing changes to durable world state; projections and spatial views make that state observable and editable. The README documents the product boundary and capabilities. Source excerpts and the index support several internal calls, but many Web, spatial, and persistence connections are documented only at a high level, so those links are omitted or marked unverified.

Main entry points: [`src/atom-system/browser-entry.mjs`](https://github.com/open-worker-2077/atom/blob/main/src/atom-system/browser-entry.mjs) (Web entry), [`src/atom-system/adapters/legacy-engine-adapter.mjs`](https://github.com/open-worker-2077/atom/blob/main/src/atom-system/adapters/legacy-engine-adapter.mjs) (Engine adapter), [`work-engine/atom-language/engine.mjs`](https://github.com/open-worker-2077/atom/blob/main/work-engine/atom-language/engine.mjs) (Atom engine), [`src/atom-system/public/world-service.mjs`](https://github.com/open-worker-2077/atom/blob/main/src/atom-system/public/world-service.mjs) (World service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Interaction"]
  node_web["Web entry<br/>[browser-entry.mjs]"]
  node_cli["CLI interface<br/>[cli-app.mjs]"]
  node_browser_mapper["Command mapper"]
  node_world_service["World service<br/>[world-service.mjs]"]
  node_engine_adapter["Engine adapter"]
end

subgraph group_world["World runtime"]
  node_world_facts["World facts<br/>[context-store.mjs]"]
  node_world_repo[("JSON world repository")]
  node_transactional["Transactional persistence"]
  node_save_worker["Durable save worker"]
  node_revision["World revisions<br/>[world-revision.mjs]"]
  node_commit["Commit coordinator"]
  node_projection["Projection pipeline"]
end

subgraph group_programs["Program runtime"]
  node_engine["Atom engine<br/>[engine.mjs]"]
  node_programs_lang["Program definitions<br/>[program.mjs]"]
  node_query["Query capability"]
  node_transform["Transform executor"]
  node_key_parser["Key parser<br/>[key-parser.mjs]"]
end

subgraph group_spatial["Spatial experience"]
  node_scene["Scene adapter"]
  node_spatial_engine["Spatial engine<br/>[spatial-engine.js]"]
  node_cluster_field["Cluster field"]
  node_view_state[("View state")]
  node_presentation["Presentation settings"]
end

node_people(("People / Agents"))

node_people -->|"uses"| node_web
node_people -->|"uses"| node_cli
node_web -.->|"interacts through"| node_world_service
node_cli -.->|"shares world"| node_world_service
node_web -.->|"maps commands"| node_browser_mapper
node_world_service -->|"delegates execution"| node_engine_adapter
node_engine_adapter -->|"executes"| node_engine
node_engine -->|"queries"| node_query
node_engine -->|"applies transforms"| node_transform
node_programs_lang -->|"applies transforms"| node_transform
node_key_parser -.->|"validates keys"| node_world_facts
node_engine_adapter -->|"creates persistence"| node_transactional
node_transactional -.->|"persists world"| node_world_repo
node_save_worker -->|"writes durable state"| node_world_repo
node_save_worker -->|"coordinates commits"| node_commit
node_world_repo -->|"checks revisions"| node_revision
node_world_facts -->|"derives revision"| node_revision
node_projection -.->|"projects facts"| node_world_facts
node_scene -.->|"adapts scene"| node_spatial_engine
node_spatial_engine -.->|"renders clusters"| node_cluster_field
node_presentation -.->|"configures views"| node_view_state

click node_web "https://github.com/open-worker-2077/atom/blob/main/src/atom-system/browser-entry.mjs"
click node_cli "https://github.com/open-worker-2077/atom/blob/main/cli/lib/cli-app.mjs"
click node_browser_mapper "https://github.com/open-worker-2077/atom/blob/main/src/atom-system/browser-command-mapper.mjs"
click node_world_service "https://github.com/open-worker-2077/atom/blob/main/src/atom-system/public/world-service.mjs"
click node_engine_adapter "https://github.com/open-worker-2077/atom/blob/main/src/atom-system/adapters/legacy-engine-adapter.mjs"
click node_engine "https://github.com/open-worker-2077/atom/blob/main/work-engine/atom-language/engine.mjs"
click node_programs_lang "https://github.com/open-worker-2077/atom/blob/main/work-engine/atom-language/program.mjs"
click node_query "https://github.com/open-worker-2077/atom/blob/main/work-engine/atom-language/query-capability.mjs"
click node_transform "https://github.com/open-worker-2077/atom/blob/main/work-engine/atom-language/transform-executor.mjs"
click node_key_parser "https://github.com/open-worker-2077/atom/blob/main/work-engine/atom-language/key-parser.mjs"
click node_world_facts "https://github.com/open-worker-2077/atom/blob/main/work-engine/atom-language/context-store.mjs"
click node_world_repo "https://github.com/open-worker-2077/atom/blob/main/src/atom-system/adapters/json-world-repository.mjs"
click node_transactional "https://github.com/open-worker-2077/atom/blob/main/src/atom-system/adapters/transactional-world-persistence.mjs"
click node_save_worker "https://github.com/open-worker-2077/atom/blob/main/src/atom-system/adapters/durable-world-save-worker.mjs"
click node_revision "https://github.com/open-worker-2077/atom/blob/main/src/atom-system/world-runtime/world-revision.mjs"
click node_commit "https://github.com/open-worker-2077/atom/blob/main/src/atom-system/world-runtime/commit-coordinator.mjs"
click node_projection "https://github.com/open-worker-2077/atom/blob/main/src/atom-system/projections/projection-pipeline.mjs"
click node_scene "https://github.com/open-worker-2077/atom/blob/main/src/atom-system/adapters/browser-scene-adapter.mjs"
click node_spatial_engine "https://github.com/open-worker-2077/atom/blob/main/spatial-engine.js"
click node_cluster_field "https://github.com/open-worker-2077/atom/blob/main/spatial-cluster-field.js"
click node_view_state "https://github.com/open-worker-2077/atom/blob/main/src/atom-system/spatial-experience/view-state-repository.mjs"
click node_presentation "https://github.com/open-worker-2077/atom/blob/main/src/atom-system/spatial-experience/presentation-settings-service.mjs"

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,node_cli,node_browser_mapper,node_world_service,node_engine_adapter toneBlue
class node_world_facts,node_world_repo,node_transactional,node_save_worker,node_revision,node_commit,node_projection toneAmber
class node_engine,node_programs_lang,node_query,node_transform,node_key_parser toneMint
class node_scene,node_spatial_engine,node_cluster_field,node_view_state,node_presentation toneRose
class node_people toneIndigo
```

## Components

### Interaction

- [Web entry](https://github.com/open-worker-2077/atom/blob/main/src/atom-system/browser-entry.mjs): `src/atom-system/browser-entry.mjs`
- [CLI interface](https://github.com/open-worker-2077/atom/blob/main/cli/lib/cli-app.mjs): `cli/lib/cli-app.mjs`
- [Command mapper](https://github.com/open-worker-2077/atom/blob/main/src/atom-system/browser-command-mapper.mjs): `src/atom-system/browser-command-mapper.mjs`
- [World service](https://github.com/open-worker-2077/atom/blob/main/src/atom-system/public/world-service.mjs): `src/atom-system/public/world-service.mjs`
- [Engine adapter](https://github.com/open-worker-2077/atom/blob/main/src/atom-system/adapters/legacy-engine-adapter.mjs): `src/atom-system/adapters/legacy-engine-adapter.mjs`

### World runtime

- [World facts](https://github.com/open-worker-2077/atom/blob/main/work-engine/atom-language/context-store.mjs): `work-engine/atom-language/context-store.mjs`
- [JSON world repository](https://github.com/open-worker-2077/atom/blob/main/src/atom-system/adapters/json-world-repository.mjs): `src/atom-system/adapters/json-world-repository.mjs`
- [Transactional persistence](https://github.com/open-worker-2077/atom/blob/main/src/atom-system/adapters/transactional-world-persistence.mjs): `src/atom-system/adapters/transactional-world-persistence.mjs`
- [Durable save worker](https://github.com/open-worker-2077/atom/blob/main/src/atom-system/adapters/durable-world-save-worker.mjs): `src/atom-system/adapters/durable-world-save-worker.mjs`
- [World revisions](https://github.com/open-worker-2077/atom/blob/main/src/atom-system/world-runtime/world-revision.mjs): `src/atom-system/world-runtime/world-revision.mjs`
- [Commit coordinator](https://github.com/open-worker-2077/atom/blob/main/src/atom-system/world-runtime/commit-coordinator.mjs): `src/atom-system/world-runtime/commit-coordinator.mjs`
- [Projection pipeline](https://github.com/open-worker-2077/atom/blob/main/src/atom-system/projections/projection-pipeline.mjs): `src/atom-system/projections/projection-pipeline.mjs`

### Program runtime

- [Atom engine](https://github.com/open-worker-2077/atom/blob/main/work-engine/atom-language/engine.mjs): `work-engine/atom-language/engine.mjs`
- [Program definitions](https://github.com/open-worker-2077/atom/blob/main/work-engine/atom-language/program.mjs): `work-engine/atom-language/program.mjs`
- [Query capability](https://github.com/open-worker-2077/atom/blob/main/work-engine/atom-language/query-capability.mjs): `work-engine/atom-language/query-capability.mjs`
- [Transform executor](https://github.com/open-worker-2077/atom/blob/main/work-engine/atom-language/transform-executor.mjs): `work-engine/atom-language/transform-executor.mjs`
- [Key parser](https://github.com/open-worker-2077/atom/blob/main/work-engine/atom-language/key-parser.mjs): `work-engine/atom-language/key-parser.mjs`

### Spatial experience

- [Scene adapter](https://github.com/open-worker-2077/atom/blob/main/src/atom-system/adapters/browser-scene-adapter.mjs): `src/atom-system/adapters/browser-scene-adapter.mjs`
- [Spatial engine](https://github.com/open-worker-2077/atom/blob/main/spatial-engine.js): `spatial-engine.js`
- [Cluster field](https://github.com/open-worker-2077/atom/blob/main/spatial-cluster-field.js): `spatial-cluster-field.js`
- [View state](https://github.com/open-worker-2077/atom/blob/main/src/atom-system/spatial-experience/view-state-repository.mjs): `src/atom-system/spatial-experience/view-state-repository.mjs`
- [Presentation settings](https://github.com/open-worker-2077/atom/blob/main/src/atom-system/spatial-experience/presentation-settings-service.mjs): `src/atom-system/spatial-experience/presentation-settings-service.mjs`

### Other components

- **People / Agents**

## Connections

- People / Agents → Web entry: uses (evidence: `README.md`)
- People / Agents → CLI interface: uses (evidence: `README.md`)
- Web entry → World service: interacts through
- CLI interface → World service: shares world (evidence: `README.md`)
- Web entry → Command mapper: maps commands
- World service → Engine adapter: delegates execution (evidence: `src/atom-system/adapters/legacy-engine-adapter.mjs`)
- Engine adapter → Atom engine: executes (evidence: `src/atom-system/adapters/legacy-engine-adapter.mjs`)
- Atom engine → Query capability: queries (evidence: `work-engine/atom-language/engine.mjs`)
- Atom engine → Transform executor: applies transforms (evidence: `work-engine/atom-language/engine.mjs`)
- Program definitions → Transform executor: applies transforms (evidence: `work-engine/atom-language/program.mjs`)
- Key parser → World facts: validates keys (evidence: `work-engine/atom-language/context-store.mjs`)
- Engine adapter → Transactional persistence: creates persistence (evidence: `src/atom-system/adapters/legacy-engine-adapter.mjs`)
- Transactional persistence → JSON world repository: persists world
- Durable save worker → JSON world repository: writes durable state (evidence: `src/atom-system/adapters/durable-world-save-worker.mjs`)
- Durable save worker → Commit coordinator: coordinates commits (evidence: `src/atom-system/adapters/durable-world-save-worker.mjs`)
- JSON world repository → World revisions: checks revisions (evidence: `src/atom-system/adapters/json-world-repository.mjs`)
- World facts → World revisions: derives revision (evidence: `work-engine/atom-language/context-store.mjs`)
- Projection pipeline → World facts: projects facts
- Scene adapter → Spatial engine: adapts scene
- Spatial engine → Cluster field: renders clusters
- Presentation settings → View state: configures views
