forge/README.md

# Forge Framework

**Forge** is a high-performance, production-ready framework for Arma 3 persistent game servers, built with Rust and Redis for optimal performance and reliability.

## Overview

Forge provides a complete solution for managing persistent player data, organizations, and game state in Arma 3 multiplayer environments. It combines the performance of Rust with the flexibility of Redis to deliver sub-millisecond response times while maintaining data consistency across server restarts.

### Key Features

- **🚀 High Performance**: Sub-millisecond data access through intelligent caching
- **🔒 Data Integrity**: Strict validation and type safety at every layer
- **🏗️ Clean Architecture**: Layered design following SOLID principles
- **📦 Modular Design**: Easy to extend with new entities and features
- **🔄 Real-time Sync**: Automatic state synchronization across all clients
- **💾 Persistent Storage**: Redis-backed storage with automatic failover
- **🧪 Testable**: Mock-friendly architecture for comprehensive testing

## Architecture

Forge follows a **layered architecture** pattern:

```mermaid
graph TD
    Extension[Extension Layer<br/>ArmA 3 Interface <---> Rust]
    Services[Services Layer<br/>#40;Business Logic#41;]
    Repositories[Repositories Layer<br/>#40;Data Persistence#41;]
    Models[Models Layer<br/>#40;Data Structures & Validation#41;]

    Extension --> Services
    Services --> Repositories
    Repositories --> Models
```

**Communication Flow**:
- **Clients** → Use events (`CBA_Events`) to communicate with server
- **Server** → Calls Rust extension via `callExtension`
- **Extension** → Manages Redis connection pool and data operations

For detailed architecture information, see [Diagram](Architecture_Diagram.md).

## Project Structure

```
forge/
├── arma/
│   ├── client/                 # Client-side SQF mod
│   │   ├── addons/
│   │   │   ├── main/           # Core initialization & config
│   │   │   ├── common/         # Shared utilities & helpers
│   │   │   ├── actor/          # Actor/player UI, class & events
│   │   │   ├── org/            # Organization UI, class & events
│   │   │   └── bank/           # Banking UI, class & events
│   │   ├── include/            # Header files
│   │   └── tools/              # Build tools
│   ├── server/
│   │   ├── addons/
│   │   │   ├── main/           # Core initialization & config
│   │   │   ├── common/         # Shared utilities & helpers
│   │   │   ├── actor/          # Actor/player Registry, Store & events
│   │   │   └── org/            # Organization Registry, Store & events
│   │   ├── include/            # Header files
│   │   ├── tools/              # Build tools
│   │   └── extension/          # Rust extension (Arma 3 interface)
│   │       ├── src/
│   │       │   ├── actor.rs    # Actor/player commands
│   │       │   ├── org.rs      # Organization commands
│   │       │   ├── redis/      # Redis operations module
│   │       │   └── adapters/   # Repository adapters
│   │       └── README.md
├── lib/
│   ├── models/                 # Data structures & validation
│   ├── repositories/           # Data persistence layer
│   ├── services/               # Business logic layer
│   ├── shared/                 # Common utilities & traits
│   └── README.md
└── FORGE_Architecture_Diagram.md
```

## Quick Start

### Prerequisites

- Rust 1.70+ with `cargo`
- Redis 6.0+
- HEMTT

1. Clone the repository from Gitea
2. Install HEMTT
The latest version of HEMTT can be installed by running:
```cmd
winget install hemtt
```

