# videlboga/cyberjack architecture
> Architecture diagram of the GitHub repository videlboga/cyberjack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/videlboga/cyberjack
- Repository: https://github.com/videlboga/cyberjack
## Overview
#### Purpose and Entry Points
Cyberjack is a TypeScript simulation/game backend with a React/Vite operator UI. It models characters, scenes, actions, contracts, resources, narrative reactions, and time-based world progression. Main runtime boundaries are the HTTP/socket server at `src/api/server.ts`, browser bootstrap at `src/ui/main.tsx`, and game-tick orchestrator at `src/orchestration/runGameTick.ts`. The repository also contains a separate Unity project under `Assets/` for 3D/avatar interaction work.
#### API and Client Boundary
The API layer exposes controller/route groups for players, state, ticks, scenarios, scenes, contracts, metadata, and logs. Controllers translate HTTP requests into orchestration/domain operations; socket support is isolated alongside the server. The UI is a multi-surface development/game workspace rather than a simple public site.
- `src/api/server.ts`
- `src/api/socket.ts`
- `src/api/controllers/tickController.ts`
- `src/ui/GameApp.tsx`
- `src/ui/WorkspaceApp.tsx`
#### Tick-Oriented Simulation Core
The primary control flow is a tick: load persisted state, evaluate scene/world conditions and triggers, select/execute actions, apply effects and learning, compute results, then save state and emit narrative/telemetry. The engine owns deterministic state transformation and validation; orchestration coordinates cross-domain work.
- `src/orchestration/loadTickState.ts`
- `src/orchestration/runGameTick.ts`
- `src/orchestration/saveTickState.ts`
- `src/engine/runTick.ts`
- `src/engine/computeResult.ts`
- `src/engine/applyLearning.ts`
#### Domain, Action Compilation, and Diagnostics
Domain modules define canonical schemas, anatomy, targets, profiles, edge state, taxonomy, and resolution rules. Incoming or generated actions are compiled into vectors/context, scaled and merged before engine execution. Diagnostics interpret semantic actions and infer traits from outcomes, creating a separate analysis boundary from simulation mutation.
- `src/domain/schemas.ts`
- `src/domain/edgeState.ts`
- `src/compiler/compileAction.ts`
- `src/compiler/compileContextVector.ts`
- `src/diagnostics/semanticActionInterpreter.ts`
#### Scenario and World Progression
Scenario services govern resource costs, asset purchases/contracts, action access, character lifecycle, spatial context, and scene transitions. Scene orchestration, condition watching, sustained effects, and event routing extend tick execution into campaign/world behavior.
- `src/scenario/runScenarioStep.ts`
- `src/scenario/resolveSceneTransition.ts`
- `src/scenario/worldService.ts`
- `src/orchestration/sceneOrchestrator.ts`
- `src/orchestration/conditionWatcher.ts`
- `src/orchestration/sustainedEffects.ts`
#### Persistence, Content, and Generation
Infrastructure encapsulates database access, repositories, event queries, contracts, seeding, presets, and generated visual matrices. Lore JSON and tag catalogs feed character generation, whose pipeline composes prompts and profiles/narratives. Character/portrait generation and memory/embedding services form external-service-facing boundaries; LLM/OpenRouter-oriented prompt construction is explicit.
- `src/infrastructure/db.ts`
- `src/infrastructure/repositories.ts`
- `src/infrastructure/data/presets/actions.json`
- `src/orchestration/characterGenerator/generator.ts`
- `src/prompts/openRouterPromptBuilder.ts`
- `src/services/embeddingService.ts`
#### Presentation and 3D Integration
React views visualize simulation, diagnostics, database state, campaign controls, portraits, and device/scene context. Static VRM models, poses, and backgrounds support avatar presentation. The Unity project includes body-part UI anchoring, a body UI manager, interaction management, and editor ragdoll generation, suggesting a separate Unity runtime/art pipeline rather than a direct replacement for the TypeScript server.
- `src/ui/views/Simulation/SimulationView.tsx`
- `src/ui/views/Diagnostics/DiagnosticsView.tsx`
- `public/models/base.vrm`
- `Assets/Scripts/UI/BodyUIManager.cs`
- `Assets/Scripts/UI/InteractionManager.cs`
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_api["API & clients"]
node_api_server["HTTP/socket server
TypeScript API"]
node_socket["Socket support
realtime transport"]
node_tick_controller["Tick controller
API controller"]
node_game_app["Game app
React app"]
node_workspace_app["Workspace app
React workspace"]
end
subgraph group_simulation["Simulation pipeline"]
node_run_game_tick{{"Game tick orchestrator
orchestration"}}
node_tick_state_load["Tick state loader
state loading"]
node_engine_tick{{"Tick engine
deterministic engine"}}
node_action_compiler["Action compiler
action vectors"]
node_result_learning["Results & learning
engine outcomes"]
node_tick_state_save["Tick state saver
state persistence"]
node_domain_model["Domain model
canonical schemas"]
node_diagnostics["Action diagnostics
outcome analysis"]
end
subgraph group_world["World & scenario"]
node_scene_orchestration{{"Scene orchestration
world behavior"}}
node_scenario_step["Scenario step
scenario service"]
end
subgraph group_data["Data & generation"]
node_database[("Database & repositories
persistence")]
node_content_presets["Content presets
JSON content"]
node_character_generation["Character generation
generation pipeline"]
node_prompt_embedding["LLM & embeddings
external AI services"]
end
subgraph group_presentation["Presentation & 3D"]
node_simulation_view["Simulation view
React view"]
node_diagnostics_view["Diagnostics view
React view"]
node_unity_interaction["Unity interaction
Unity runtime"]
node_vrm_avatar["VRM avatar assets
3D assets"]
end
node_game_app -->|"HTTP"| node_api_server
node_workspace_app -->|"HTTP"| node_api_server
node_api_server -->|"realtime"| node_socket
node_api_server -->|"routes tick"| node_tick_controller
node_tick_controller -->|"run tick"| node_run_game_tick
node_run_game_tick -->|"load state"| node_tick_state_load
node_tick_state_load -->|"read"| node_database
node_run_game_tick -->|"compile actions"| node_action_compiler
node_action_compiler -->|"uses schemas"| node_domain_model
node_action_compiler -->|"vectors"| node_engine_tick
node_run_game_tick -->|"execute"| node_engine_tick
node_domain_model -->|"rules"| node_engine_tick
node_engine_tick -->|"outcomes"| node_result_learning
node_result_learning -.->|"analyze"| node_diagnostics
node_run_game_tick -->|"evaluate world"| node_scene_orchestration
node_scene_orchestration -->|"scene actions"| node_scenario_step
node_scenario_step -->|"state rules"| node_domain_model
node_run_game_tick -->|"save outcomes"| node_tick_state_save
node_tick_state_save -->|"write"| node_database
node_content_presets -.->|"action definitions"| node_action_compiler
node_character_generation -->|"prompts and memory"| node_prompt_embedding
node_character_generation -->|"persist characters"| node_database
node_workspace_app -->|"renders"| node_simulation_view
node_workspace_app -->|"renders"| node_diagnostics_view
node_simulation_view -.->|"avatar asset"| node_vrm_avatar
node_unity_interaction -.->|"3D avatar work"| node_vrm_avatar
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_api_server,node_socket,node_tick_controller,node_game_app,node_workspace_app toneBlue
class node_run_game_tick,node_tick_state_load,node_engine_tick,node_action_compiler,node_result_learning,node_tick_state_save,node_domain_model,node_diagnostics toneAmber
class node_scene_orchestration,node_scenario_step toneMint
class node_database,node_content_presets,node_character_generation,node_prompt_embedding toneRose
class node_simulation_view,node_diagnostics_view,node_unity_interaction,node_vrm_avatar toneIndigo
```
## Components
### API & clients
- **HTTP/socket server**: TypeScript API · Routes requests and hosts realtime support.
- **Socket support**: realtime transport
- **Tick controller**: API controller · Starts simulation ticks from API requests.
- **Game app**: React app
- **Workspace app**: React workspace · Development and operations surfaces.
### Simulation pipeline
- **Game tick orchestrator**: orchestration · Coordinates state, engine, world behavior, and persistence.
- **Tick state loader**: state loading
- **Tick engine**: deterministic engine · Validates and transforms canonical game state.
- **Action compiler**: action vectors · Compiles, scales, and merges action context.
- **Results & learning**: engine outcomes
- **Tick state saver**: state persistence
- **Domain model**: canonical schemas · Defines entities, taxonomy, targets, and edge state.
- **Action diagnostics**: outcome analysis · Interprets semantic actions and inferred traits.
### World & scenario
- **Scene orchestration**: world behavior · Watches conditions and manages sustained effects.
- **Scenario step**: scenario service · Governs contracts, costs, lifecycle, and transitions.
### Data & generation
- **Database & repositories**: persistence · Stores state, events, contracts, and query data.
- **Content presets**: JSON content · Seed actions and authored game content.
- **Character generation**: generation pipeline · Builds characters, profiles, and narratives.
- **LLM & embeddings**: external AI services · Builds OpenRouter prompts and manages semantic memory.
### Presentation & 3D
- **Simulation view**: React view
- **Diagnostics view**: React view
- **Unity interaction**: Unity runtime · Separate avatar/body interaction runtime.
- **VRM avatar assets**: 3D assets
## Connections
- Game app → HTTP/socket server: HTTP
- Workspace app → HTTP/socket server: HTTP
- HTTP/socket server → Socket support: realtime
- HTTP/socket server → Tick controller: routes tick
- Tick controller → Game tick orchestrator: run tick
- Game tick orchestrator → Tick state loader: load state
- Tick state loader → Database & repositories: read
- Game tick orchestrator → Action compiler: compile actions
- Action compiler → Domain model: uses schemas
- Action compiler → Tick engine: vectors
- Game tick orchestrator → Tick engine: execute
- Domain model → Tick engine: rules
- Tick engine → Results & learning: outcomes
- Results & learning → Action diagnostics: analyze
- Game tick orchestrator → Scene orchestration: evaluate world
- Scene orchestration → Scenario step: scene actions
- Scenario step → Domain model: state rules
- Game tick orchestrator → Tick state saver: save outcomes
- Tick state saver → Database & repositories: write
- Content presets → Action compiler: action definitions
- Character generation → LLM & embeddings: prompts and memory
- Character generation → Database & repositories: persist characters
- Workspace app → Simulation view: renders
- Workspace app → Diagnostics view: renders
- Simulation view → VRM avatar assets: avatar asset
- Unity interaction → VRM avatar assets: 3D avatar work