# av1la/dynamic-faction architecture

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

- Interactive diagram: https://gitdiagram.com/av1la/dynamic-faction
- Repository: https://github.com/av1la/dynamic-faction

## Overview

##### Project Type and Purpose
- This is an open-source Pawn library (“dynamic-faction”) for the SA-MP game mod. It provides a modular framework to manage factions/organizations in a multiplayer server: handling commands, data persistence, member roles, and in-game UI.

##### File Structure Analysis
- Top-level includes:
- commands.inc – parses and routes chat/console commands
- database.inc – abstracts MySQL/SQL operations for persistence
- header.inc & impl.inc – library’s public API and main implementation
- Subdirectories (each with its own header.inc + impl.inc):
- member/ – member enrollment, role assignments
- visual/ – UI rendering (dialogs & textdraws) for faction and member screens

##### Key README Insights
- Features: dialog/textdraw UI, faction & member management, vehicle management
- Discontinued but still a complete reference architecture for mod scripting

a. Main Components:
1. SA-MP Server (runtime host)
2. dynamic-faction Library
– Command Handler (commands.inc)
– Database Layer (database.inc)
– Faction Manager (faction/header.inc + impl.inc)
– Member Manager (member/header.inc + impl.inc)
– Visual Layer (visual/*.inc)
3. MySQL Database (external persistence)
4. SA-MP API (native calls for dialogs, textdraws, vehicles)
b. Interactions:
– Players issue commands → Command Handler
– Handler calls Faction/Member Manager APIs
– Managers read/write via Database Layer → MySQL
– Updated data flows to Visual Layer → SA-MP API renders UI
– Vehicle management modules interact with SA-MP API directly
c. Architectural Patterns:
– Layered architecture (Command → Business Logic → Data Access → Presentation)
– Separation of interface (header.inc) vs implementation (impl.inc)
– Single-responsibility per module (faction vs member vs visual)
d. Technologies & Libraries:
– Pawn scripting for SA-MP
– MySQL plugin for persistence
– SA-MP dialog and textdraw APIs

##### Detail Checklist
- Modules: Command Handler, Faction Manager, Member Manager, Visual Layer, Database Layer
- External Dependencies: SA-MP Server, MySQL Database, SA-MP API
- Data Stores: persistent tables for factions, members, vehicles
- Flows: Command → Business Logic → Data Access → UI Rendering

## Diagram (Mermaid)

```mermaid
flowchart TD
    SMPServer["SA-MP Server (Runtime Host)"]:::external

    subgraph "dynamic-faction Library"
        PublicAPI["Public API (header.inc)"]:::coreLogic
        Impl["Library Implementation (impl.inc)"]:::coreLogic
        CommandHandler["Command Handler (commands.inc)"]:::coreLogic

        subgraph "Faction Module"
            FHeader["Interface (faction/header.inc)"]:::coreLogic
            FImpl["Implementation (faction/impl.inc)"]:::coreLogic
        end

        subgraph "Member Module"
            MHeader["Interface (member/header.inc)"]:::coreLogic
            MImpl["Implementation (member/impl.inc)"]:::coreLogic
        end

        subgraph "Visual Layer"
            VFaction["Faction UI (visual/faction.inc)"]:::ui
            VMember["Member UI (visual/member.inc)"]:::ui
        end

        DatabaseLayer["Database Layer (database.inc)"]:::infra
    end

    MySQLDB["MySQL Database"]:::infra
    SAMPAAPI["SA-MP API"]:::external

    SMPServer -->|"OnCommand"| CommandHandler
    CommandHandler -->|"uses API"| PublicAPI
    PublicAPI --> Impl
    CommandHandler --> Impl

    Impl --> FHeader
    FHeader --> FImpl
    Impl --> MHeader
    MHeader --> MImpl

    FImpl --> DatabaseLayer
    MImpl --> DatabaseLayer
    DatabaseLayer -->|"SELECT/INSERT"| MySQLDB

    Impl --> VFaction
    Impl --> VMember
    VFaction -->|"ShowDialog/TextDraw"| SAMPAAPI
    VMember -->|"ShowDialog/TextDraw"| SAMPAAPI
    Impl -->|"Vehicle API"| SAMPAAPI

    click CommandHandler "https://github.com/av1la/dynamic-faction/blob/master/commands.inc"
    click DatabaseLayer "https://github.com/av1la/dynamic-faction/blob/master/database.inc"
    click PublicAPI "https://github.com/av1la/dynamic-faction/blob/master/header.inc"
    click Impl "https://github.com/av1la/dynamic-faction/blob/master/impl.inc"
    click FHeader "https://github.com/av1la/dynamic-faction/blob/master/faction/header.inc"
    click FImpl "https://github.com/av1la/dynamic-faction/blob/master/faction/impl.inc"
    click MHeader "https://github.com/av1la/dynamic-faction/blob/master/member/header.inc"
    click MImpl "https://github.com/av1la/dynamic-faction/blob/master/member/impl.inc"
    click VFaction "https://github.com/av1la/dynamic-faction/blob/master/visual/faction.inc"
    click VMember "https://github.com/av1la/dynamic-faction/blob/master/visual/member.inc"

    classDef coreLogic fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef infra fill:#90EE90,stroke:#333,stroke-width:1px
    classDef ui fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
