# solarint/sain architecture

> Architecture diagram of the GitHub repository solarint/sain, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/solarint/sain
- Repository: https://github.com/solarint/sain

## Overview

##### Project Type & Purpose
- This is a **plugin-based AI system** for “Single-player Escape From Tarkov” (SPT-AKI).
- It consists of two main subsystems:
a) A **Unity/BepInEx C# plugin** (SAIN) that replaces the in-game bot AI.
b) A **Node/TypeScript ServerMod** loaded by SPT-AKI to provide REST-style endpoints, configuration synchronization, version checks, and mod-lifecycle hooks.

##### Top-Level Components
A. Unity/C# Plugin (under root folder)
- **BepInEx Loader & Plugin Entry** (`Plugin/SAINPlugin.cs`, `AssemblyInfoClass.cs`)
- **BotComponentSpace** – Core AI component attached to every bot: decision trees, vision, hearing, movement, memory
- **BotControllerSpace** – Manages squads, spawning logic, periodic jobs
- **GameWorldSpace** – Environment queries: doors, lights, player positions
- **PlayerComponentSpace** – Reads player state, equipment, illumination, sound
- **Layers** – Sets of AI behaviors organized by priority (Combat/Solo, Combat/Squad, Peace, Extract, Unstuck, Debug)
- **Patches** – BepInEx/Harmony patches that disable default BigBrain layers and inject SAIN layers
- **Preset & Config System** (`Preset`, `Plugin/PresetHandler.cs`, GUI editors) – Loads/saves JSON presets, delivers live updates via in-game GUI (F6)
- **Helpers & Interfaces** – Utility classes, reflection, JSON, math, navmesh helpers
- **Coroutine/Threading** – `CoroutineManager` for multi-threaded vision raycasts, AI updates
- **External Dependencies** – BigBrain plugin, Waypoints expanded navmesh

B. ServerMod (under `ServerMod/` folder)
- **Mod Loader Bootstrap** (`mod.ts`, build scripts) loaded by SPT-AKI
- **Dependency Injection Container** (`tsyringe`)
- **Routers** – HTTP, WebSocket, ItemEvent, Dynamic & Static routers
- **Controllers** – One per REST endpoint (GameController, BotController, ProfileController, etc.)
- **Services** – Business logic (BotGeneratorService, RagfairService, ProfileSnapshotService, etc.)
- **Generators** – Factories for bots, items, loot, quests
- **Models & Types** – Strongly typed DTOs for all SPT-AKI callbacks and request/response schemas
- **Utilities** – Database importer, HTTP file util, random, UUID, logging

##### Relationships & Data Flows
- **Game Engine → BepInEx Loader**
BepInEx starts up and loads `SAINPlugin`.
- **SAINPlugin**
- On bot spawn, attaches **SAINComponent** → instantiates a **BotComponent**.
- **BotComponent** reads environment from **GameWorldSpace** and **PlayerComponentSpace**, then runs **DecisionManager** in its update loop.
- **Layers** register actions in a priority queue; selected actions command the bot’s `Mover`, `WeaponFunction`, `Search`, `Talk`, etc.
- **CoroutineManager** dispatches multi-threaded vision raycasts to a thread pool and returns results to the component.
- **PresetHandler** loads JSON presets from disk; **ConfigEditingTracker** watches for GUI changes and pushes updates live into the AI components.
- **Patches** use Harmony to disable default BigBrain combat layers and inject SAIN layers in parallel.

- **SPT-AKI ServerMod**
- The Node application is launched by SPT-AKI’s mod loader.
- It registers **Routers** with internal HTTP server → incoming API calls.
- **HTTPRouter** dispatches to **Controllers** → calls into **Services** → may call **Generators** or **Utils** → returns JSON.
- Used for mod lifecycle hooks (OnLoad, OnUpdate), preset import/export endpoints, version checks, dependency validation, and any server-side computations.

##### Architectural Patterns & Principles
- **Component-Based Architecture** in Unity: one SAIN component per bot, plus subcomponents for cover-finding, memory, movement.
- **Layered Behavior System**: stacks of actions (Combat/Solo, Combat/Squad, etc.) selected by priority.
- **Plugin & Patch**: BepInEx/Harmony injection to override default AI without touching core game code.
- **Dependency Injection** in ServerMod (tsyringe) for testability and modularity.
- **Modular Organization**: separate domains into folders (Components, Layers, Preset, Patches, Helpers).
- **Multi-Threading**: offload expensive vision raycasts from main thread.
- **Live Configuration**: in-game GUI writes JSON, components subscribe to config events.

## Diagram (Mermaid)

