# maria-shchurova/ai-lifesim architecture

> Architecture diagram of the GitHub repository maria-shchurova/ai-lifesim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maria-shchurova/ai-lifesim
- Repository: https://github.com/maria-shchurova/ai-lifesim

## Overview

##### Project Type and Purpose
- This is a Unity-based full-stack game project (“ai-lifesim”).
- Purpose: A dialogue-based simulation where NPCs use the OpenAI API to generate character speech and behaviors at runtime.

##### File Structure Analysis
- Top-level directories:
- Assets – contains all game assets: 3D models, animations, materials, scripts, scenes, UI, plugins, editor extensions.
- Packages – NuGet/.NET dependencies and Unity package manifest.
- ProjectSettings – Unity project configuration.
- UserSettings – local Unity editor layouts/settings.
- Key subfolders under Assets:
- Scripts – core game logic, NPC behavior, AI controllers, menus, scene controls.
- Plugins/x64/OpenAI_API – C# client wrappers for OpenAI endpoints (Chat, Completions, Embeddings, Images, Files, Models, Moderation).
- Editor – Unity editor extensions: AICommandWindow, Roslyn compiler integration, OpenAIUtil.
- StreamingAssets – persona and chatHistory JSON for each NPC (Alice, Ernest, Kathie, Trenton).
- Scenes – Unity .unity scene files and NavMesh assets.
- UI – prefabs for Canvas/menu screens.
- Unity-Roslyn – Roslyn compiler integration assembly.
- Configuration files: manifest.json, packages-lock.json, ProjectSettings/…
- Dependencies: TextMesh Pro, Unity-Roslyn, Microsoft.CodeAnalysis, System.*

##### README Insights
- Describes using OpenAI Unity integration for characters at runtime.
- References Roslyn to compile C# code in Unity.
- Credits 3D asset sources.

