# maeneko/forgetting architecture

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

- Interactive diagram: https://gitdiagram.com/maeneko/forgetting
- Repository: https://github.com/maeneko/forgetting

## Overview

Forgetting is a VPN management panel and API for AmneziaWG. A panel operator or API client requests peer/key operations through awg-ui; it authenticates requests, serves the web UI and public API, and brokers VPN operations to the privileged, loopback-only awg-ctrl. awg-ui also manages multi-server nodes and SenAWG master-key subscriptions. The CLI manages service processes and panel credentials. The README documents the component boundaries; some internal routing and storage details are unsampled, so uncertain links are omitted.

Main entry points: [`awg-ui/src/App.tsx`](https://github.com/maeneko/forgetting/blob/main/awg-ui/src/App.tsx) (Web panel), [`awg-ui/server.ts`](https://github.com/maeneko/forgetting/blob/main/awg-ui/server.ts) (HTTP API and auth), [`awg-ui/sub.ts`](https://github.com/maeneko/forgetting/blob/main/awg-ui/sub.ts) (Subscription service), [`awg-ctrl/index.ts`](https://github.com/maeneko/forgetting/blob/main/awg-ctrl/index.ts) (Privileged VPN API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Panel interface"]
  node_panel["Web panel<br/>[App.tsx]"]
  node_users_ui["Peer management<br/>[index.tsx]"]
  node_apikey_ui["API-key management<br/>[index.tsx]"]
  node_master_ui["Master-key management<br/>[index.tsx]"]
end

subgraph group_ui["Panel services"]
  node_ui_server["HTTP API and auth<br/>[server.ts]"]
  node_public_api["Public API<br/>[server.ts]"]
  node_node_manager["Node management<br/>[nodes.ts]"]
  node_subscription["Subscription service<br/>[sub.ts]"]
  node_sen_codec["Sen link protocol<br/>[sen.ts]"]
  node_ui_db[("Panel database<br/>[server.ts]")]
end

subgraph group_vpn["VPN control"]
  node_ctrl["Privileged VPN API<br/>[index.ts]"]
  node_vpn_state[("VPN peers and config<br/>[index.ts]")]
  node_agent["VPN agent<br/>[index.ts]"]
end

subgraph group_ops["Operations"]
  node_cli["Service CLI<br/>[index.ts]"]
  node_admin_ui["Admin console<br/>[App.tsx]"]
  node_admin_api["Admin service<br/>[server.ts]"]
end

node_operator(("Panel operator"))
node_api_client(("API client"))
node_sen_client(("SenAWG device"))

node_operator -->|"uses"| node_panel
node_panel -->|"requests"| node_ui_server
node_panel -->|"renders"| node_users_ui
node_panel -->|"renders"| node_apikey_ui
node_panel -->|"renders"| node_master_ui
node_api_client -->|"calls"| node_public_api
node_public_api -->|"proxies VPN requests"| node_ctrl
node_ui_server -->|"stores panel keys"| node_ui_db
node_ui_server -->|"starts"| node_node_manager
node_ui_server -->|"starts"| node_subscription
node_subscription -->|"reads and writes"| node_ui_db
node_subscription -->|"encodes links"| node_sen_codec
node_sen_client -->|"registers device"| node_subscription
node_ctrl -->|"manages peers"| node_vpn_state
node_operator -->|"manages services"| node_cli
node_admin_ui -.->|"uses"| node_admin_api

click node_panel "https://github.com/maeneko/forgetting/blob/main/awg-ui/src/App.tsx"
click node_users_ui "https://github.com/maeneko/forgetting/blob/main/awg-ui/src/tabs/users/index.tsx"
click node_apikey_ui "https://github.com/maeneko/forgetting/blob/main/awg-ui/src/tabs/apikeys/index.tsx"
click node_master_ui "https://github.com/maeneko/forgetting/blob/main/awg-ui/src/tabs/masterkeys/index.tsx"
click node_ui_server "https://github.com/maeneko/forgetting/blob/main/awg-ui/server.ts"
click node_public_api "https://github.com/maeneko/forgetting/blob/main/awg-ui/server.ts"
click node_node_manager "https://github.com/maeneko/forgetting/blob/main/awg-ui/nodes.ts"
click node_subscription "https://github.com/maeneko/forgetting/blob/main/awg-ui/sub.ts"
click node_sen_codec "https://github.com/maeneko/forgetting/blob/main/awg-ui/sen.ts"
click node_ui_db "https://github.com/maeneko/forgetting/blob/main/awg-ui/server.ts"
click node_ctrl "https://github.com/maeneko/forgetting/blob/main/awg-ctrl/index.ts"
click node_vpn_state "https://github.com/maeneko/forgetting/blob/main/awg-ctrl/index.ts"
click node_agent "https://github.com/maeneko/forgetting/blob/main/awg-agent/index.ts"
click node_cli "https://github.com/maeneko/forgetting/blob/main/cli/src/index.ts"
click node_admin_ui "https://github.com/maeneko/forgetting/blob/main/admin/frontend/src/App.tsx"
click node_admin_api "https://github.com/maeneko/forgetting/blob/main/admin/backend/server.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_panel,node_users_ui,node_apikey_ui,node_master_ui,node_api_client toneBlue
class node_ui_server,node_public_api,node_node_manager,node_subscription,node_sen_codec,node_ui_db toneAmber
class node_ctrl,node_vpn_state,node_agent toneMint
class node_cli,node_admin_ui,node_admin_api toneRose
class node_operator,node_sen_client toneIndigo
```

## Components

### Panel interface

- [Web panel](https://github.com/maeneko/forgetting/blob/main/awg-ui/src/App.tsx): `awg-ui/src/App.tsx`
- [Peer management](https://github.com/maeneko/forgetting/blob/main/awg-ui/src/tabs/users/index.tsx): `awg-ui/src/tabs/users/index.tsx`
- [API-key management](https://github.com/maeneko/forgetting/blob/main/awg-ui/src/tabs/apikeys/index.tsx): `awg-ui/src/tabs/apikeys/index.tsx`
- [Master-key management](https://github.com/maeneko/forgetting/blob/main/awg-ui/src/tabs/masterkeys/index.tsx): `awg-ui/src/tabs/masterkeys/index.tsx`

### Panel services

- [HTTP API and auth](https://github.com/maeneko/forgetting/blob/main/awg-ui/server.ts): `awg-ui/server.ts`
- [Public API](https://github.com/maeneko/forgetting/blob/main/awg-ui/server.ts): `awg-ui/server.ts`
- [Node management](https://github.com/maeneko/forgetting/blob/main/awg-ui/nodes.ts): `awg-ui/nodes.ts`
- [Subscription service](https://github.com/maeneko/forgetting/blob/main/awg-ui/sub.ts): `awg-ui/sub.ts`
- [Sen link protocol](https://github.com/maeneko/forgetting/blob/main/awg-ui/sen.ts): `awg-ui/sen.ts`
- [Panel database](https://github.com/maeneko/forgetting/blob/main/awg-ui/server.ts): `awg-ui/server.ts`

### VPN control

- [Privileged VPN API](https://github.com/maeneko/forgetting/blob/main/awg-ctrl/index.ts): `awg-ctrl/index.ts`
- [VPN peers and config](https://github.com/maeneko/forgetting/blob/main/awg-ctrl/index.ts): `awg-ctrl/index.ts`
- [VPN agent](https://github.com/maeneko/forgetting/blob/main/awg-agent/index.ts): `awg-agent/index.ts`

### Operations

- [Service CLI](https://github.com/maeneko/forgetting/blob/main/cli/src/index.ts): `cli/src/index.ts`
- [Admin console](https://github.com/maeneko/forgetting/blob/main/admin/frontend/src/App.tsx): `admin/frontend/src/App.tsx`
- [Admin service](https://github.com/maeneko/forgetting/blob/main/admin/backend/server.ts): `admin/backend/server.ts`

### Other components

- **Panel operator**
- **API client**
- **SenAWG device**

## Connections

- Panel operator → Web panel: uses (evidence: `README.md`)
- Web panel → HTTP API and auth: requests (evidence: `awg-ui/src/App.tsx`)
- Web panel → Peer management: renders
- Web panel → API-key management: renders
- Web panel → Master-key management: renders
- API client → Public API: calls (evidence: `README.md`)
- Public API → Privileged VPN API: proxies VPN requests (evidence: `README.md`)
- HTTP API and auth → Panel database: stores panel keys (evidence: `awg-ui/server.ts`)
- HTTP API and auth → Node management: starts (evidence: `awg-ui/server.ts`)
- HTTP API and auth → Subscription service: starts (evidence: `awg-ui/server.ts`)
- Subscription service → Panel database: reads and writes (evidence: `awg-ui/sub.ts`)
- Subscription service → Sen link protocol: encodes links (evidence: `awg-ui/sub.ts`)
- SenAWG device → Subscription service: registers device (evidence: `README.md`)
- Privileged VPN API → VPN peers and config: manages peers (evidence: `README.md`)
- Panel operator → Service CLI: manages services (evidence: `README.md`)
- Admin console → Admin service: uses