### Coding Guidelines
This mod follows the same coding guidelines as the ACE3 mod, which can be found [here](https://ace3.acemod.org/wiki/development/coding-guidelines).

### Building the Extension

```bash
# Build for release
cargo build --release

# The compiled extension will be at:
# target/release/forge_server.dll (Windows)
# target/release/forge_server.so (Linux)
```

### Configuration

Create `@forge_server/config.toml`:

```toml
[redis]
host = "127.0.0.1"
port = 6379
password = ""  # Optional
max_connections = 10
min_connections = 2
idle_timeout = 300
```

### SQF Usage

```sqf
// Create an actor
private _data = createHashMapFromArray [
    ["name", "John Doe"],
    ["bank", 1000],
    ["level", 1]
];
private _result = "forge_server" callExtension ["actor:create", [getPlayerUID player, toJSON _data]];

// Get actor data
private _result = "forge_server" callExtension ["actor:get", [getPlayerUID player]];
private _actorData = fromJSON (_result select 0);

// Update actor
private _update = createHashMapFromArray [["bank", 1500]];
"forge_server" callExtension ["actor:update", [getPlayerUID player, toJSON _update]];
```

## Core Modules

### Models
Defines strict data structures with built-in validation:
- `Actor`: Player data (stats, inventory, position)
- `Org`: Organization/clan data (members, roles, metadata)

[Documentation](lib/models/README.md)

### Repositories
Manages data persistence with Redis:
- Hash-based storage for structured data
- Set-based storage for collections
- Generic over Redis client implementations

[Documentation](lib/repositories/README.md)

### Services
Implements business logic and orchestration:
- Get-or-create patterns
- Data validation and transformation
- Complex workflows

[Documentation](lib/services/README.md)

### Extension
Arma 3 interface layer:
- Command routing and parsing
- Session management
- Error handling and logging

[Documentation](arma/server/extension/README.md)

### Client Mod
Client-side SQF addon that provides:
- **UI Components**: Player interfaces for inventory, organizations, banking
- **Event Handlers**: CBA event listeners for server communication
- **Optimistic Caching**: Local data caching for instant UI updates
- **State Management**: Client-side state synchronization
- **Input Validation**: Client-side validation before server requests

The client mod communicates with the server using **CBA Events**, ensuring:
- No direct extension calls from clients (security)
- Event-driven architecture for scalability
- Automatic state synchronization across all clients
- Reduced server load through client-side caching

## Available Commands

### Actor Commands
| Command | Description |
|---------|-------------|
| `actor:get` | Retrieve actor data by UID |
| `actor:create` | Create a new actor |
| `actor:update` | Update actor fields |
| `actor:exists` | Check if actor exists |
| `actor:delete` | Delete actor data |

### Organization Commands
| Command | Description |
|---------|-------------|
| `org:get` | Retrieve organization data |
| `org:create` | Create a new organization |
| `org:update` | Update organization fields |
| `org:exists` | Check if organization exists |
| `org:delete` | Delete organization |
| `org:add_member` | Add member to organization |
| `org:remove_member` | Remove member from organization |
| `org:get_members` | Get all organization members |

### Redis Operations
Direct Redis operations for advanced use cases:
- **Common**: Key-value operations (set, get, incr, decr, del)
- **Hash**: Structured data (hset, hget, hgetall, hdel)
- **List**: Ordered collections (lpush, rpush, lrange, lpop, rpop)
- **Set**: Unique collections (sadd, smembers, srem, sismember)

[Documentation](arma/server/extension/src/redis/README.md)

## Performance

- **Hot Cache (Server)**: < 1ms (HashMap lookup)
- **Cold Storage (Redis)**: 1-5ms (Network + Redis query)
- **Cache Hit Ratio**: ~95% for active players
- **Memory Usage**: ~1KB per active player (server), ~2KB per player (Redis)

## Contributing

We welcome contributions! Please see the contributing guides for each layer:

- [Extension Contributing Guide](arma/server/extension/README.md#contributing)
- [Services Contributing Guide](lib/services/README.md#contributing)
- [Repositories Contributing Guide](lib/repositories/README.md#contributing)
- [Models Contributing Guide](lib/models/README.md#contributing)
- [Library Contributing Guide](lib/README.md#contributing)
- [Adapter Contributing Guide](arma/server/extension/src/adapters/#contributing)

### Development Workflow

1. **Define Model**: Create data structure with validation
2. **Create Repository**: Implement persistence layer
3. **Build Service**: Add business logic
4. **Expose in Extension**: Create SQF-callable commands
5. **Test**: Verify each layer independently

## Error Handling

All commands return consistent error messages:

```sqf
private _result = "forge_server" callExtension ["actor:get", ["invalid_uid"]];
private _response = _result select 0;

if (_response find "Error:" == 0) then {
    diag_log format ["Operation failed: %1", _response];
} else {
    private _data = fromJSON _response;
    // Use data
};
```

## Logging

Logs are automatically created in `@forge_server/logs/`:
- `actor.log` - Actor operations
- `org.log` - Organization operations
- `redis.log` - Redis connection and operations
- `debug.log` - General debug information

## License

[Your License Here]

## Support

- **Issues**: [Gitea Issues](https://gitea.innovativedevsolutions.org/IDSolutions/forge/issues)
- **Documentation**: See individual module READMEs
- **Architecture**: [FORGE_Architecture_Diagram.md](FORGE_Architecture_Diagram.md)

## Roadmap

- [ ] Admin system
- [ ] Arsenal system
- [ ] Banking system
- [ ] Economy system
- [ ] Garage system
- [ ] Locker system
- [ ] Mission template

---

Built using **Rust**, **Redis**, and **Arma 3**