Evan Reichard
91d4202874
All checks were successful
continuous-integration/drone/push Build is passing
- Root AGENTS.md: add build pipeline, Makefile targets, full directory listing - Backend AGENTS.md: add architecture layout, API routes table, streaming/store patterns, missing deps (jsonschema-go, values pkg, types pkg) - Frontend AGENTS.md: add architecture layout, missing deps (marked, highlight.js), Alpine component pattern, build pipeline details - README.md: add env var config table, Docker/Make workflows, dev setup, thinking support, token stats, structured output, llama.cpp timings
69 lines
2.5 KiB
Markdown
69 lines
2.5 KiB
Markdown
# Frontend Agent Instructions
|
|
|
|
## Stack
|
|
|
|
- **Bun** (bundler + package manager — no npm)
|
|
- **TypeScript** (strict mode, ES2020 target)
|
|
- **Alpine.js** (reactivity, bundled via `main.ts` — not CDN)
|
|
- **Tailwind CSS 4** (no config file, just `styles.css` with `@import`)
|
|
- **marked + marked-highlight + highlight.js** (Markdown rendering)
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
bun run build # Production build → public/dist/
|
|
bun run dev # Watch mode (JS + CSS)
|
|
bun run lint # ESLint
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Directory Layout
|
|
|
|
```
|
|
src/
|
|
main.ts # Entry point — imports components, starts Alpine
|
|
client.ts # All API calls (fetch-based, centralized)
|
|
types/index.ts # Shared TypeScript interfaces
|
|
utils.ts # Shared utility functions
|
|
theme.ts # Theme toggle logic
|
|
components/
|
|
chatManager.ts # Chat UI — message list, streaming, Markdown
|
|
imageManager.ts # Image generation/gallery UI
|
|
settingsManager.ts # Settings form UI
|
|
themeManager.ts # Theme Alpine component
|
|
navigationManager.ts # Page navigation Alpine component
|
|
public/
|
|
index.html # SPA shell
|
|
pages/
|
|
chats.html # Chat page template
|
|
images.html # Images page template
|
|
settings.html # Settings page template
|
|
styles.css # Tailwind entry point
|
|
```
|
|
|
|
### Key Patterns
|
|
|
|
- **Alpine.js components**: each `*Manager.ts` registers an `Alpine.data(...)` component. State lives in Alpine's reactive scope + localStorage for persistence.
|
|
- **API client**: all backend calls go through `src/client.ts`. Streaming uses NDJSON via `ReadableStream` reader.
|
|
- **Build pipeline**: Bun bundles `src/main.ts` → `public/dist/main.js`; Tailwind CLI compiles `styles.css` → `public/dist/styles.css`. Output is copied to `backend/web/static/` by the root `Makefile`.
|
|
- **No SPA router**: navigation is handled by Alpine component visibility toggling.
|
|
|
|
## Non-Negotiables
|
|
|
|
- ❌ No `any` type — use `unknown` and narrow
|
|
- ❌ No `as` type assertions
|
|
- ❌ No `@ts-ignore` or `@ts-expect-error`
|
|
- ❌ Fix all TypeScript and ESLint errors — don't ignore them
|
|
- ❌ No Alpine.js via CDN (it's bundled)
|
|
- ❌ Don't commit `public/dist/`
|
|
|
|
## Code Style
|
|
|
|
- 2 spaces, single quotes, semicolons required
|
|
- camelCase for variables/functions
|
|
- PascalCase for types/interfaces
|
|
- UPPER_SNAKE_CASE for constants
|
|
- Explicit error handling with try/catch
|
|
- User-friendly error messages in UI (not just console.log)
|