Replace Vite/React scaffold with Go build spec
- AGENTS.md: build spec for Paperclip (constraints, conventions, 7 phases) - docs/phase-1..7: per-phase work, DoD, out-of-scope, risks - reference/: frozen decisions, stack+ports+budgets, content map, acceptance tests - agents/: persona and security policy drafts - Retires the React scaffold; history retained as record of the false start
This commit is contained in:
36
reference/decisions.md
Normal file
36
reference/decisions.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# Frozen decisions
|
||||
|
||||
**These are not open for reconsideration inside the build.** Changing any of them requires Sam's written approval and an ADR in this folder. Detail and reasoning: `../../resume_ai_system/plan/10-technology-plan.md` and `40-cull-register.md`.
|
||||
|
||||
| # | Decision | Chosen | Rejected, and why |
|
||||
|---|---|---|---|
|
||||
| D1 | Site shell | **Go + `templ` + HTMX** | React 19/Vite — node build + bundler for no UX gain. Svelte/Solid — no benefit for a server-rendered content site. Astro — credible runner-up, but adds a Node toolchain we control away. Leptos/Wasm — complexity overhead |
|
||||
| D2 | Templating | **`templ`** | `html/template` — stringly typed, fails at runtime not compile time. `templ` compiles to Go, so a broken view is a compiler error |
|
||||
| D3 | AI console | **One hand-written TS island**, ES modules | React island — second toolchain. No framework — xterm and SSE are plain-library concerns |
|
||||
| D4 | Markdown / highlighting | **Server-side** `goldmark` + `chroma` | Client-side Prism/marked — bundle weight, flash of unstyled code, two implementations for two modes |
|
||||
| D5 | Embedded data | **SQLite + FTS5** | Postgres — another container for a site with one writer. Redis — explicitly rejected previously, and unnecessary |
|
||||
| D6 | Vector store | **Qdrant** | ChromaDB — heavier footprint, weaker payload filtering, and it is the stack being retired. SQLite-vec — promising, less mature filtering. Weaviate/Milvus/pgvector — overkill |
|
||||
| D7 | Ingestion | **Prefect** (server already running) | Airflow — already abandoned once for RAM. n8n — retained for household automation only |
|
||||
| D8 | Query graph | **LangGraph, four nodes** | Flowise/Windmill/Activepieces — visual builders, not needed for 200 lines of Python. More agents — complexity that causes drift |
|
||||
| D9 | Model access | **OmniRoute only** | LiteLLM — would duplicate an existing gateway. Direct provider SDKs — violates house rule |
|
||||
| D10 | Retrieval | **Hybrid**: vectors + BM25/FTS5 → RRF → cross-encoder rerank | Vector-only — misses exact tokens (repo names, `LoRaWAN`, `MQTT`, dates) |
|
||||
| D11 | Memory | **None.** Stateless by design | Hindsight, TencentDB Agent Memory, LangMem, Engram, Headroom — all rejected *for this product*. A public assistant with no returning user gains nothing and gains a write path. Engram/Headroom remain part of Sam's own workflow and are documented as such |
|
||||
| D12 | Observability | JSONL trace + Langfuse Cloud free tier | Self-hosted Langfuse — 6 containers, ~2 GiB, unaffordable on `.13` |
|
||||
| D13 | Guardrails | **`mozilla-ai/any-guardrail`** | Prompt-only defence. The library is the mechanism; `agents/security.md` is the policy |
|
||||
| D14 | Agent tools | **None** | A code-execution sandbox was considered and rejected: a public CV site will not run model-generated code |
|
||||
| D15 | Voice | Reuse existing **Whisper + Piper** on `.13` | New STT/TTS stack — already solved |
|
||||
|
||||
## Standing rules
|
||||
|
||||
1. All models through **OmniRoute**.
|
||||
2. Secrets from **`~/.config/environment.d/`** only.
|
||||
3. Own service, own port, own folder.
|
||||
4. No LLM in the path of a fast or consequential action.
|
||||
5. **Mode A must work with every AI service stopped.**
|
||||
6. New footprint **≤ 1.0 GiB RAM, ≤ 4 containers**.
|
||||
|
||||
## Rejected before deployment
|
||||
|
||||
Airflow · self-hosted Langfuse · Trigger.dev · LiteLLM · second Garage instance · OpenCode as a "brain" service · Flowise · Windmill · Activepieces · Helm/Helicone · Multica · Archon · CAO CLI · AgentPipe · CrewAI · nine documentation platforms.
|
||||
|
||||
**Why this list is kept:** "alternatives considered" is a senior signal, and it converts a cull from a subtraction into an exhibit. The public site gets a short page listing these with the reasoning.
|
||||
Reference in New Issue
Block a user