# amyrahmady/sampvoice architecture

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

- Interactive diagram: https://gitdiagram.com/amyrahmady/sampvoice
- Repository: https://github.com/amyrahmady/sampvoice

## Overview

##### Main Components
- Client Module:
- All client code lives in the “client” directory, including source files for handling streams (global streams, local streams, voice packets, control packets, etc.).
- Contains specific integrations for audio (with include/audio for BASS and Opus) and game hooks (include/game and include/samp for integrating with SA-MP).
- The client is built using CMake (client/CMakeLists.txt) and has resources such as shaders and the plugin installer.
- Server Module:
- Located in the “server” directory; it processes incoming control packets, manages dynamic and static streams (for objects, players, vehicles, etc.), and handles network communication (via the “NetHandler” and RakNet-based modules).
- Also built via CMake (server/CMakeLists.txt) and includes its own set of network and utility files.
- Shared/Utility Libraries:
- The “lib” directory and subdirectories (e.g., “omp-net” and “omp-sdk”) contain shared functionality that might be used by both client and server.
- External Dependencies:
- Dependencies on audio libraries (BASS, BASS_FX, Opus) and networking libraries (RakNet).
- Additional UI and debug functionality supported by ImGui (in client/include/imgui).
- Build and Deployment:
- CMakeLists.txt at the root and in subdirectories handle the building for both Win32 and Linux targets.
- CI configuration is present in the “.github” directory, which is relevant for continuous integration flows.

##### Relationships and Interactions
- The Client and Server interact using network communication protocols (likely built on RakNet).
- The client handles voice capture, key events (activation and deactivation of streams), and routing of voice packets to the server.
- The server receives these voice packets, processes them (e.g., routing them to the appropriate streams whether global or local), and sends them out to other players.
- Both sides integrate with a set of shared utility libraries (logging, resource management, timer utilities) ensuring a consistent approach.
- The plugin relies on the SA-MP / open.mp game engine’s hooks; thus the integration layers (modules in client/include/samp and client/include/game) are critical components.

##### Important Architectural Patterns
- Modular Design: Clear separation of responsibilities between client and server code.
- Plugin and SDK Pattern: The client-side code is a “plugin” that is loaded into the GTA San Andreas executable to hook into game events and manage audio streams.
- Network Messaging & Real-Time Communications: Use of control packets, voice packets, and stream management to route audio among players.
- Utilization of External Libraries: Wrapping over external audio (BASS/Opus) and networking (RakNet) libraries to provide a higher-level SDK API.
- CMake-Based Build System: Providing cross-platform build instructions.

##### Relevant Technologies
- C/C++ as the programming language with a heavy use of header and source (.cpp/.h) file separation.
- Audio processing libraries: BASS (for audio output/effects) and Opus (for codec functionality).
- RakNet is the underlying network library for handling connections and messaging.
- ImGui for any in-game overlays or debug UIs.
- CI/CD pipelines managed via GitHub Actions (see “.github/workflows/build.yml”).
- The Pawn scripting language interface is enabled via custom headers and type systems.

##### Elements
- Clear Labels: Components such as “Client Voice Plugin”, “Server Voice Manager”, “RakNet Communication Layer”, “Audio Library Integration (BASS/Opus)”, “Utility Libraries”, and “Build/Deployment (CMake, GitHub CI)” should be clearly marked.
- Grouping: Separate modules into logical clusters like “Game Integration/Plugin”, “Network Communication”, “Audio Processing”, and “Build/CI”.

- The client-side architecture (handling game input, voice capture, stream management, integration with SA-MP hooks, and external audio libraries).
- The server-side architecture (control packet handling, dynamic allocation of streams, network routing, and integration with external libraries).
- The communication flow between these two major components, and the way each integrates with shared utility and external dependencies.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Client Side"
        A["Client Voice Plugin"]:::client
        B["Audio Library Integration (BASS/Opus)"]:::external
        C["Game Integration Hooks (SA-MP/open.mp)"]:::external
        D["UI and Debug (ImGui)"]:::external
        E["RakNet Communication Layer"]:::external
    end

    subgraph "Server Side"
        F["Server Voice Manager"]:::server
    end

    subgraph "Shared/Utility Libraries"
        G["Utility Libraries (omp-net, omp-sdk)"]:::lib
    end

    subgraph "Build and Deployment"
        H["Build System (CMake) & CI"]:::build
    end

    A -->|"uses"| B
    A -->|"integrates"| C
    A -->|"renders"| D
    A -->|"sendsVia"| E
    E -->|"delivers"| F
    A -.->|"sharedUtils"| G
    F -.->|"sharedUtils"| G
    H -->|"builds"| A
    H -->|"builds"| F
    H -->|"builds"| G
    H -->|"builds"| E

    click A "https://github.com/amyrahmady/sampvoice/blob/master/client/CMakeLists.txt"
    click B "https://github.com/amyrahmady/sampvoice/tree/master/client/include/audio"
    click C "https://github.com/amyrahmady/sampvoice/tree/master/client/include/samp"
    click D "https://github.com/amyrahmady/sampvoice/tree/master/client/include/imgui"
    click E "https://github.com/amyrahmady/sampvoice/tree/master/client/include/raknet"
    click F "https://github.com/amyrahmady/sampvoice/blob/master/server/CMakeLists.txt"
    click G "https://github.com/amyrahmady/sampvoice/tree/master/lib"
    click H "https://github.com/amyrahmady/sampvoice/blob/master/.github/workflows/build.yml"

    classDef client fill:#c7e9ff,stroke:#333,stroke-width:2px;
    classDef server fill:#ffcccb,stroke:#333,stroke-width:2px;
    classDef lib fill:#d3ffd3,stroke:#333,stroke-width:2px;
    classDef build fill:#fdfd96,stroke:#333,stroke-width:2px;
    classDef external fill:#f0e68c,stroke:#333,stroke-width:2px;
```
