# KLALB Repository Guide

KLALB is a Java SRv6/load-balancing system. The executable entrypoint is `org.kne.cloud.network.klalb.KLALBMain`; runtime configuration is `klalb-config.json` in the repository root.

## Build And Run

- This is a plain Eclipse/IntelliJ Java project: sources are `src/`, vendored dependencies are `lib/`, and output is `bin/`. There is no Maven or Gradle.
- `.classpath` targets `JavaSE-25`. Sources contain Chinese text, so manual compilation must use UTF-8:

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

- Run from the repository root. Manual `javac` does not copy resources, so keep `src` on the runtime classpath:

```powershell
& "C:\Program Files\Zulu\zulu-25\bin\java.exe" --enable-native-access=ALL-UNNAMED "--add-opens=java.base/jdk.internal.misc=ALL-UNNAMED" -cp "bin;src;lib/*" org.kne.cloud.network.klalb.KLALBMain
```

- The native libraries and `klalb-config.json` are resolved from the current directory. Restart a running JVM after recompiling.
- TUN creation normally needs elevation. For non-admin UI/routing checks, set `"enableTUN": false`.
- Current full compilation emits 11 pre-existing varargs/deprecation warnings; exit code `0` is success.

## Dashboard

- `dashboard/` is a Git submodule. Commit dashboard changes inside it, then update the parent repository's submodule pointer.
- Run frontend commands from `dashboard/` with pnpm:

```powershell
pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
pnpm build
pnpm dev
```

- `pnpm build` runs `tsc -b` then Vite and writes `dashboard/dist`, which the Java web server hosts. Vite development proxies `/api` to `http://127.0.0.1:4665`.
- Add shadcn components through `pnpm dlx shadcn@latest add <component>`; do not hand-create replacements for installed shadcn primitives.

## Verification

- There is no CI or automated test suite. `*Test*` classes are manual harnesses that require real network peers.
- For Java changes, compile and launch the app. For dashboard changes, run `pnpm typecheck` and `pnpm build`.

## Important Boundaries

- `KLALBConfigItem` is a polymorphic JSON array keyed by `Type`. Adding a type requires a subclass and cases in both default config serializer and deserializer; unknown types must remain preserved.
- `/api/config` is field-by-field parsing, not whole-object Gson mapping. Keep legacy key aliases in sync with new fields.
- Vendored Gson is `2.1`: responses that are `JsonElement` instances must be serialized with `JsonElement.toString()`, not reflective `gson.toJson(Object)`.
- UI strings use `UIEnv.getRsb()`; add keys to both `src/klalb_zh_CN.properties` and `src/klalb_en_US.properties`.
- `KLALBController.PublishedNodeInfo` is the thread-safe source for Tiny/Full node-info responses. Publish name, description, external endpoints, and Extra Routes through the controller method so snapshots and Tiny/Full update flags stay consistent.
- `RouterInfo` no longer carries a device name. Its wire format retains an empty legacy UTF slot and `RouterInfoPacket` has optional Tiny/Full invalidation flags. Treat codec changes as compatibility work: preserve old-reader behavior and review a whole-mesh rollout.
- Full node-info carries `extraRoutes` separately from the endpoint `data` list. Keep absent fields compatible with older peers.