forge/Architecture_Diagram.md

Forge Architecture & Data Flow Diagram

🏗️ System Architecture Overview

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

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)

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)

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

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