# webavatar

An npm-workspaces monorepo providing reusable core infrastructure for webavatar client projects — session management, auth tokens, and the realtime model connection — as independently-versioned packages, plus a SvelteKit template to branch client projects from.

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full architecture map, [AGENTS.md](AGENTS.md) for project conventions, and `docs/` for a deep-dive per subsystem.

## Workspaces

| Workspace                                | What it is                                                                                                                                                                        |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`packages/core`](packages/core)         | `@webavatar/webavatar-core` — session management, auth tokens, provider adapters, the WS relay. Every client project needs this.                                                  |
| [`packages/humanoid`](packages/humanoid) | `@webavatar/webavatar-humanoid` — avatar-state derivation and animation-channel composition for 3D humanoid avatars. Optional — only projects building a humanoid avatar need it. |
| [`apps/template`](apps/template)         | The SvelteKit application template client projects branch from. See its own README for the client-project bootstrap procedure.                                                    |

Both packages are privately distributed (not published to the public npm registry) and ESM-only.

## Getting started

```sh
npm install
cp apps/template/.env.example apps/template/.env
# fill in OPENAI_API_KEY and REALTIME_TOKEN_SECRET in apps/template/.env
npm run dev
```

The root `npm run dev` builds both packages once, then watches them alongside the template app's own dev server — this is what makes package-source hot reload work (see [docs/REALTIME_SESSION.md](docs/REALTIME_SESSION.md)'s "Dev-mode reload behavior"). Open [`/demo/realtime`](http://localhost:5173/demo/realtime) or [`/demo/humanoid`](http://localhost:5173/demo/humanoid) (works offline via `REALTIME_PROVIDER=mock`, no API key needed).

## Scripts

Run from the repo root, these orchestrate all three workspaces:

- `npm run dev` / `npm run build` / `npm run check` / `npm test` — build the packages first, then run the equivalent command across every workspace.
- `npm run lint` / `npm run format` — prettier + eslint across the whole repo.

Run a single workspace's own scripts with `-w`, e.g. `npm run dev -w apps/template`, or `npm run test -w packages/core`.

## Documentation

| Subsystem                                                             | Doc                                                                  |
| --------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Architecture overview and module layering                             | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)                         |
| Realtime session management                                           | [docs/REALTIME_SESSION.md](docs/REALTIME_SESSION.md)                 |
| Tool calling (server- and client-executed)                            | [docs/TOOLS.md](docs/TOOLS.md)                                       |
| Analytics recording                                                   | [docs/ANALYTICS.md](docs/ANALYTICS.md)                               |
| Configuration (env vars, persona)                                     | [docs/CONFIGURATION.md](docs/CONFIGURATION.md)                       |
| `@webavatar/webavatar-humanoid` (avatar-state, animation composition) | [docs/HUMANOID.md](docs/HUMANOID.md)                                 |
| The monorepo migration itself — rationale, decisions, verification    | [docs/MONOREPO_MIGRATION_BRIEF.md](docs/MONOREPO_MIGRATION_BRIEF.md) |