# nik-potokar/ninja-saga-private-server architecture

> Architecture diagram of the GitHub repository nik-potokar/ninja-saga-private-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nik-potokar/ninja-saga-private-server
- Repository: https://github.com/nik-potokar/ninja-saga-private-server

## Overview

Ninja Saga Private Server is a Laravel-backed game server with an admin panel and optional live PvP and chat services. The main player flow is the custom client sending AMF requests, which the server handles through gameplay services and persistent game state before returning game data or rewards. Admins manage accounts and game content through Filament. Clan and crew APIs provide distinct social and competitive features. The README documents chat and PvP capabilities, but chat implementation files are absent from the supplied tree; several other runtime relationships are therefore left unconnected rather than inferred.

Main entry points: [`Database/Laragon/ninjasage/app/Models/Character.php`](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Models/Character.php) (Character state), [`Database/Laragon/ninjasage/app/Services/Amf/Concerns/ValidatesSession.php`](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Services/Amf/Concerns/ValidatesSession.php) (Session validation), [`Database/Laragon/ninjasage/app/Services/Amf/PetService/QueryService.php`](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Services/Amf/PetService/QueryService.php) (Pet queries), [`Database/Laragon/ninjasage/app/Services/Amf/DragonHuntEventService.php`](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Services/Amf/DragonHuntEventService.php) (Event rewards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["Game Protocol"]
  node_amf_entry["AMF entry<br/>[index.php]"]
  node_amf_server["SabreAMF server<br/>[Server.php]"]
  node_session_guard["Session validation"]
end

subgraph group_gameplay["Player Gameplay"]
  node_character_game["Character gameplay<br/>[ShopService.php]"]
  node_pets["Pet queries<br/>[QueryService.php]"]
  node_talents["Talent queries<br/>[QueryService.php]"]
  node_senjutsu["Senjutsu queries<br/>[QueryService.php]"]
  node_events["Event rewards"]
end

subgraph group_social["Social Competition"]
  node_clan_api["Clan API"]
  node_crew_api["Crew API"]
  node_pvp_server["Live PvP<br/>[RoomManager.js]"]
  node_chat_service["Live chat"]
end

subgraph group_admin["Administration"]
  node_filament["Admin panel"]
  node_admin_tools["Game settings<br/>[ShopManager.php]"]
end

subgraph group_state["Persistent State"]
  node_character_data[("Character state<br/>[Character.php]")]
  node_item_data[("Item catalog<br/>[Item.php]")]
  node_pet_data[("Pet catalog<br/>[Pet.php]")]
  node_skill_data[("Skill catalog<br/>[Skill.php]")]
  node_character_items[("Character inventory<br/>[CharacterItem.php]")]
end

node_player(("Game player"))
node_client["Custom client"]
node_mysql[("MySQL database")]

node_player -->|"plays through"| node_client
node_client -.->|"sends game requests"| node_amf_entry
node_amf_entry -->|"loads"| node_amf_server
node_amf_server -.->|"dispatches"| node_character_game
node_character_game -->|"validates session"| node_session_guard
node_pets -->|"validates session"| node_session_guard
node_talents -->|"validates session"| node_session_guard
node_senjutsu -->|"validates session"| node_session_guard
node_events -->|"validates session"| node_session_guard
node_pets -->|"reads and updates"| node_character_data
node_pets -->|"reads"| node_pet_data
node_talents -->|"reads"| node_character_data
node_senjutsu -->|"reads"| node_character_data
node_events -->|"updates rewards"| node_character_data
node_events -->|"reads and writes"| node_character_items
node_clan_api -->|"reads"| node_character_data
node_crew_api -->|"reads"| node_character_data
node_client -.->|"uses clan features"| node_clan_api
node_client -.->|"uses crew features"| node_crew_api
node_client -.->|"connects for PvP"| node_pvp_server
node_client -.->|"connects for chat"| node_chat_service
node_filament -.->|"manages game data"| node_admin_tools
node_admin_tools -->|"manages catalog"| node_item_data
node_admin_tools -->|"reads and updates"| node_character_data
node_character_data -.->|"persists in"| node_mysql
node_item_data -.->|"persists in"| node_mysql
node_pet_data -.->|"persists in"| node_mysql
node_skill_data -.->|"persists in"| node_mysql
node_character_items -.->|"persists in"| node_mysql

click node_amf_entry "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/index.php"
click node_amf_server "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/ThirdParty/SabreAMF/Server.php"
click node_character_game "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Services/Amf/CharacterService/ShopService.php"
click node_pets "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Services/Amf/PetService/QueryService.php"
click node_talents "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Services/Amf/TalentService/QueryService.php"
click node_senjutsu "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Services/Amf/SenjutsuService/QueryService.php"
click node_events "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Services/Amf/DragonHuntEventService.php"
click node_session_guard "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Services/Amf/Concerns/ValidatesSession.php"
click node_clan_api "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Http/Controllers/ClanApiController.php"
click node_crew_api "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Http/Controllers/CrewApiController.php"
click node_pvp_server "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/pvp-server/src/RoomManager.js"
click node_filament "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Filament/Resources/Characters/CharacterResource.php"
click node_admin_tools "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Filament/Pages/ShopManager.php"
click node_character_data "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Models/Character.php"
click node_item_data "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Models/Item.php"
click node_pet_data "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Models/Pet.php"
click node_skill_data "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Models/Skill.php"
click node_character_items "https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Models/CharacterItem.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_amf_entry,node_amf_server,node_session_guard,node_client toneBlue
class node_character_game,node_pets,node_talents,node_senjutsu,node_events,node_mysql toneAmber
class node_clan_api,node_crew_api,node_pvp_server,node_chat_service toneMint
class node_filament,node_admin_tools toneRose
class node_character_data,node_item_data,node_pet_data,node_skill_data,node_character_items,node_player toneIndigo
```

## Components

### Game Protocol

- [AMF entry](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/index.php): `Database/Laragon/index.php`
- [SabreAMF server](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/ThirdParty/SabreAMF/Server.php): `Database/Laragon/ninjasage/app/ThirdParty/SabreAMF/Server.php`
- [Session validation](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Services/Amf/Concerns/ValidatesSession.php): `Database/Laragon/ninjasage/app/Services/Amf/Concerns/ValidatesSession.php`

### Player Gameplay

- [Character gameplay](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Services/Amf/CharacterService/ShopService.php): `Database/Laragon/ninjasage/app/Services/Amf/CharacterService/ShopService.php`
- [Pet queries](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Services/Amf/PetService/QueryService.php): `Database/Laragon/ninjasage/app/Services/Amf/PetService/QueryService.php`
- [Talent queries](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Services/Amf/TalentService/QueryService.php): `Database/Laragon/ninjasage/app/Services/Amf/TalentService/QueryService.php`
- [Senjutsu queries](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Services/Amf/SenjutsuService/QueryService.php): `Database/Laragon/ninjasage/app/Services/Amf/SenjutsuService/QueryService.php`
- [Event rewards](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Services/Amf/DragonHuntEventService.php): `Database/Laragon/ninjasage/app/Services/Amf/DragonHuntEventService.php`

### Social Competition

- [Clan API](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Http/Controllers/ClanApiController.php): `Database/Laragon/ninjasage/app/Http/Controllers/ClanApiController.php`
- [Crew API](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Http/Controllers/CrewApiController.php): `Database/Laragon/ninjasage/app/Http/Controllers/CrewApiController.php`
- [Live PvP](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/pvp-server/src/RoomManager.js): `Database/Laragon/ninjasage/pvp-server/src/RoomManager.js`
- **Live chat**

### Administration

- [Admin panel](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Filament/Resources/Characters/CharacterResource.php): `Database/Laragon/ninjasage/app/Filament/Resources/Characters/CharacterResource.php`
- [Game settings](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Filament/Pages/ShopManager.php): `Database/Laragon/ninjasage/app/Filament/Pages/ShopManager.php`

### Persistent State

- [Character state](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Models/Character.php): `Database/Laragon/ninjasage/app/Models/Character.php`
- [Item catalog](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Models/Item.php): `Database/Laragon/ninjasage/app/Models/Item.php`
- [Pet catalog](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Models/Pet.php): `Database/Laragon/ninjasage/app/Models/Pet.php`
- [Skill catalog](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Models/Skill.php): `Database/Laragon/ninjasage/app/Models/Skill.php`
- [Character inventory](https://github.com/nik-potokar/ninja-saga-private-server/blob/main/Database/Laragon/ninjasage/app/Models/CharacterItem.php): `Database/Laragon/ninjasage/app/Models/CharacterItem.php`

### Other components

- **Game player**
- **Custom client**
- **MySQL database**

## Connections

- Game player → Custom client: plays through (evidence: `README.md`)
- Custom client → AMF entry: sends game requests
- AMF entry → SabreAMF server: loads (evidence: `Database/Laragon/index.php`)
- SabreAMF server → Character gameplay: dispatches (evidence: `Database/Laragon/ninjasage/app/Services/Amf/CharacterService/ShopService.php`)
- Character gameplay → Session validation: validates session (evidence: `Database/Laragon/ninjasage/app/Services/Amf/CharacterService/ShopService.php`)
- Pet queries → Session validation: validates session (evidence: `Database/Laragon/ninjasage/app/Services/Amf/PetService/QueryService.php`)
- Talent queries → Session validation: validates session (evidence: `Database/Laragon/ninjasage/app/Services/Amf/TalentService/QueryService.php`)
- Senjutsu queries → Session validation: validates session (evidence: `Database/Laragon/ninjasage/app/Services/Amf/SenjutsuService/QueryService.php`)
- Event rewards → Session validation: validates session (evidence: `Database/Laragon/ninjasage/app/Services/Amf/DragonHuntEventService.php`)
- Pet queries → Character state: reads and updates (evidence: `Database/Laragon/ninjasage/app/Services/Amf/PetService/QueryService.php`)
- Pet queries → Pet catalog: reads (evidence: `Database/Laragon/ninjasage/app/Services/Amf/PetService/QueryService.php`)
- Talent queries → Character state: reads (evidence: `Database/Laragon/ninjasage/app/Services/Amf/TalentService/QueryService.php`)
- Senjutsu queries → Character state: reads (evidence: `Database/Laragon/ninjasage/app/Services/Amf/SenjutsuService/QueryService.php`)
- Event rewards → Character state: updates rewards (evidence: `Database/Laragon/ninjasage/app/Services/Amf/DragonHuntEventService.php`)
- Event rewards → Character inventory: reads and writes (evidence: `Database/Laragon/ninjasage/app/Services/Amf/DragonHuntEventService.php`)
- Clan API → Character state: reads (evidence: `Database/Laragon/ninjasage/app/Http/Controllers/ClanApiController.php`)
- Crew API → Character state: reads (evidence: `Database/Laragon/ninjasage/app/Http/Controllers/CrewApiController.php`)
- Custom client → Clan API: uses clan features (evidence: `README.md`)
- Custom client → Crew API: uses crew features (evidence: `README.md`)
- Custom client → Live PvP: connects for PvP (evidence: `README.md`)
- Custom client → Live chat: connects for chat (evidence: `README.md`)
- Admin panel → Game settings: manages game data (evidence: `README.md`)
- Game settings → Item catalog: manages catalog (evidence: `Database/Laragon/ninjasage/app/Filament/Pages/ShopManager.php`)
- Game settings → Character state: reads and updates (evidence: `Database/Laragon/ninjasage/app/Filament/Pages/ShopManager.php`)
- Character state → MySQL database: persists in (evidence: `README.md`)
- Item catalog → MySQL database: persists in (evidence: `README.md`)
- Pet catalog → MySQL database: persists in (evidence: `README.md`)
- Skill catalog → MySQL database: persists in (evidence: `README.md`)
- Character inventory → MySQL database: persists in (evidence: `README.md`)