# Forge Architecture & Data Flow Diagram

## 🏗️ **System Architecture Overview**

```mermaid
graph TD
    subgraph ForgeSystem [FORGE SYSTEM]
        subgraph Clients [Clients #40;Read-Only#41;]
            ClientA[CLIENT A]
            ClientB[CLIENT B]
            ClientN[CLIENT N]

            subgraph OptimisticCache [Optimistic Cache]
                ActorObj[Actor Object<br/>- loadout<br/>- position<br/>- stats]
            end

            ClientA --- OptimisticCache
            ClientB --- OptimisticCache
            ClientN --- OptimisticCache
        end

        subgraph Server [ArmA 3 SERVER #40;Hot Cache#41;]
            Registry["GVAR(Registry)<br/>In-Memory HashMap<br/>UID -> {loadout, position, stats...}"]
            SessionMgmt[Session Management<br/>- Token Generation<br/>- UID Resolution<br/>- Player State]
        end

        subgraph Rust [EXTENSION #40;Cold Storage#41;]
            ConnPool["Connection Pool<br/>(bb8-redis)<br/>2-10 connections"]
            RedisOps[Redis Operations<br/>- actor_get/set/update<br/>- Async I/O]
        end

        subgraph Redis [DATABASE #40;Saved to Disc#41;]
            ActorDataStore[Actor Data Store<br/>actor:UID -> JSON]
            Modules[Additional Modules<br/>garage, locker, bank, org]
        end

        Clients -->|Event Driven<br/>#40;CBA A3 Events#41;| Server
        Server -->|Extension Calls<br/>#40;Rust FFI#41;| Rust
        Rust -->|Redis Protocol<br/>#40;bb8-redis#41;| Redis
    end
```

## 🔄 **Data Flow Sequence**

### **1. Player Connection & Initial Data Load**

```mermaid
sequenceDiagram
    participant Client
    participant Server as Server (Hot Cache)
    participant Extension as Extension (Cold Storage)
    participant Redis as Redis (Database)

    Note over Client, Redis: 1. Player Connection & Initial Data Load

    Client->>Server: 1. Connect
    Client->>Server: 2. Request Actor Data
    Server->>Server: 3. Check Cache (Cache Miss)
    Server->>Extension: 4. Extension Call
    Extension->>Redis: 5. Redis Query
    Redis-->>Extension: 6. JSON Data
    Extension-->>Server: 7. Actor Data
    Server->>Server: 8. Store in Hot Cache
    Server-->>Client: 9. Secure Response
    Client->>Client: 10. Update Local Cache
```

### **2. Subsequent Data Access (Cache Hit)**

```mermaid
sequenceDiagram
    participant Client
    participant Server as Server (Hot Cache)
    participant Extension as Extension (Cold Storage)
    participant Redis as Redis (Database)

    Note over Client, Redis: 2. Subsequent Data Access (Cache Hit)

    Client->>Server: 1. Request Actor Data
    Server->>Server: 2. Check Cache (Cache Hit!)
    Server-->>Client: 3. Instant Response
    Client->>Client: 4. Update Local Cache
```

### **3. Data Update (Write-Through)**

```mermaid
sequenceDiagram
    participant Client
    participant Server as Server (Hot Cache)
    participant Extension as Extension (Cold Storage)
    participant Redis as Redis (Database)

    Note over Client, Redis: 3. Data Update (Write-Through)

    Client->>Server: 1. Action (Move, etc)
    Server->>Server: 2. Validate & Update Cache
    Server->>Extension: 3. Persist to Database
    Extension->>Redis: 4. Redis Update
    Redis-->>Extension: 5. Confirmation
    Extension-->>Server: 6. Success
    Server-->>Client: 7. Sync to All Clients
```

## 🚀 **Performance Characteristics**

### **Access Times**

- **Hot Cache (Server)**: `< 1ms` (HashMap lookup)
- **Cold Storage (Redis)**: `1-5ms` (Network + Redis)
- **Client Cache**: `< 0.1ms` (Local object access)

### **Cache Hit Ratios**

- **Hot Cache**: `~95%` (Active players)
- **Cold Storage**: `~5%` (New connections, cache misses)

### **Memory Usage**

- **Server Registry**: `~1KB per active player`
- **Client Cache**: `~500B per player object`
- **Redis**: `~2KB per player (persistent)`

## 🔒 **Security & Session Management**

```mermaid
flowchart TD
    subgraph SessionMgmt [SERVER-SIDE #40;Session MGT#41;]
        Conn[Player Connection] --> Token[Session Token Generation<br/>#40;Generated on server#41;]
        Token --> UID[UID Resolution<br/>#40;Steam UID mapping#41;]
        UID --> State[Player State Tracking<br/>#40;Tracked in Registry#41;]
        State --> Access[Data Access Authorized<br/>#40;Authorized via session#41;]
    end
```