Inside ichi · 07

Architecture Decisions

The decisions that shaped ichi, in the open. Problem, options, decision, trade-off, outcome.

Architecture Decision Records (ADRs) capture why, not just what. Implementations change; a good ADR explains the thinking so the next decision has context.

ADR-001 · A static site

  • Problem: Publish essays reliably, at near-zero cost, with the smallest possible attack surface.
  • Options: A CMS (WordPress); an app framework (Next.js); a static generator.
  • Decision: Static generation with Hugo.
  • Trade-off: No server-side features without extra work; every change needs a build.
  • Outcome: Sub-500ms loads, no database to breach, no runtime to patch, negligible hosting cost.

ADR-002 · Markdown in a local vault

  • Problem: Where should knowledge live so it survives tool changes and stays fully owned?
  • Options: A hosted knowledge app; a database; local Markdown files.
  • Decision: Local-first Markdown (Obsidian over plain files).
  • Trade-off: Less enforced structure; no real-time collaboration.
  • Outcome: Knowledge is diffable, portable, and outlives any single app. Nothing is trapped behind an API.

ADR-003 · Claude CLI as the reasoning engine

  • Problem: Automation needs judgment — drafting, reviewing, answering — not just scripts.
  • Options: Hosted bot APIs with a fixed budget; a self-hosted model; a scriptable CLI.
  • Decision: Claude CLI, invoked from ordinary automation.
  • Trade-off: We build the orchestration ourselves.
  • Outcome: Reasoning becomes a Unix-style tool — pipe text in, get judgment out — usable by any cron job or script, on our terms.

ADR-004 · Human approval at every gate

  • Problem: How much autonomy should the agents have?
  • Options: Full autonomy (agents act); no autonomy (agents only advise); gated autonomy (agents act, humans approve).
  • Decision: Gated. Agents draft, monitor, and propose; a person approves anything that ships, spends, or publishes.
  • Trade-off: The human is a bottleneck by design.
  • Outcome: Automation earns trust by being reversible and gated — not by being unsupervised. The bottleneck is the safety mechanism.

More ADRs — why Telegram, why not a database, why an AI Executive Office — are answered in short form in Chapter 12.