# remnawave/node architecture

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

- Interactive diagram: https://gitdiagram.com/remnawave/node
- Repository: https://github.com/remnawave/node

## Overview

Remnawave Node is the panel-managed runtime for a Remnawave server node. The main workflow is panel requests entering the node’s HTTP API, then reaching user-management, statistics, plugin, or Xray operations and returning responses. Xray startup also gathers node/interface data, synchronizes integrations, builds configuration, and controls the Xray process. The graph preserves documented API capabilities and major subsystems; several service internals were not sampled, so their relationships are omitted unless the source index or excerpts establish them.

Main entry points: [`src/modules/xray-core/xray.service.ts`](https://github.com/remnawave/node/blob/main/src/modules/xray-core/xray.service.ts) (Xray Lifecycle), [`src/modules/_plugin/services/nft.service.ts`](https://github.com/remnawave/node/blob/main/src/modules/_plugin/services/nft.service.ts) (Firewall Rules), [`src/modules/_plugin/plugin.controller.ts`](https://github.com/remnawave/node/blob/main/src/modules/_plugin/plugin.controller.ts) (Plugin API), [`src/main.ts`](https://github.com/remnawave/node/blob/main/src/main.ts) (HTTP Bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Node Runtime"]
  node_entry["HTTP Bootstrap<br/>[main.ts]"]
  node_app["Application Modules<br/>[app.module.ts]"]
  node_internal["Internal Operations"]
  node_integrations["Integrations"]
end

subgraph group_api["Panel API"]
  node_routes["API Route Contract<br/>[routes.ts]"]
  node_handler["User Operations<br/>[handler.service.ts]"]
  node_xray_api["Xray API<br/>[xray.controller.ts]"]
  node_plugins_api["Plugin API"]
end

subgraph group_xray["Xray Core"]
  node_xray["Xray Lifecycle<br/>[xray.service.ts]"]
  node_core_loader["Core Loader"]
  node_geodata["Geodata<br/>[geodata.service.ts]"]
  node_process["Xray Process"]
end

subgraph group_plugins["Plugins"]
  node_plugin_service["Plugin Management<br/>[plugin.service.ts]"]
  node_nft["Firewall Rules<br/>[nft.service.ts]"]
  node_plugin_state["Plugin State"]
  node_drop_event["Connection Drop Event"]
end

subgraph group_observability["Stats and Data"]
  node_stats["Stats Operations<br/>[stats.service.ts]"]
  node_geocheck["Geo Check"]
  node_network_stats["Network Stats"]
  node_asn["ASN Prefix Lookup"]
  node_asn_store[("ASN LMDB")]
end

node_panel(("Remnawave Panel"))

node_panel -.->|"requests"| node_entry
node_entry -->|"bootstraps"| node_app
node_panel -->|"uses endpoints"| node_routes
node_handler -->|"calls"| node_internal
node_xray_api -->|"dispatches"| node_xray
node_xray -->|"uses"| node_core_loader
node_xray -->|"uses"| node_geodata
node_xray -->|"controls"| node_process
node_xray -->|"calls"| node_internal
node_xray -->|"queries"| node_network_stats
node_xray -.->|"synchronizes"| node_integrations
node_plugins_api -->|"dispatches"| node_plugin_service
node_plugins_api -->|"dispatches"| node_nft
node_nft -->|"updates"| node_plugin_state
node_nft -->|"publishes"| node_drop_event
node_drop_event -->|"uses"| node_plugin_state
node_stats -.->|"queries"| node_network_stats
node_asn -.->|"reads"| node_asn_store

click node_entry "https://github.com/remnawave/node/blob/main/src/main.ts"
click node_app "https://github.com/remnawave/node/blob/main/src/app.module.ts"
click node_routes "https://github.com/remnawave/node/blob/main/libs/contract/api/routes.ts"
click node_handler "https://github.com/remnawave/node/blob/main/src/modules/handler/handler.service.ts"
click node_stats "https://github.com/remnawave/node/blob/main/src/modules/stats/stats.service.ts"
click node_geocheck "https://github.com/remnawave/node/blob/main/src/modules/stats/geocheck.service.ts"
click node_xray_api "https://github.com/remnawave/node/blob/main/src/modules/xray-core/xray.controller.ts"
click node_xray "https://github.com/remnawave/node/blob/main/src/modules/xray-core/xray.service.ts"
click node_core_loader "https://github.com/remnawave/node/blob/main/src/modules/xray-core/core-loader.service.ts"
click node_geodata "https://github.com/remnawave/node/blob/main/src/modules/xray-core/geodata.service.ts"
click node_process "https://github.com/remnawave/node/blob/main/src/modules/xray-core/xray-process.service.ts"
click node_internal "https://github.com/remnawave/node/blob/main/src/modules/internal/internal.service.ts"
click node_plugins_api "https://github.com/remnawave/node/blob/main/src/modules/_plugin/plugin.controller.ts"
click node_plugin_service "https://github.com/remnawave/node/blob/main/src/modules/_plugin/plugin.service.ts"
click node_nft "https://github.com/remnawave/node/blob/main/src/modules/_plugin/services/nft.service.ts"
click node_plugin_state "https://github.com/remnawave/node/blob/main/src/modules/_plugin/services/plugin-state.service.ts"
click node_drop_event "https://github.com/remnawave/node/blob/main/src/modules/_plugin/events/drop-connections/drop-connections.handler.ts"
click node_integrations "https://github.com/remnawave/node/blob/main/src/integration-modules/integrations.service.ts"
click node_network_stats "https://github.com/remnawave/node/blob/main/src/modules/network-stats/network-stats.service.ts"
click node_asn "https://github.com/remnawave/node/blob/main/src/modules/asn-lmdb/asn-lmdb.service.ts"
click node_asn_store "https://github.com/remnawave/node/blob/main/src/modules/asn-lmdb/asn-lmdb.service.ts"

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_entry,node_app,node_internal,node_integrations toneBlue
class node_routes,node_handler,node_xray_api,node_plugins_api toneAmber
class node_xray,node_core_loader,node_geodata,node_process toneMint
class node_plugin_service,node_nft,node_plugin_state,node_drop_event toneRose
class node_stats,node_geocheck,node_network_stats,node_asn,node_asn_store,node_panel toneIndigo
```

## Components

### Node Runtime

- [HTTP Bootstrap](https://github.com/remnawave/node/blob/main/src/main.ts): `src/main.ts`
- [Application Modules](https://github.com/remnawave/node/blob/main/src/app.module.ts): `src/app.module.ts`
- [Internal Operations](https://github.com/remnawave/node/blob/main/src/modules/internal/internal.service.ts): `src/modules/internal/internal.service.ts`
- [Integrations](https://github.com/remnawave/node/blob/main/src/integration-modules/integrations.service.ts): `src/integration-modules/integrations.service.ts`

### Panel API

- [API Route Contract](https://github.com/remnawave/node/blob/main/libs/contract/api/routes.ts): `libs/contract/api/routes.ts`
- [User Operations](https://github.com/remnawave/node/blob/main/src/modules/handler/handler.service.ts): `src/modules/handler/handler.service.ts`
- [Xray API](https://github.com/remnawave/node/blob/main/src/modules/xray-core/xray.controller.ts): `src/modules/xray-core/xray.controller.ts`
- [Plugin API](https://github.com/remnawave/node/blob/main/src/modules/_plugin/plugin.controller.ts): `src/modules/_plugin/plugin.controller.ts`

### Xray Core

- [Xray Lifecycle](https://github.com/remnawave/node/blob/main/src/modules/xray-core/xray.service.ts): `src/modules/xray-core/xray.service.ts`
- [Core Loader](https://github.com/remnawave/node/blob/main/src/modules/xray-core/core-loader.service.ts): `src/modules/xray-core/core-loader.service.ts`
- [Geodata](https://github.com/remnawave/node/blob/main/src/modules/xray-core/geodata.service.ts): `src/modules/xray-core/geodata.service.ts`
- [Xray Process](https://github.com/remnawave/node/blob/main/src/modules/xray-core/xray-process.service.ts): `src/modules/xray-core/xray-process.service.ts`

### Plugins

- [Plugin Management](https://github.com/remnawave/node/blob/main/src/modules/_plugin/plugin.service.ts): `src/modules/_plugin/plugin.service.ts`
- [Firewall Rules](https://github.com/remnawave/node/blob/main/src/modules/_plugin/services/nft.service.ts): `src/modules/_plugin/services/nft.service.ts`
- [Plugin State](https://github.com/remnawave/node/blob/main/src/modules/_plugin/services/plugin-state.service.ts): `src/modules/_plugin/services/plugin-state.service.ts`
- [Connection Drop Event](https://github.com/remnawave/node/blob/main/src/modules/_plugin/events/drop-connections/drop-connections.handler.ts): `src/modules/_plugin/events/drop-connections/drop-connections.handler.ts`

### Stats and Data

- [Stats Operations](https://github.com/remnawave/node/blob/main/src/modules/stats/stats.service.ts): `src/modules/stats/stats.service.ts`
- [Geo Check](https://github.com/remnawave/node/blob/main/src/modules/stats/geocheck.service.ts): `src/modules/stats/geocheck.service.ts`
- [Network Stats](https://github.com/remnawave/node/blob/main/src/modules/network-stats/network-stats.service.ts): `src/modules/network-stats/network-stats.service.ts`
- [ASN Prefix Lookup](https://github.com/remnawave/node/blob/main/src/modules/asn-lmdb/asn-lmdb.service.ts): `src/modules/asn-lmdb/asn-lmdb.service.ts`
- [ASN LMDB](https://github.com/remnawave/node/blob/main/src/modules/asn-lmdb/asn-lmdb.service.ts): `src/modules/asn-lmdb/asn-lmdb.service.ts`

### Other components

- **Remnawave Panel**

## Connections

- Remnawave Panel → HTTP Bootstrap: requests
- HTTP Bootstrap → Application Modules: bootstraps (evidence: `src/main.ts`)
- Remnawave Panel → API Route Contract: uses endpoints (evidence: `libs/contract/api/routes.ts`)
- User Operations → Internal Operations: calls (evidence: `src/modules/handler/handler.service.ts`)
- Xray API → Xray Lifecycle: dispatches (evidence: `src/modules/xray-core/xray.controller.ts`)
- Xray Lifecycle → Core Loader: uses (evidence: `src/modules/xray-core/xray.service.ts`)
- Xray Lifecycle → Geodata: uses (evidence: `src/modules/xray-core/xray.service.ts`)
- Xray Lifecycle → Xray Process: controls (evidence: `src/modules/xray-core/xray.service.ts`)
- Xray Lifecycle → Internal Operations: calls (evidence: `src/modules/xray-core/xray.service.ts`)
- Xray Lifecycle → Network Stats: queries (evidence: `src/modules/xray-core/xray.service.ts`)
- Xray Lifecycle → Integrations: synchronizes
- Plugin API → Plugin Management: dispatches (evidence: `src/modules/_plugin/plugin.controller.ts`)
- Plugin API → Firewall Rules: dispatches (evidence: `src/modules/_plugin/plugin.controller.ts`)
- Firewall Rules → Plugin State: updates (evidence: `src/modules/_plugin/services/nft.service.ts`)
- Firewall Rules → Connection Drop Event: publishes (evidence: `src/modules/_plugin/services/nft.service.ts`)
- Connection Drop Event → Plugin State: uses (evidence: `src/modules/_plugin/events/drop-connections/drop-connections.handler.ts`)
- Stats Operations → Network Stats: queries
- ASN Prefix Lookup → ASN LMDB: reads (evidence: `src/modules/asn-lmdb/asn-lmdb.service.ts`)
