Files

Offending Commit 764a7502a3 docs: add project docs, GitHub DX, fire-tools stamp

- CLAUDE.md with commands, structure, key constraints
- .claude/rules/ coding standards + workflows
- docs/architecture.md with design decisions
- .github/ CI workflow, issue templates, PR template
- LICENSE (MIT)
- .fire-tools.json initialization stamp
- README.md rewritten with features, quick start, stack table

2026-04-24 21:42:03 -05:00

2.5 KiB

Raw Blame History

Architecture: honcho-ui

Overview

Single-page application for browsing and interacting with a self-hosted Honcho instance. Configurable at runtime — no URLs baked in.

Stack: React 19, Vite 8, TypeScript 6, TanStack Router v1, TanStack Query v5, Tailwind CSS v4, framer-motion, openapi-fetch.

Key Components

Component	Location	Responsibility
API client	`src/api/client.ts`	openapi-fetch client, reads config from localStorage at call time
Query hooks	`src/api/queries.ts`	All TanStack Query hooks, typed via generated schema
Config	`src/lib/config.ts`	localStorage read/write, health check, Zod validation
Theme	`src/lib/theme.ts`	Dark/light theme via `data-theme` on `<html>`
Root route	`src/routes/__root.tsx`	Auth guard (redirect to /settings), Sidebar layout
Sidebar	`src/components/layout/Sidebar.tsx`	Nav with animated active indicator
Settings	`src/components/settings/SettingsForm.tsx`	Base URL + optional token, connection test

Data Flow

App boots → __root.tsx checks localStorage for config
No config → redirect to /settings
User saves URL (+ optional token) → loadConfig() returns it on every query
client.current getter recreates the openapi-fetch client on each call, always picking up latest config
TanStack Query caches responses; stale time 30s, retries 1x

External Dependencies

Honcho REST API — described by openapi.json (local copy, regenerate with pnpm generate:api)
No external auth provider — token is optional, detected via health check

Design Decisions

2026-04-24: Use CSS custom properties instead of Tailwind color tokens — enables instant dark/light switch via data-theme attribute without JS class manipulation per element.

2026-04-24: client.current getter pattern instead of module-level singleton — config can change at runtime (user updates settings) without requiring page reload.

2026-04-24: TanStack Router flat-route syntax — required by v1 Vite plugin; params cast as as never at callsites to satisfy the union type constraint without widening the app's own types.

2026-04-24: Token is optional — self-hosted Honcho instances may not require auth; checkConnection() probes the API to detect whether a 401 is returned, then surfaces the result in the settings form.

2.5 KiB Raw Blame History