0
0
# Docs Overhaul Design
## Goal
Rewrite hatk documentation to reflect the current API surface (generated client helpers, SQLite-only, SvelteKit remote commands, `parseViewer`/`login`/`logout` from `$hatk/client`). Inspired by Nitro's docs style — project tree on landing page, code-heavy examples, progressive structure.
## Audience
Web developers who may or may not know AT Protocol. Don't gate understanding behind AT Protocol knowledge. Explain concepts inline as they come up ("lexicons are schemas for your data — like Prisma models but for the AT Protocol"). Link to AT Protocol docs for deep dives.
## Framework
Stay with VitePress. Content is the problem, not the tooling.
---
## Landing Page
Hero with current tagline, then a project structure visualization:
```
my-app/
├── app/ # SvelteKit frontend
│ ├── routes/
│ │ ├── +layout.server.ts # parseViewer(cookies)
│ │ └── +page.svelte # your UI
│ └── lib/
├── server/ # Backend
│ ├── feeds/ # Feed generators
│ │ └── recent.ts # defineFeed({ ... })
│ └── xrpc/ # Custom endpoints
│ └── getProfile.ts # defineQuery('...', ...)
├── seeds/
│ └── seed.ts # Test fixtures
├── lexicons/ # AT Protocol schemas
├── hatk.config.ts # Configuration
└── hatk.generated.ts # Auto-generated types
```
Below the tree, 4 feature cards:
- **Typed end-to-end** — Lexicons generate TypeScript types for records, queries, feeds
- **SQLite by default** — No external database, just works
- **OAuth built-in** — AT Protocol auth with session cookies, no setup
- **SvelteKit-first** — Full-stack with SSR, remote commands, typed XRPC calls
CTA: "Get Started"
---
## Navigation Structure
### Top nav
- Guide → /getting-started/quickstart
- Frontend → /frontend/setup
- CLI → /cli/
- API → /api/
### Sidebar
**Getting Started** (3 pages)
- Quickstart
- Project Structure
- Configuration
**Guides** (7 pages)
- Feeds
- XRPC Handlers
- Auth & OAuth
- Seeds
- Labels
- OpenGraph
- Hooks
**Frontend** (3 pages)
- SvelteKit Setup
- Data Loading
- Mutations
**CLI Reference** (5 pages)
- Overview
- Scaffolding
- Development
- Testing
- Build & Deploy
**API Reference** (7 pages)
- Overview
- Records
- Feeds
- Search
- Blobs
- Preferences
- Labels
---
## Page Details
### Getting Started
**Quickstart** — Zero to running app in under 2 minutes.
1. `npx hatk new my-app`
2. `cd my-app && npm run dev`
3. Open browser, see the app
4. Make a first change (edit a feed or add a record via admin)
No AT Protocol preamble. Jump straight into doing. Explain concepts when they naturally arise.
**Project Structure** — Expanded annotated tree. Each directory gets 2-3 sentences and a link to the relevant guide. Replaces current page which lists directories without connecting them to workflows.
**Configuration** — `hatk.config.ts` reference. Each option with type, default, one-line description. Groups: server (relay, plc, port), database (engine, path), backfill (parallelism, signalCollections), oauth (issuer, scopes, clients). Minimal config example at top showing just the essentials. No DuckDB options.
### Guides
All guides follow the same pattern: what it does, minimal example, then details.
**Feeds** — `defineFeed()` with `generate` and `hydrate`. Statusphere "recent" feed as the example. Pagination with `ctx.paginate()`, hydration for author profiles. Most important guide.
**XRPC Handlers** — `defineQuery()` and `defineProcedure()` with typed context (`Ctx<K>`). `ctx.ok()` for return type enforcement. `ctx.db.query()` for direct SQL, `ctx.lookup()` for cross-collection joins.
**Auth & OAuth** — Rewritten from scratch. No `OAuthClient` class. Focus on: config (hatk.config.ts oauth section), built-in login/callback flow, `parseViewer(cookies)` in layouts, `login()`/`logout()` from `$hatk/client`, `getViewer()` in server code. Complete flow from config to working login.
**Seeds** — `seed()` helper with `createAccount`, `createRecord`, `uploadBlob`. Complete seed file example. `hatk seed` and `hatk reset` commands.
**Labels** — `defineLabel()` with `evaluate()`. Brief.
**OpenGraph** — `defineOG()` with Satori. Brief.
**Hooks** — `defineHook('on-login', ...)` with `ensureRepo`. One example.
### Frontend
**SvelteKit Setup** — Vite plugin (`hatk()` in vite.config.ts), `$hatk` and `$hatk/client` aliases, what the generated files contain, the `app/` directory convention. `hatk generate types` for regeneration.
**Data Loading** — `callXrpc()` from `$hatk/client`. Show in `+page.server.ts` (server-side bridge) and `+page.ts` (universal). `customFetch` for SvelteKit deduplication. `getViewer()` for current user in server code.
**Mutations** — Remote commands with SvelteKit experimental remote functions. `command('unchecked', ...)` pattern. Creating/deleting records via `callXrpc('dev.hatk.createRecord', ...)`. Optimistic UI updates.
### CLI & API Reference
Update to match current signatures. Remove DuckDB references. Add `customFetch` param, `parseViewer`, new generated client exports.
---
## Key Changes from Current Docs
- Drop all DuckDB references (SQLite only)
- Drop TanStack Query (use `callXrpc` directly)
- Drop `OAuthClient` class (use generated `login`/`logout`/`parseViewer`)
- Drop `api-client.md` guide (fold into Frontend section)
- Frontend gets its own top-level section
- Landing page gets project tree visualization
- All examples sourced from hatk-template-statusphere and hatk-template-teal
- Deployment guide updated for SQLite/Railway
## Source Material
- `~/code/hatk-template-statusphere` — simple reference app
- `~/code/hatk-template-teal` — complex reference app with feeds, bookmarks, search
- `~/code/hatk-template-start` — minimal starter
- `~/code/hatk/packages/hatk/src/cli.ts` — generated client output (auth helpers, parseViewer)