# webavatar-core

A base SvelteKit project meant to be branched off for future webavatar client projects. It provides the reusable core infrastructure those projects would otherwise reimplement from scratch — session management, auth tokens, and the realtime model connection — as a foundation to branch from, not a finished product.

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

## Getting started

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

Open [`/demo/realtime`](http://localhost:5173/demo/realtime) for the realtime session reference wiring, or [`/demo/humanoid`](http://localhost:5173/demo/humanoid) for the humanoid avatar-state demo (works offline via `REALTIME_PROVIDER=mock`, no API key needed).

## Scripts

- `npm run dev` / `npm run build` / `npm run preview` — standard SvelteKit commands.
- `npm run check` — type-check. `npm run lint` / `npm run format` — prettier + eslint.
- `npm run test:unit` — vitest. `npm run test:e2e` — Playwright.
- `npm start` — run the production build via `server.js` (the persistent Node process the realtime WebSocket relay requires — see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)).

## 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)       |
| `humanoid` package (avatar-state, animation composition)       | [docs/HUMANOID.md](docs/HUMANOID.md)                 |