mathias
deb8523d75
Operational context for independent agent sessions: orientation order, TBD + conventional-commit workflow, the three "looks reusable but isn't" traps (llm is copied not imported, brain sink is HTTP not filesystem, OAuth is fresh), the settled decisions not to reopen, the Clean Architecture/BDD stance, and a provenance trail back to the S5 spike and the llm source. Distills the operating knowledge surfaced during the 2026-06-02 planning+grill session.
tapir
Watches a user's YouTube/Vimeo subscriptions and, when a subscribed channel posts a new video, summarizes it into highlights and takeaways using a local-first AI stack with an optional, per-user BYO-AI fallback. Standalone-first; feeding a personal knowledge base ("brain") is one optional sink, not the reason Tapir exists. Written in Go.
Status
Pre-code. The repository currently holds the guardrail documentation — vision, decisions, architecture, data model, and behavior specs — committed before implementation so the design intent is version-controlled and the build has something to be checked against.
Read these first (the guardrails)
| Doc | What it is |
|---|---|
VISION.md |
Product vision, principles, and the staged Definition of Success. Stage 0 ("useful to me") is the gate before any multi-user work. |
DECISIONS.md |
Architecture Decision Records (append-only). Why Go, why no Supabase, standalone-first, captions-first, etc. |
docs/architecture/architecture.md |
C4 context + container diagrams, key sequence diagrams, and the Clean Architecture layering (Mermaid). |
docs/data-model.md |
Entities and the per-user isolation model (Stage 0 / Stage 1 scope). |
docs/use-cases/ |
Gherkin .feature files — the BDD behavior spec that seeds the test suite. |
Approach
- Clean Architecture / ports & adapters. A provider- and sink-agnostic engine depends only
on interfaces (
VideoSource,Summarizer,Sink,SecretStore). YouTube, Vimeo, the AI router, the user store, and the brain sink are adapters. "Standalone vs homelab" is a wiring choice, not two codebases. - TDD/BDD. The
.featurefiles are the living behavior spec; the use-case core is tested through fake adapters. Behavior is specified as executable scenarios, not prose that drifts. - Trunk-Based Development. Commit directly to
main, one logical change per commit, every commit deployable (see ADR-009). CI is the quality gate.
Conventions
Reuses homelab conventions: Go, Dex for identity, ESO + 1Password for secrets, Postgres for persistence. No new auth or secrets system (ADR-002).
Next
First implementation step: scaffold the Go service (engine + interfaces + the copied llm
package), captions-first, with the store and brain sink adapters — decomposable into
independent units suitable for a Claude Code swarm. Tracked as the first build issue.