# KLALB Agent Guide

KLALB is a Java SRv6/WAN load-balancing system. `KLALBMain` loads `klalb-config.json` from the current directory, builds `KLALBProxySystem`, optionally opens a desktop UI, optionally starts the web UI, and always binds the virtual server to `[::]:4564`.

## Java Build And Run

- This is a plain Java project: vendored dependencies are in `lib/`, `bin/` is generated, and sources/resources are in `src/`. There is no Maven, Gradle, test suite, or CI.
- VSCode is configured for `C:\Program Files\Zulu\zulu-25`. `javac` is not on `PATH`; source files require UTF-8 and now reference JavaFX modules.

```powershell
& "C:\Program Files\Zulu\zulu-25\bin\javac.exe" -encoding UTF-8 --add-modules=javafx.controls,javafx.graphics -cp "lib/*" -d bin (Get-ChildItem -Recurse src -Filter *.java | ForEach-Object FullName)
```

- The documented `ThreadTool` varargs and deprecated-API warnings are pre-existing; compilation succeeds with exit code 0. Restart a debugged JVM after compiling because it keeps old classes.
- Run from the repository root. `src` must stay on the runtime classpath after manual compilation because it contains `klalb_*.properties` and `/assets/*` resources.
- Use `KLALB JavaFX Preview (bin)` in VSCode for the opt-in `--javafx` UI. Default startup remains Swing. The preview configuration supplies required JavaFX modules, native-access flags, and `java.library.path`.
- Native files are expected in the repository root. `fastcopy.dll` is currently absent, so `FastLib` logs a recoverable `UnsatisfiedLinkError`; restore the matching binary before testing native acceleration. Set `enableTUN: false` for non-admin UI testing; otherwise TUN creation requires elevation.

## Architecture And UI

- Keep `KLALBController` and networking work off UI threads. The current JavaFX layer is `src/org/kne/cloud/network/klalb/ui/fx/`, starts only with `--javafx`, and exposes immutable snapshots/typed commands through `KLALBJavaFXGateway`; do not leak controller or link objects into JavaFX views.
- Swing remains in `...klalb.ui`. Do not assume feature parity: Overview and Connections are migrated; routing, topology, settings, and detailed monitor views remain Swing/placeholder workspaces.
- UI strings use the active `UIEnv` bundle. Add every new key to both `src/klalb_zh_CN.properties` and `src/klalb_en_US.properties`; keep them on the runtime classpath.

## Config, APIs, And Protocols

- `klalb-config.json` is a `Type`-discriminated list. New item types need a `KLALBConfigItem` subclass plus both default Gson serializer/deserializer registrations; unknown items must remain preservable.
- Config saves use canonical keys but reads and `/api/config` accept legacy aliases. Keep aliases in `KLALBConfigItem` and field-by-field `KLALBWebServer.handleConfig` parsing when changing controller settings; whole-object Gson mapping breaks polymorphic address lists.
- Gson is vendored version 2.1. For a runtime `JsonElement`, use `JsonElement.toString()` rather than `gson.toJson(Object)`; old Gson serializes subclasses incorrectly. Keep the existing guard in `sendJsonResponse`.
- SRv6 JSON datagrams have a two-byte UTF-8 payload length; keep encoded messages below 64 KiB.
- The web dashboard is served from `dashboard/dist` when `webUI` is enabled (normally `:4665`); without it, the backend serves fallback HTML.

## Dashboard Submodule

- `dashboard/` is a separate Git repository. Commit frontend work there first, then update the parent submodule pointer.
- Run frontend commands inside `dashboard/`: `pnpm dev`, `pnpm build`, `pnpm lint`, and `pnpm typecheck`. Vite proxies `/api` to `http://127.0.0.1:4665`.
- Install shadcn components only with `pnpm dlx shadcn@latest add <component>`; use `pnpm add` for other dependencies. The dashboard README's `npx` instruction is stale.

## Verification

- Practical Java verification is the full compile command above plus a controlled launch. Existing `*Test*` classes are manual harnesses that need real network peers.
- For dashboard changes, run `pnpm lint`, `pnpm typecheck`, and `pnpm build`.
