# achmad-firdaus/node-shield architecture

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

- Interactive diagram: https://gitdiagram.com/achmad-firdaus/node-shield
- Repository: https://github.com/achmad-firdaus/node-shield

## Overview

Node Shield is a Node.js runtime attack-protection library with standalone demo servers and a dashboard. The main workflow is an incoming request passing through middleware, parameter checks, blocking or continuation, and attack logging; operators then inspect attack history and analytics in the dashboard or CLI. The README also documents eight detection categories, IP tracking, brute-force detection, and severity analytics. Sampled excerpts show the middleware, storage, and dashboard responsibilities; some internal wiring and unsampled detection details are therefore left unspecified.

Main entry points: [`index.js`](https://github.com/achmad-firdaus/node-shield/blob/main/index.js) (Express Middleware), [`shield.js`](https://github.com/achmad-firdaus/node-shield/blob/main/shield.js) (Attack Logging), [`app-standalone.js`](https://github.com/achmad-firdaus/node-shield/blob/main/app-standalone.js) (Dashboard API), [`app.js`](https://github.com/achmad-firdaus/node-shield/blob/main/app.js) (Express Demo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Application Integration"]
  node_expressapp["Express Demo<br/>[app.js]"]
  node_standalone["Standalone Server<br/>[app-standalone.js]"]
  node_package["Package API<br/>[index.js]"]
end

subgraph group_protection["Request Protection"]
  node_middleware["Express Middleware<br/>[index.js]"]
  node_detection["Attack Detection<br/>[shield.js]"]
  node_iptracking["IP Tracking<br/>[shield.js]"]
  node_block["Block Response<br/>[index.js]"]
end

subgraph group_data["Attack Data"]
  node_logging["Attack Logging<br/>[shield.js]"]
  node_memory[("In-memory Attacks<br/>[shield.js]")]
  node_postgres[("PostgreSQL")]
  node_analytics["Statistics &amp; Severity<br/>[shield.js]"]
end

subgraph group_operations["Operator Views"]
  node_dashboard["Dashboard HTML<br/>[shield.js]"]
  node_dashboardui["Dashboard UI"]
  node_httpapi["Dashboard API<br/>[app-standalone.js]"]
  node_expressapi["Express Dashboard API<br/>[app.js]"]
  node_cli["Shield CLI<br/>[cli.js]"]
end

node_client(("Request Client"))

node_client -->|"sends request"| node_expressapp
node_expressapp -->|"installs"| node_middleware
node_middleware -->|"checks parameters"| node_detection
node_middleware -->|"tracks client IP"| node_iptracking
node_middleware -->|"records detection"| node_logging
node_middleware -->|"returns blocked response"| node_block
node_middleware -->|"continues request"| node_expressapp
node_client -->|"sends request"| node_standalone
node_standalone -->|"checks query values"| node_detection
node_standalone -->|"records detection"| node_logging
node_logging -->|"stores attacks"| node_memory
node_logging -.->|"stores attacks"| node_postgres
node_analytics -->|"reads attacks"| node_memory
node_analytics -.->|"queries attacks"| node_postgres
node_expressapp -->|"serves dashboard routes"| node_expressapi
node_expressapi -->|"gets dashboard HTML"| node_dashboard
node_expressapi -->|"gets statistics"| node_analytics
node_standalone -->|"serves dashboard routes"| node_httpapi
node_httpapi -->|"loads dashboard file"| node_dashboardui
node_httpapi -->|"gets statistics"| node_analytics
node_httpapi -->|"gets attack history"| node_logging
node_client -->|"views dashboard"| node_httpapi
node_package -->|"exports middleware"| node_middleware
node_cli -->|"gets statistics"| node_analytics
node_cli -->|"gets or resets logs"| node_logging

click node_expressapp "https://github.com/achmad-firdaus/node-shield/blob/main/app.js"
click node_standalone "https://github.com/achmad-firdaus/node-shield/blob/main/app-standalone.js"
click node_package "https://github.com/achmad-firdaus/node-shield/blob/main/index.js"
click node_middleware "https://github.com/achmad-firdaus/node-shield/blob/main/index.js"
click node_detection "https://github.com/achmad-firdaus/node-shield/blob/main/shield.js"
click node_iptracking "https://github.com/achmad-firdaus/node-shield/blob/main/shield.js"
click node_block "https://github.com/achmad-firdaus/node-shield/blob/main/index.js"
click node_logging "https://github.com/achmad-firdaus/node-shield/blob/main/shield.js"
click node_memory "https://github.com/achmad-firdaus/node-shield/blob/main/shield.js"
click node_analytics "https://github.com/achmad-firdaus/node-shield/blob/main/shield.js"
click node_dashboard "https://github.com/achmad-firdaus/node-shield/blob/main/shield.js"
click node_dashboardui "https://github.com/achmad-firdaus/node-shield/blob/main/dashboard-as400pro.html"
click node_httpapi "https://github.com/achmad-firdaus/node-shield/blob/main/app-standalone.js"
click node_expressapi "https://github.com/achmad-firdaus/node-shield/blob/main/app.js"
click node_cli "https://github.com/achmad-firdaus/node-shield/blob/main/cli.js"

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_expressapp,node_standalone,node_package,node_client toneBlue
class node_middleware,node_detection,node_iptracking,node_block toneAmber
class node_logging,node_memory,node_postgres,node_analytics toneMint
class node_dashboard,node_dashboardui,node_httpapi,node_expressapi,node_cli toneRose
```

## Components

### Application Integration

- [Express Demo](https://github.com/achmad-firdaus/node-shield/blob/main/app.js): `app.js`
- [Standalone Server](https://github.com/achmad-firdaus/node-shield/blob/main/app-standalone.js): `app-standalone.js`
- [Package API](https://github.com/achmad-firdaus/node-shield/blob/main/index.js): `index.js`

### Request Protection

- [Express Middleware](https://github.com/achmad-firdaus/node-shield/blob/main/index.js): `index.js`
- [Attack Detection](https://github.com/achmad-firdaus/node-shield/blob/main/shield.js): `shield.js`
- [IP Tracking](https://github.com/achmad-firdaus/node-shield/blob/main/shield.js): `shield.js`
- [Block Response](https://github.com/achmad-firdaus/node-shield/blob/main/index.js): `index.js`

### Attack Data

- [Attack Logging](https://github.com/achmad-firdaus/node-shield/blob/main/shield.js): `shield.js`
- [In-memory Attacks](https://github.com/achmad-firdaus/node-shield/blob/main/shield.js): `shield.js`
- **PostgreSQL**
- [Statistics & Severity](https://github.com/achmad-firdaus/node-shield/blob/main/shield.js): `shield.js`

### Operator Views

- [Dashboard HTML](https://github.com/achmad-firdaus/node-shield/blob/main/shield.js): `shield.js`
- [Dashboard UI](https://github.com/achmad-firdaus/node-shield/blob/main/dashboard-as400pro.html): `dashboard-as400pro.html`
- [Dashboard API](https://github.com/achmad-firdaus/node-shield/blob/main/app-standalone.js): `app-standalone.js`
- [Express Dashboard API](https://github.com/achmad-firdaus/node-shield/blob/main/app.js): `app.js`
- [Shield CLI](https://github.com/achmad-firdaus/node-shield/blob/main/cli.js): `cli.js`

### Other components

- **Request Client**

## Connections

- Request Client → Express Demo: sends request
- Express Demo → Express Middleware: installs
- Express Middleware → Attack Detection: checks parameters
- Express Middleware → IP Tracking: tracks client IP
- Express Middleware → Attack Logging: records detection
- Express Middleware → Block Response: returns blocked response
- Express Middleware → Express Demo: continues request
- Request Client → Standalone Server: sends request
- Standalone Server → Attack Detection: checks query values
- Standalone Server → Attack Logging: records detection
- Attack Logging → In-memory Attacks: stores attacks
- Attack Logging → PostgreSQL: stores attacks
- Statistics & Severity → In-memory Attacks: reads attacks
- Statistics & Severity → PostgreSQL: queries attacks
- Express Demo → Express Dashboard API: serves dashboard routes
- Express Dashboard API → Dashboard HTML: gets dashboard HTML
- Express Dashboard API → Statistics & Severity: gets statistics
- Standalone Server → Dashboard API: serves dashboard routes
- Dashboard API → Dashboard UI: loads dashboard file
- Dashboard API → Statistics & Severity: gets statistics
- Dashboard API → Attack Logging: gets attack history
- Request Client → Dashboard API: views dashboard
- Package API → Express Middleware: exports middleware
- Shield CLI → Statistics & Severity: gets statistics
- Shield CLI → Attack Logging: gets or resets logs