a. Main Components
1. Unity Engine
– Scene & Game Loop
– Asset Pipeline (3D models, animations, materials).
2. Presentation Layer
– UI Canvas & Menus (MainMenu, PauseMenu).
– TextMeshPro for text rendering.
3. Game Logic Layer
– Scripts (GameStateManager, PlayerInteractions, NPC, Messenger, SceneControls).
– NPC Subsystem: NPCMemory, NPC_Persona, NPCtoNPC, DynamicRelationships, Schedule.
– Animation controllers (Assets/Character topdown, Assets/NPC/*/Animations).
4. AI Integration Layer
– OpenAIController & Messenger (wrapper orchestrating requests).
– Plugins/OpenAI_API endpoints (Chat, Completion, Embedding, etc.).
– Editor/OpenAIUtil for testing in Editor.
5. Data Layer
– StreamingAssets/persona.txt & chatHistory.json (persistent per-NPC context).
6. External Service
– OpenAI REST API (hosted externally).
7. Tooling/Editor Extensions
– Unity-Roslyn for runtime C# compilation.
– Editor scripts (AICommandWindow) for dev workflows.

b. Relationships & Data Flows
- Player → PlayerInteractions → GameStateManager
- When player talks to NPC:
- GameLogic → OpenAIController → Plugins/OpenAI_API → HTTP request → OpenAI Service
- Receive JSON response → Messenger → NPCMemory updates → NPCtoNPC events
- NPCMemory & schedule drive animation state (Animator controllers) and dialogue UI.
- StreamingAssets store persona and conversation history; read/write by OpenAIController.
- Editor tools (Roslyn, OpenAIUtil) enable testing/compiling commands during development.

c. Architectural Patterns & Principles
- Layered architecture: Presentation → Game Logic → AI Integration → Data → External.
- Separation of concerns:
- UI components isolated in Assets/UI.
- Core game logic in Scripts/.
- External API calls encapsulated in Plugins/OpenAI_API.
- Data persistency via StreamingAssets.
- Dependency injection pattern: Messenger class for callbacks.

d. Technologies & Frameworks
- Unity 2021.x
- C# 8/.NET 6.0 (via Unity-Roslyn)
- OpenAI .NET client (Plugins/OpenAI_API)
- TextMesh Pro for text rendering
- NavMesh for NPC pathfinding

##### Detail Level
- Essential elements: Assets → Scripts → Plugins → External API → Data.
- Do not overcrowd: group similar animation assets or NPC folders into single “NPC Assets” node.
- Data flows (persona/chatHistory) are shown distinctly.

## Diagram (Mermaid)

```mermaid
graph TD
  subgraph "Runtime Execution"
    subgraph "Unity Engine"
      UE["Unity Engine"]:::engine
      Scenes["Scenes"]:::engine
    end
    subgraph "Presentation Layer"
      UI["UI Canvas & Menus"]:::engine
      TMP["TextMesh Pro"]:::engine
    end
    subgraph "Game Logic"
      PI["PlayerInteractions"]:::logic
      GSM["GameStateManager"]:::logic
      subgraph "Menus"
        MM["MainMenu"]:::logic
        PM["PauseMenu"]:::logic
      end
      subgraph "NPC Subsystem"
        NPC["NPC Core"]:::logic
        NM["NPCMemory"]:::logic
        NP["NPC_Persona"]:::logic
        N2N["NPCtoNPC"]:::logic
        DR["DynamicRelationships"]:::logic
        SCH["Schedule"]:::logic
      end
      subgraph "Messenger DI"
        MSG["Messenger"]:::logic
        CB["Callback"]:::logic
      end
      subgraph "Scene Controls"
        SC["SceneControls"]:::logic
        CC["CameraControl"]:::logic
        CF["CameraFlyAround"]:::logic
      end
    end
  end

  subgraph "AI Integration"
    OAC["OpenAIController"]:::logic
    Plugins["OpenAI .NET Client Wrappers"]:::logic
    subgraph "Tests & Examples"
      TA["TestsAI"]:::logic
      CE["CompilerExample"]:::logic
    end
  end

  subgraph "Data Storage"
    SA["StreamingAssets (Persona & ChatHistory)"]:::data
  end

  subgraph "Editor Tooling"
    UR["Unity-Roslyn"]:::editor
    ACW["AICommandWindow"]:::editor
    OU["OpenAIUtil"]:::editor
    ACS["AICommandSettings"]:::editor
  end

  EXT["OpenAI REST API"]:::external

  PI --> GSM
  GSM --> OAC
  OAC --> Plugins
  Plugins --> EXT
  EXT --> OAC
  OAC --> MSG
  MSG --> NM
  NM --> DR
  DR --> NPC
  NPC --> SC
  SC --> CC
  SC --> CF
  NPC --> SA
  OAC --> SA
  UI --> PI
  TMP --> UI
  Scenes --> GSM

  ACW --> OAC
  OU --> OAC
  ACS --> ACW
  CE --> UR
  TA --> UR

  click Scenes "https://github.com/maria-shchurova/ai-lifesim/tree/main/Assets/Scenes/"
  click UI "https://github.com/maria-shchurova/ai-lifesim/tree/main/Assets/UI/"
  click TMP "https://github.com/maria-shchurova/ai-lifesim/tree/main/Assets/TextMesh Pro/"
  click GSM "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/GameStateManager.cs"
  click PI "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/PlayerInteractions.cs"
  click MM "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/MainMenu.cs"
  click PM "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/PauseMenu.cs"
  click NM "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/NPC/NPCMemory.cs"
  click NP "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/NPC/NPC_Persona.cs"
  click N2N "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/NPC/NPCtoNPC.cs"
  click DR "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/NPC/DynamicRelationships.cs"
  click SCH "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/NPC/Schedule.cs"
  click NPC "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/NPC/NPC.cs"
  click MSG "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/Messenger/Messenger.cs"
  click CB "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/Messenger/Callback.cs"
  click SC "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/SceneControls/SceneControls.cs"
  click CC "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/SceneControls/CameraControl.cs"
  click CF "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/SceneControls/CameraFlyAround.cs"
  click OAC "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/OpenAIController.cs"
  click TA "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/TestsAI.cs"
  click CE "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Scripts/CompilerExample.cs"
  click Plugins "https://github.com/maria-shchurova/ai-lifesim/tree/main/Assets/Plugins/x64/OpenAI_API/"
  click ACW "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Editor/AICommandWindow.cs"
  click OU "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Editor/OpenAIUtil.cs"
  click ACS "https://github.com/maria-shchurova/ai-lifesim/blob/main/Assets/Editor/AICommandSettings.cs"
  click UR "https://github.com/maria-shchurova/ai-lifesim/tree/main/Assets/Unity-Roslyn/"

  classDef engine fill:#ADD8E6,stroke:#333,stroke-width:1px
  classDef logic fill:#90EE90,stroke:#333,stroke-width:1px
  classDef external fill:#ff6961,stroke:#333,stroke-width:1px
  classDef data fill:#ffb347,stroke:#333,stroke-width:1px
  classDef editor fill:#d3d3d3,stroke:#333,stroke-width:1px
```
