From 84e01c78517223bc355b6937ce047bc571896093 Mon Sep 17 00:00:00 2001
From: sagit <sagitchu@gmail.com>
Date: Sat, 24 Jan 2026 03:52:58 +0000
Subject: [PATCH] docs: add AGENTS.md knowledge base files

---
 AGENTS.md                    | 43 ++++++++++++++++++++++++++++++++++++
 go-gost/AGENTS.md            | 31 ++++++++++++++++++++++++++
 springboot-backend/AGENTS.md | 37 +++++++++++++++++++++++++++++++
 vite-frontend/AGENTS.md      | 34 ++++++++++++++++++++++++++++
 4 files changed, 145 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 go-gost/AGENTS.md
 create mode 100644 springboot-backend/AGENTS.md
 create mode 100644 vite-frontend/AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..6d5dc6e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,43 @@
+# PROJECT KNOWLEDGE BASE
+
+**Generated:** Sat Jan 24 2026
+**Context:** Monorepo for Flux Panel (Traffic Forwarding)
+
+## OVERVIEW
+Flux Panel is a traffic forwarding management system based on [go-gost](https://github.com/go-gost/gost). It manages tunnels, port forwarding, and user quotas.
+**Stack:** Monorepo (Java/Spring Boot Backend + React/Vite Frontend + Go/GOST Service).
+
+## STRUCTURE
+```
+/root/flux-panel/
+├── springboot-backend/  # Java 21 + Spring Boot 2.7 Admin API
+├── vite-frontend/       # React 18 + Vite + HeroUI/NextUI
+├── go-gost/             # Go 1.23 + GOST Extensions (Core logic)
+├── docker-compose*.yml  # Deployment configs (v4/v6)
+└── *.sh                 # Install scripts (panel_install.sh, install.sh)
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| **Admin API** | `springboot-backend/` | Users, quotas, billing logic |
+| **UI/Dashboard** | `vite-frontend/` | Management console |
+| **Core Forwarding** | `go-gost/` | GOST implementation & extensions |
+| **Deploy** | `docker-compose-v4.yml` | Container orchestration |
+
+## CONVENTIONS
+- **Monorepo**: 3 distinct languages/stacks. Treat each subdir as a separate project.
+- **Docker**: Primary deployment method.
+- **Scripts**: `panel_install.sh` for panel, `install.sh` for nodes.
+
+## COMMANDS
+```bash
+# Quick Deploy (Panel)
+./panel_install.sh
+
+# Quick Deploy (Node)
+./install.sh
+
+# Docker
+docker-compose -f docker-compose-v4.yml up -d
+```
diff --git a/go-gost/AGENTS.md b/go-gost/AGENTS.md
new file mode 100644
index 0000000..c9f36fc
--- /dev/null
+++ b/go-gost/AGENTS.md
@@ -0,0 +1,31 @@
+# GO-GOST SERVICE KNOWLEDGE BASE
+
+## OVERVIEW
+Core forwarding service based on GOST v3.
+**Stack:** Go 1.23, GOST Core v0.3.1, GOST x (Extensions).
+
+## STRUCTURE
+```
+go-gost/
+├── main.go           # Entry point
+├── x/                # Local extensions (REPLACES github.com/go-gost/x)
+│   ├── api/          # Management API
+│   ├── registry/     # Service registry
+│   ├── handler/      # Protocol handlers (socks, tunnel, relay)
+│   └── listener/     # Network listeners (tcp, udp, tun/tap)
+└── go.mod            # Defines local replacement
+```
+
+## CONVENTIONS
+- **Local Replace**: `go.mod` uses `replace github.com/go-gost/x => ./x`.
+- **Extensions**: Custom logic lives in `x/`. This is the primary place for modifications.
+- **Handlers**: Implements SOCKS5, Tunnel, Relay, etc.
+
+## COMMANDS
+```bash
+# Run
+go run .
+
+# Build
+go build .
+```
diff --git a/springboot-backend/AGENTS.md b/springboot-backend/AGENTS.md
new file mode 100644
index 0000000..ccff72c
--- /dev/null
+++ b/springboot-backend/AGENTS.md
@@ -0,0 +1,37 @@
+# SPRINGBOOT BACKEND KNOWLEDGE BASE
+
+## OVERVIEW
+Admin API for Flux Panel. Manages users, licenses, and traffic rules.
+**Stack:** Java 21, Spring Boot 2.7.18, SQLite, MyBatis Plus.
+
+## STRUCTURE
+```
+springboot-backend/
+├── src/main/java/com/admin/
+│   ├── controller/      # API Endpoints
+│   ├── entity/          # DB Models (MyBatis Plus)
+│   ├── mapper/          # Data Access
+│   ├── service/         # Business Logic
+│   └── common/          # Utils, DTOs
+└── src/main/resources/
+    ├── application.yml  # Config
+    ├── mapper/          # XML Mappers
+    ├── data.sql         # Init data
+    └── bgimages/        # Static resources
+```
+
+## CONVENTIONS
+- **DB**: SQLite used via `sqlite-jdbc`.
+- **ORM**: MyBatis Plus + MyBatis Plus Join.
+- **JSON**: FastJSON2 used for serialization.
+- **Utils**: Hutool used extensively.
+- **Auth**: Likely custom or token-based (see `controller` logic).
+
+## COMMANDS
+```bash
+# Build
+mvn clean package
+
+# Run
+java -jar target/admin-0.0.1-SNAPSHOT.jar
+```
diff --git a/vite-frontend/AGENTS.md b/vite-frontend/AGENTS.md
new file mode 100644
index 0000000..b25704a
--- /dev/null
+++ b/vite-frontend/AGENTS.md
@@ -0,0 +1,34 @@
+# VITE FRONTEND KNOWLEDGE BASE
+
+## OVERVIEW
+Web management console for Flux Panel.
+**Stack:** React 18, Vite 5, TypeScript, TailwindCSS 4, HeroUI (NextUI).
+
+## STRUCTURE
+```
+vite-frontend/
+├── src/
+│   ├── pages/        # Route views
+│   ├── components/   # Reusable UI parts
+│   ├── layouts/      # Page wrappers
+│   ├── api/          # Axios wrappers
+│   ├── config/       # App settings
+│   └── utils/        # Helpers
+├── vite.config.ts    # Vite config (Base: '/')
+└── package.json
+```
+
+## CONVENTIONS
+- **UI Lib**: HeroUI (formerly NextUI) + Tailwind CSS 4.
+- **Routing**: React Router DOM 6.
+- **State**: Check `provider.tsx` or local state.
+- **Build**: Output to `dist/`.
+
+## COMMANDS
+```bash
+# Dev
+npm run dev
+
+# Build
+npm run build
+```