mathias/tapir

Files

T

mathias 7090fb1e40 docs: add architecture decision records (ADR-001..009)

Records the decisions from the S5 spike and the Full Grill as append-only ADRs:
Go not Python; no Supabase; standalone-first with brain as one sink; copy the
llm package; brain sink via HTTP brain-mcp; fresh outbound OAuth; captions-first
with STT deferred; Future C deferred behind the Stage 0 gate; trunk-based dev.

2026-06-02 10:31:00 +00:00

7.5 KiB

Raw Blame History

Architecture Decision Records — Tapir

Lightweight ADRs. Each records a decision, its context, and its consequences at the time it was made. Decisions are append-only: to reverse one, add a new ADR that supersedes it (note the supersession in both). This is the reversibility record the VISION guardrails refer to.

Status values: Accepted · Superseded by ADR-NNN · Proposed.

ADR-001 — Go, not Python

Status: Accepted (2026-06-02)

Context. The first design draft assumed a Python/FastAPI/arq stack. The homelab is a Go estate (template-go-web, template-go-agent, mcp-chassis, hyperguild/ingestion). A Python service would be the only one of its kind, outside every shared convention, chassis, and CI pattern.

Decision. Tapir is written in Go. Python is used only where it makes no sense not to (e.g. if an ML component later genuinely requires it — none does today).

Consequences. Reuses homelab Go conventions and the mcp-chassis auth pattern if/when Tapir exposes an MCP surface. Closes the door on the Python async ecosystem (acceptable — Go's concurrency model fits the watcher/worker shape).

ADR-002 — No Supabase; reuse existing Dex / ESO / Postgres conventions

Status: Accepted (2026-06-02)

Context. The draft proposed self-hosted Supabase for auth + RLS + secrets (Vault). The homelab already runs Dex (OIDC), ESO + 1Password (secrets), and a postgres18 instance that the May-2026 architecture review is actively de-coupling by blast radius. Supabase would bundle a second auth system, a second secrets store, and its own Postgres — three duplications of things just consolidated.

Decision. No Supabase. Auth, secrets, and persistence reuse the homelab's existing primitives: Dex for identity (when external identity is needed), ESO + 1Password for secret custody, Postgres with per-tenant role/grant and the tenant= namespace label scheme for isolation when Future B/C arrives.

Consequences. No new infra to operate or back up. Multi-tenancy uses the architecture review's SC7/P6 primitives rather than Supabase RLS. For Stage 0 (single user) most of this is dormant; it activates at Stage 1.

ADR-003 — Standalone-first; brain is one sink behind an interface

Status: Accepted (2026-06-02)

Context. Tapir was initially framed as both a standalone service and a brain-ingestion pipeline. The maintainer clarified that standalone is the more important of the two.

Decision. Tapir is a standalone service. Delivery of summaries is via a Sink interface with multiple implementations. The user's own store is the primary sink; the brain is one optional sink among others. The engine does not know or care which sinks are attached.

Consequences. Brain ingestion can never dictate the core architecture (a named drift signal in VISION). Homelab mode is "the brain sink is enabled"; it is not a separate build.

ADR-004 — Copy the `llm` package from `hyperguild/ingestion`; do not lift to a shared lib

Status: Accepted (2026-06-02)

Context. Spike S5 (infra/docs/superpowers/handoffs/2026-06-02-video-adapter-placement.md) examined what Tapir could reuse from hyperguild/ingestion. The internal/llm package (Client + Router) is stdlib-only and its Router implements exactly the Primary→Fallback pattern Tapir needs for local-first → BYO-AI. It is ~3.5 KB and stable.

Decision. Copy the llm package into Tapir and own it. Do not lift it into a shared module. Lifting would couple Tapir's release cycle to the monolith to save ~100 lines — a bad trade against the "standalone owes nothing" bias.

Consequences. Minor duplication. Tapir owes nothing to hyperguild/ingestion at the dependency level. Primary = local stack via LiteLLM/piguard alias; Fallback = user BYO key.

ADR-005 — Brain sink is an HTTP brain-mcp client, not the filesystem `brain` package

Status: Accepted (2026-06-02)

Context. hyperguild/ingestion's internal/brain package manipulates the brain git checkout on the local filesystem (os.WriteFile into brain/wiki/...). That assumes co-location with the brain repo — fine for the monolith, wrong for a standalone service where brain is one network-reached sink.

Decision. Tapir's brain sink is a thin HTTP adapter calling brain-mcp's brain_ingest tool. It does not import or replicate the filesystem brain package.

Consequences. The brain sink works regardless of where Tapir runs. Adds a dependency on brain-mcp availability when that sink is enabled (acceptable; sinks fail independently).

ADR-006 — Outbound OAuth (YouTube/Vimeo) written fresh

Status: Accepted (2026-06-02)

Context. hyperguild/ingestion's internal/oauth package is the MCP server's inbound auth (client_credentials, authenticating claude.ai). Tapir needs outbound authorization-code OAuth to YouTube/Vimeo with per-user token custody — a different concern that happens to share a name.

Decision. Write the YouTube/Vimeo OAuth client fresh using golang.org/x/oauth2. Store per-user refresh tokens via the homelab's ESO/1Password convention (ADR-002), not a new secrets system.

Consequences. No reuse from the monolith here. Token custody is the highest-value secret surface (see VISION Stage 2); it gets the existing, vetted secret path.

ADR-007 — Captions-first; audio-download + speech-to-text deferred

Status: Accepted (2026-06-02)

Context. YouTube's Data API does not expose transcripts. Options: official captions (clean, limited coverage) vs. audio download + local Whisper (broad coverage, ToS-grey, GPU-contending with the JEPA PoC on koala, breakage-prone via yt-dlp).

Decision. The core path is captions-only. When a video has no usable transcript, Tapir records "no transcript" and moves on. Audio-download + speech-to-text is a deferred, clearly-bounded optional component, not part of the core path or Stage 0.

Consequences. Some videos won't be summarized at Stage 0 — accepted. The "is this useful to me?" hypothesis is testable on captioned videos alone. Avoids GPU contention and ToS risk in the validated path.

ADR-008 — Future C (public multi-tenant SaaS) deferred behind the Stage 0 gate

Status: Accepted (2026-06-02)

Context. "Real users soon" was initially asserted, which would load Google OAuth verification, billing, and hardened multi-tenant custody early. Lowered to Future B (1–5 trusted users), with the maintainer as the real first customer.

Decision. Build for Stage 0 then Stage 1 (Future B). Public SaaS machinery (sign-up, billing, Google OAuth app verification at scale) is not built until the Stage 0 self-use gate passes and real external demand appears.

Consequences. Smaller, faster first build. The staged Definition of Success in VISION governs advancement. Reversible: if demand appears, a new ADR opens the Future C scope.

ADR-009 — Trunk-Based Development

Status: Accepted (2026-06-02)

Context. Platform-wide convention (homelab architecture review invariant; gitea-mcp #27): commit directly to main, one logical change per commit, every commit deployable.

Decision. Tapir follows TBD. Commit directly to main. No feature branches or PRs for solo/agent work; short-lived agent/<desc> branches only when parallel agents are active on the repo simultaneously. CI is the quality gate, not branch protection.

Consequences. Consistent with the rest of the estate. Depends on the direct-to-main write path tracked in gitea-mcp #35 (item #1).