# shenjai47/ninjasaga architecture

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

- Interactive diagram: https://gitdiagram.com/shenjai47/ninjasaga
- Repository: https://github.com/shenjai47/ninjasaga

## Overview

This repository is an offline Ninja Saga Flash private server: the player requests game content through a local HTTPS gateway, which routes AMF calls to reconstructed handlers and serves local SWFs. Missing SWFs can be cloned from donors or answered with stubs. Character state and extracted game tables support server responses, while separate bytecode patchers modify client SWFs. The main routing and fallback relationships are documented in the README; source excerpts show codec, state, data, clone, and stub responsibilities, but do not expose all handler calls.

Main entry points: [`server/index.js`](https://github.com/shenjai47/ninjasaga/blob/master/server/index.js) (Node Gateway), [`server/chardata.js`](https://github.com/shenjai47/ninjasaga/blob/master/server/chardata.js) (Character State), [`web/cdn/swf/latest`](https://github.com/shenjai47/ninjasaga/tree/master/web/cdn/swf/latest) (Local SWF Assets), [`web/cdn/swf/latest/swf/library`](https://github.com/shenjai47/ninjasaga/tree/master/web/cdn/swf/latest/swf/library) (Client SWFs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Local Gateway"]
  node_caddy["Caddy HTTPS"]
  node_node_gateway["Node Gateway<br/>[index.js]"]
  node_amf_codec["AMF Codec<br/>[amf.js]"]
end

subgraph group_game_logic["Game Responses"]
  node_response_handlers["AMF Handlers<br/>[index.js]"]
  node_character_state[("Character State<br/>[chardata.js]")]
  node_character_records[("Character Records<br/>[characters.json]")]
  node_game_tables["Game Data Tables"]
end

subgraph group_assets["Asset Serving"]
  node_asset_files[("Local SWF Assets")]
  node_asset_fallback["Missing Asset Fallback<br/>[index.js]"]
  node_swf_cloner["SWF Cloner<br/>[assetclone.js]"]
  node_swf_stub["SWF Stub<br/>[stub.js]"]
end

subgraph group_client_patches["Client Patches"]
  node_patch_tools["SWF Patch Tools"]
  node_library_patchers["Library Patchers"]
  node_patched_client[("Client SWFs")]
end

node_player(("Flash Player"))

node_player -->|"requests HTTPS"| node_caddy
node_caddy -->|"reverse proxies"| node_node_gateway
node_node_gateway -->|"decodes AMF"| node_amf_codec
node_node_gateway -->|"dispatches POST"| node_response_handlers
node_node_gateway -->|"serves GET"| node_asset_files
node_response_handlers -->|"uses character data"| node_character_state
node_character_state -.->|"persists state"| node_character_records
node_response_handlers -->|"uses game tables"| node_game_tables
node_node_gateway -->|"handles missing SWF"| node_asset_fallback
node_asset_fallback -->|"clones donor"| node_swf_cloner
node_asset_fallback -->|"creates fallback"| node_swf_stub
node_asset_fallback -->|"scans donors"| node_asset_files
node_patch_tools -.->|"patches bytecode"| node_patched_client
node_library_patchers -->|"patches library SWF"| node_patched_client

click node_node_gateway "https://github.com/shenjai47/ninjasaga/blob/master/server/index.js"
click node_amf_codec "https://github.com/shenjai47/ninjasaga/blob/master/server/amf.js"
click node_response_handlers "https://github.com/shenjai47/ninjasaga/blob/master/server/index.js"
click node_character_state "https://github.com/shenjai47/ninjasaga/blob/master/server/chardata.js"
click node_character_records "https://github.com/shenjai47/ninjasaga/blob/master/server/characters.json"
click node_game_tables "https://github.com/shenjai47/ninjasaga/tree/master/server"
click node_asset_files "https://github.com/shenjai47/ninjasaga/tree/master/web/cdn/swf/latest"
click node_asset_fallback "https://github.com/shenjai47/ninjasaga/blob/master/server/index.js"
click node_swf_cloner "https://github.com/shenjai47/ninjasaga/blob/master/server/assetclone.js"
click node_swf_stub "https://github.com/shenjai47/ninjasaga/blob/master/server/stub.js"
click node_patch_tools "https://github.com/shenjai47/ninjasaga/tree/master/server"
click node_library_patchers "https://github.com/shenjai47/ninjasaga/tree/master/web/cdn/swf/latest/swf/library"
click node_patched_client "https://github.com/shenjai47/ninjasaga/tree/master/web/cdn/swf/latest/swf/library"

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_caddy,node_node_gateway,node_amf_codec toneBlue
class node_response_handlers,node_character_state,node_character_records,node_game_tables toneAmber
class node_asset_files,node_asset_fallback,node_swf_cloner,node_swf_stub toneMint
class node_patch_tools,node_library_patchers,node_patched_client toneRose
class node_player toneIndigo
```

## Components

### Local Gateway

- **Caddy HTTPS**
- [Node Gateway](https://github.com/shenjai47/ninjasaga/blob/master/server/index.js): `server/index.js`
- [AMF Codec](https://github.com/shenjai47/ninjasaga/blob/master/server/amf.js): `server/amf.js`

### Game Responses

- [AMF Handlers](https://github.com/shenjai47/ninjasaga/blob/master/server/index.js): `server/index.js`
- [Character State](https://github.com/shenjai47/ninjasaga/blob/master/server/chardata.js): `server/chardata.js`
- [Character Records](https://github.com/shenjai47/ninjasaga/blob/master/server/characters.json): `server/characters.json`
- [Game Data Tables](https://github.com/shenjai47/ninjasaga/tree/master/server): `server`

### Asset Serving

- [Local SWF Assets](https://github.com/shenjai47/ninjasaga/tree/master/web/cdn/swf/latest): `web/cdn/swf/latest`
- [Missing Asset Fallback](https://github.com/shenjai47/ninjasaga/blob/master/server/index.js): `server/index.js`
- [SWF Cloner](https://github.com/shenjai47/ninjasaga/blob/master/server/assetclone.js): `server/assetclone.js`
- [SWF Stub](https://github.com/shenjai47/ninjasaga/blob/master/server/stub.js): `server/stub.js`

### Client Patches

- [SWF Patch Tools](https://github.com/shenjai47/ninjasaga/tree/master/server): `server`
- [Library Patchers](https://github.com/shenjai47/ninjasaga/tree/master/web/cdn/swf/latest/swf/library): `web/cdn/swf/latest/swf/library`
- [Client SWFs](https://github.com/shenjai47/ninjasaga/tree/master/web/cdn/swf/latest/swf/library): `web/cdn/swf/latest/swf/library`

### Other components

- **Flash Player**

## Connections

- Flash Player → Caddy HTTPS: requests HTTPS (evidence: `README.md`)
- Caddy HTTPS → Node Gateway: reverse proxies (evidence: `README.md`)
- Node Gateway → AMF Codec: decodes AMF (evidence: `server/index.js`)
- Node Gateway → AMF Handlers: dispatches POST (evidence: `README.md`)
- Node Gateway → Local SWF Assets: serves GET (evidence: `README.md`)
- AMF Handlers → Character State: uses character data (evidence: `server/index.js`)
- Character State → Character Records: persists state
- AMF Handlers → Game Data Tables: uses game tables (evidence: `server/index.js`)
- Node Gateway → Missing Asset Fallback: handles missing SWF (evidence: `README.md`)
- Missing Asset Fallback → SWF Cloner: clones donor (evidence: `server/index.js`)
- Missing Asset Fallback → SWF Stub: creates fallback (evidence: `server/index.js`)
- Missing Asset Fallback → Local SWF Assets: scans donors (evidence: `server/index.js`)
- SWF Patch Tools → Client SWFs: patches bytecode (evidence: `README.md`)
- Library Patchers → Client SWFs: patches library SWF (evidence: `web/cdn/swf/latest/swf/library/patch_ns_swf.py`)