```mermaid
graph TD
    GameEngine["Game Engine"]:::external

    subgraph "Unity Plugin (C#)"
        SAINPlugin["BepInEx Loader & Plugin Entry"]:::plugin
        AssemblyInfo["Assembly Info"]:::plugin
        BotAI["BotComponentSpace (AI Core)"]:::plugin
        BotController["BotControllerSpace"]:::plugin
        GameWorld["GameWorldSpace"]:::plugin
        PlayerComp["PlayerComponentSpace"]:::plugin
        Layers["Behavior Layers"]:::plugin
        Patches["Patches"]:::plugin
        PresetHandler["Preset & Config System"]:::plugin
        PresetStore["Preset JSON Store"]:::storage
        Helpers["Helpers & Interfaces"]:::plugin
        Coroutine["CoroutineManager (Threading)"]:::plugin
        BigBrainHandler["BigBrain Handler"]:::plugin
        ExternalHandler["External Dependencies Handler"]:::plugin
    end

    subgraph "Thread Pool"
        ThreadPool["Thread Pool"]:::external
    end

    subgraph "External Dependencies"
        BigBrain["BigBrain Plugin"]:::external
        Waypoints["Waypoints NavMesh"]:::external
    end

    subgraph "ServerMod (Node/TS)"
        SMBootstrap["Bootstrap (mod.ts, build scripts)"]:::servermod
        DIConfig["Dependency Injection (tsyringe)"]:::servermod
        Routers["Routers (HTTP, WS, etc.)"]:::servermod
        Controllers["Controllers (REST Endpoints)"]:::servermod
        Services["Services (Business Logic)"]:::servermod
        Generators["Generators (Factories)"]:::servermod
        Models["Models & Types (DTOs)"]:::servermod
        Utils["Utilities"]:::servermod
    end

    GameEngine -->|loads| SAINPlugin
    SAINPlugin -->|uses| AssemblyInfo
    SAINPlugin -->|Attach SAINComponent| BotAI
    BotAI -->|reads environment| GameWorld
    BotAI -->|reads player state| PlayerComp
    BotAI -->|Decision→Layer Action| Layers
    BotAI -->|dispatch vision raycast| Coroutine
    Coroutine -->|uses| ThreadPool
    ThreadPool -->|returns results| Coroutine
    PresetHandler -->|loads presets| PresetStore
    PresetStore -->|Config File Change| PresetHandler
    PresetHandler -->|live update| BotAI
    SAINPlugin -->|apply patches| Patches
    Patches -->|invoke| BigBrainHandler
    Patches -->|invoke| ExternalHandler
    Patches -->|disable default AI| BigBrain
    Patches -->|inject SAIN layers| Layers

    GameEngine -->|launch mod| SMBootstrap
    SMBootstrap -->|configures| DIConfig
    DIConfig -->|injects| Routers
    Routers -->|HTTP Request| Controllers
    Controllers -->|calls| Services
    Services -->|uses factories| Generators
    Services -->|uses utils| Utils
    Controllers -->|uses| Models

    click SAINPlugin "https://github.com/solarint/sain/blob/3.2.0-Release/Plugin/SAINPlugin.cs"
    click AssemblyInfo "https://github.com/solarint/sain/blob/3.2.0-Release/Plugin/AssemblyInfoClass.cs"
    click BotAI "https://github.com/solarint/sain/tree/3.2.0-Release/Components/BotComponentSpace"
    click BotController "https://github.com/solarint/sain/tree/3.2.0-Release/Components/BotControllerSpace"
    click GameWorld "https://github.com/solarint/sain/tree/3.2.0-Release/Components/GameWorldSpace"
    click PlayerComp "https://github.com/solarint/sain/tree/3.2.0-Release/Components/PlayerComponentSpace"
    click Layers "https://github.com/solarint/sain/tree/3.2.0-Release/Layers"
    click Patches "https://github.com/solarint/sain/tree/3.2.0-Release/Patches"
    click PresetHandler "https://github.com/solarint/sain/blob/3.2.0-Release/Plugin/PresetHandler.cs"
    click PresetStore "https://github.com/solarint/sain/tree/3.2.0-Release/Preset/"
    click Helpers "https://github.com/solarint/sain/tree/3.2.0-Release/Helpers/"
    click Interfaces "https://github.com/solarint/sain/blob/3.2.0-Release/Interfaces.cs"
    click Coroutine "https://github.com/solarint/sain/blob/3.2.0-Release/Components/BotComponentSpace/CoroutineManager.cs"
    click BigBrainHandler "https://github.com/solarint/sain/blob/3.2.0-Release/Plugin/BigBrainHandler.cs"
    click ExternalHandler "https://github.com/solarint/sain/blob/3.2.0-Release/Plugin/External.cs"
    click SMBootstrap "https://github.com/solarint/sain/blob/3.2.0-Release/ServerMod/src/mod.ts"
    click DIConfig "https://github.com/solarint/sain/blob/3.2.0-Release/ServerMod/package.json"
    click SMBootstrap "https://github.com/solarint/sain/blob/3.2.0-Release/ServerMod/build.mjs"
    click Routers "https://github.com/solarint/sain/tree/3.2.0-Release/ServerMod/types/routers"
    click Controllers "https://github.com/solarint/sain/tree/3.2.0-Release/ServerMod/types/controllers"
    click Services "https://github.com/solarint/sain/tree/3.2.0-Release/ServerMod/types/services"
    click Generators "https://github.com/solarint/sain/tree/3.2.0-Release/ServerMod/types/generators"
    click Models "https://github.com/solarint/sain/tree/3.2.0-Release/ServerMod/types/models"
    click Utils "https://github.com/solarint/sain/tree/3.2.0-Release/ServerMod/types/utils"

    classDef plugin fill:#cce5ff,stroke:#3182bd
    classDef servermod fill:#d4edda,stroke:#2f855a
    classDef external fill:#ffe5b4,stroke:#dd6b20
    classDef storage fill:#e2d3b1,stroke:#a05310
```
