# Architecture

hermes-ui is a TypeScript project that ships a browser dashboard and a Koa
backend around Hermes Agent. It runs on Node.js and talks to Hermes over an
Agent Bridge (see "Hermes Integration" below).

## Package Boundaries

| Area | Path | Responsibility |
| --- | --- | --- |
| Client | `packages/client/src` | Vue UI, routing, Pinia stores, API wrappers, i18n, browser-visible state. |
| Server | `packages/server/src` | HTTP API, auth, Socket.IO, SQLite stores, file access, Hermes runtime integration. |
| Skills | `packages/skills` | Built-in skills injected into the Hermes skills directory. |
| Legacy agent | `packages/ekko-agent` | In-house agent runtime. Slated for removal in Phase 003; do not extend it. |
| Tests | `tests` | Vitest unit/integration tests and Playwright browser tests. |
| CI | `.github/workflows` | Build, e2e, lockfile, Docker, and release automation. |

This is not an npm workspaces monorepo. `packages/client` and
`packages/server` have no `package.json`; their dependencies are declared in the
root `package.json`.

## Request Flow

1. The browser loads the Vite-built client from the Koa server.
2. Client modules call API helpers from `packages/client/src/api`.
3. Server routes in `packages/server/src/routes` wire HTTP paths to controllers.
4. Controllers validate request concerns and delegate reusable behavior to services.
5. Services own side effects: files, SQLite, Hermes profiles, subprocesses, bridges, and credentials.
6. Long-running chat and group-chat flows use Socket.IO namespaces managed by server services.

Keep each layer narrow. Routes should not grow business logic, and client code
should not duplicate server persistence rules.

## State And Data Ownership

- Web UI state defaults to `~/.hermes-web-ui` through `config.appHome`.
- `HERMES_WEB_UI_HOME` and `HERMES_WEBUI_STATE_DIR` override Web UI state location.
  These identifiers are intentionally kept from the 0.6.x line: renaming them would
  break existing deployment scripts and orphan existing data directories.
- Hermes Agent state lives under Hermes profile directories and must stay distinct
  from Web UI state. Profile isolation is done by injecting `HERMES_HOME` into child
  processes, never by copying directories.
- Hermes `state.db` is read-only and owned by the Hermes Agent. Node-side code must
  never open it; read session history through the bridge's `getHistory`/`getOutput`.
- The project's own SQLite store under `packages/server/src/db` is the only writable
  store for sessions, messages, and usage. There is no startup import sync from
  Hermes state.
- Uploads default to `config.uploadDir`, which is derived from the Web UI home unless `UPLOAD_DIR` is set.
- Runtime data directories must also live under the Web UI home, not beside built `dist` assets.
- Profile-scoped Hermes data should use existing profile helpers instead of manually joining paths.

## Server Structure

- `routes/` registers HTTP and WebSocket entry points.
- `controllers/` handles request-level behavior.
- `services/` owns reusable IO, domain behavior, external process calls, and integration logic.
- `db/` owns SQLite schemas and stores.
- `middleware/` owns request middleware such as user auth.
- `shared/` contains cross-server constants and helpers.

Architecture rules:

- Register local API routes before proxy catch-all routes.
- Keep auth behavior centralized in `packages/server/src/services/auth.ts`.
- Prefer `execFile` or `spawn` with argument arrays over shell command strings.
- All Hermes CLI calls go through `execHermesWithBin`/`spawnHermesWithBin` in
  `services/hermes/hermes-process.ts`.
- Use structured file and YAML/JSON parsers when editing structured data.

## Hermes Integration

Chat runs through the Agent Bridge, which is the only supported path:

```
browser --Socket.IO--> Koa/Node server --JSON over Unix socket--> Python child
                                                                   └- hermes-agent run_agent.AIAgent
```

- `services/hermes/agent-bridge/python/` is vendored, read-only code. The only
  exception is the `HERMES_DESKTOP` checks in `bridge_runtime.py`, which hide the
  Windows console window for git subprocesses and must stay.
- `services/hermes/group-chat/`, `lib/context-compressor/`, and
  `services/hermes/context-engine/` form the chat chain. Changes there require a
  `docs/chat-chain-changes/<date>-<slug>.md` fragment.
- The Hermes CLI is user-installed. Point `HERMES_BIN` at the executable, or let
  the server resolve `hermes` from `PATH`.

## Client Structure

- `views/` contains route-level screens.
- `components/` contains reusable UI.
- `stores/` contains Pinia state.
- `api/` contains HTTP clients and should use `packages/client/src/api/client.ts`.
- `i18n/` contains locale messages for user-facing strings. Only `zh` and `en` are supported.
- `styles/` contains global styling and theme primitives.

Frontend rules:

- Use Vue 3 Composition API with `<script setup lang="ts">`.
- Use Arco Design Vue components. Naive UI is being removed; do not add new
  `naive-ui` imports.
- Add visible text to every locale file.
- Keep component styles scoped unless the style is intentionally global.

## Validation Surface

The minimum mechanical harness is:

- `npm run harness:check` for repository docs, workflow, and package-script invariants.
- `npm run test` or focused Vitest tests for local logic.
- `npm run test:e2e` for browser-visible routing/auth/chat regressions.
- `npm run build` for type checking and production bundles.

See `docs/harness/validation.md` for change-specific commands.