> **Sole engineer (personal project)** · February 2026 to present
> Source: https://www.simonbetton.com/case-studies/onlydoge.md (markdown only; there is no HTML page for this document).
> Index of case studies: https://www.simonbetton.com/case-studies/index.md

# Case study: OnlyDoge, a Dogecoin block explorer and analytics platform

## Quick facts

|  |  |
| --- | --- |
| Role | Sole engineer: product, architecture, frontend, backend, data platform, infrastructure, documentation |
| Product | OnlyDoge: a Dogecoin block explorer, an authenticated explorer and analytics API, and a chat surface where a model answers chain questions only through read-only tools |
| Timeline | Web application from February 2026, indexer and platform from March 2026; both ongoing |
| Team | One person, plus coding agents used as tooling under review |
| Repositories | Two public repositories on GitHub (web application; indexer and platform API) |
| Live | onlydoge.io and platform.onlydoge.io |
| Size | About 57,000 lines of TypeScript across 320 source and test files, as of September 2026 |
| Verification | 441 passing tests across 76 files; the two suites run in about 6.5 seconds combined |

## Overview

OnlyDoge reads the Dogecoin blockchain and presents it three ways: a conventional explorer (blocks, confirmed transactions, addresses, live mempool, search); a chat surface where a model answers questions by calling read-only tools against the same data and streams structured cards alongside its prose; and an HTTP surface designed to be read by agents, with negotiated Markdown, standards-based errors and a published description of its own endpoints.

Underneath sits a system I also had to build: an indexer that walks Dogecoin from genesis through Dogecoin Core RPC, stores raw block snapshots in object storage, materialises UTXO and balance state into ClickHouse, and exposes authenticated explorer and analytics reads behind per-key budgets. The web application talks only to that platform API.

I built all of it alone, and one engineering problem shaped every decision.

## The problem

A block explorer is public data without interpretation. A transaction page is a correct and nearly useless answer to "did this payment go through, and why did it cost that much?"

Putting a model in front of that data usually makes it worse. A model asked about a transaction hash will produce a fluent, confident, invented answer, because the hash looks like something it has seen before. For financial records that failure mode is the whole risk, and it cannot be fixed with a better prompt. A prompt is a request. A jailbreak is also a request.

There was a supply-side constraint too. The indexer goes through long catch-up phases after a restart, a schema change or a rebuild; a full raw sync from genesis takes days. During those windows the honest product behaviour is a specific statement about what is unavailable and roughly how long the wait is, rather than an empty page, a spinner, or a model guessing.

So the design goals were:

- Every chain fact in an answer traces to a tool result, never to model memory.
- The product refuses categories of question it should not answer, and the refusal does not depend on the model choosing to comply.
- Degradation is informative, and the figure the user sees is the figure the indexer reported.
- The data underneath is reproducible from the chain and checked against an independent source.
- The whole thing is legible to non-browser clients without a second codebase.

## Decisions

| Decision | Alternative | Why |
| --- | --- | --- |
| Financial refusals in code before the model runs | Prompt instructions only | Requests matching nine financial-advice phrasing patterns are refused before a model call; the server writes the refusal into the stream itself |
| The model composes SQL; the platform parses and bounds it | Fixed query templates in the web application | Validation, cost estimation and rate limiting stay with the service that owns the warehouse, and new supported questions ship without a frontend change (recorded as an architecture decision, 1 June 2026) |
| Analytics reads only below the finalised tail | Read the latest processed block | An aggregate answer must not be invalidated by a reorg thirty seconds after it is given; the validator refuses transaction and balance queries that lack a finalised-height predicate |
| Explorer reads through the authenticated platform API, with upstream failure shown as maintenance | Keep the earlier unauthenticated explorer backend | Partial empty explorer data is misleading; the earlier Typesense-backed explorer was retired (recorded as an architecture decision, 24 May 2026) |
| Model-emitted UI passes one allowlist | Render whatever the model emits | Six action types, five navigation hosts and seven read-only tools are permitted; everything else is rejected with no side effects |
| Resolve explorer data before the HTTP response starts | Stream a shell immediately | A missing block returns a real 404 and an upstream failure a real 500. Non-browser clients cannot read a "not found" message rendered inside a 200 |
| Chat history stays on the device across two storage engines | Server-side persistence | Removes a class of privacy question, at the cost of a shared contract test suite across SQLite-in-Wasm and IndexedDB |
| Never migrate or delete legacy chat storage | Migrate and clean up | A rollback must not damage data written by a version the user might return to; a contract test asserts the legacy keys are never read |
| Ban type assertions, `any` and `unknown` across the web application | Trust code review | The cheapest way for a coding agent to make types fit is an assertion, and assertions are invisible at review scale |
| Conservative indexer defaults checked into the repository | Tune for peak throughput | A backfill that finishes slowly beats one that exhausts warehouse memory hours in |

## Guardrails that do not depend on the model

### Refusals before the model

The system prompt says the assistant will not give buy, sell or hold recommendations. That is necessary and insufficient. So the financial boundary is a deterministic classifier of nine phrasing patterns that runs on the last user message before any model call. A match never reaches the gateway; the server synthesises the refusal directly into the message stream, so the client sees an ordinary streamed assistant turn. This guarantees refusal for matching inputs, not detection of every advice request: unfamiliar phrasing or adversarial wording can miss the patterns.

Questions the curated fact surface cannot answer, such as change-adjusted economic transfer value, are declined deterministically inside the analytics tool, which names the limitation and offers a supported alternative instead of returning a plausible invented number. That check runs after the model chooses the tool, not before it; the pre-model path covers only the financial boundary.

### Model-authored SQL, validated by the service that owns the data

Aggregate questions ("average fee last week", "richest addresses", "current mempool fee distribution") run against three curated analytics tables in ClickHouse. The model first reads a live schema description from the platform: table and column descriptions, worked examples, the required parameter placeholders, the constraints, and an explicit list of unsupported question classes. It composes a query. The platform then validates it before anything touches the warehouse:

- One statement, one SELECT, no trailing semicolons, at most 16,384 characters.
- The SQL is parsed into an abstract syntax tree. Every referenced table must be one of the three curated tables or a common table expression defined in the same query; CTE names are collected from the tree so an alias cannot impersonate a table. Star selects are rejected by walking the tree, so the rule holds inside subqueries and CTEs.
- FINAL, SETTINGS, FORMAT and INTO OUTFILE are rejected by keyword checks that run over a copy of the SQL with comments and string literals stripped, so a quoted value cannot trigger a false rejection and a comment cannot smuggle a keyword past.
- Each table has a required-predicate policy, also checked over the stripped SQL: transaction facts must be bounded by both time placeholders and by the finalised-height placeholder; balance snapshots by finalised height; mempool samples by sample time. The placeholders are filled by the server, so the model chooses the shape of the question and the server chooses the window.

After validation the platform runs a cost estimate and rejects the query if the estimated rows or bytes exceed budget. The query then executes through a separate analytics warehouse client, with its own credential, under warehouse-enforced limits: 5 seconds, 50 million rows read, 5 GB read, 1,000 result rows, a seven-day maximum window. Analytics draws on a separate per-key budget of 30 requests per minute with at most two concurrent queries, alongside the ordinary budget of 300 protected requests per minute per key.

Generated SQL is internal tool input throughout. It is not rendered, not persisted in local chat history, and the model is instructed not to explain it. Users see prose, a result table rendered by the application from columns and rows, warnings, and the finalised block height the answer was computed against.

### Model-emitted UI behind an allowlist

When a structured card helps, the model emits a small declarative UI language rendered through a fixed component library. Model-authored UI is an injection surface, so every action passes one validation boundary: six action types are allowed, navigation is restricted to HTTPS URLs on five host suffixes, and follow-up buttons can invoke only seven named read-only tools. Mutation-style components are excluded from the library and from the prompt. A research document on generative UI security preceded the implementation, and its core finding shaped the design: the library has no prompt flag for "queries only", so enforcement has to live in the tool provider and the action handler rather than in prompt text.

### Grounding as a hierarchy

Three sources carry three authority levels. The platform API is authoritative for anything on-chain. CoinGecko supplies market context and is rendered with attribution and observation date. Web search is explicitly non-authoritative and runs behind a locked policy: three allowlisted domains (the Dogecoin project site, the foundation site and GitHub), English only, a one-year recency window, five results. A broader open-web policy exists in code but is not the default; the policy module cites the research branch that decided it.

The tool loop has hard ceilings: eight read-only tools plus provider-executed web search, at most eight tool-calling steps, a thirty-second total budget, and only the last twenty messages sent to the model. The request abort signal propagates to the model call, so a user navigating away stops the work. There are no write tools in the surface for a prompt to reach.

### Honest degradation

The platform models readiness as three flags, current state, history and analytics facts, and history-dependent reads return HTTP 425 with a specific message until the history index is marked ready. When a chat tool's platform read fails, the tool wrapper reads the public status snapshot, takes the longer of the sync and processing estimates, ages it by the snapshot timestamp, and streams a typed notice with the phase, progress and an absolute expected-at time. The same humanised wait is thrown back into the tool error so the model repeats the identical figure rather than inventing a friendlier one. The interface recomputes the remaining wait from the absolute timestamp, so a thread reopened an hour later is still right. A rejected API key or exhausted quota skips the status lookup, because indexer progress is irrelevant to those and reporting it would mislead.

## The data platform underneath

The chat surface is only as good as the system it reads, and that system is the larger engineering problem.

A long-running indexer walks Dogecoin from Core RPC, writes raw block snapshots to S3-compatible object storage, and projects canonical outputs, spends and processed block identity into ClickHouse. Raw sync and processing are separate stages with separate progress tails, so raw retrieval can run ahead of projection work.

Four mechanisms make it survivable in production:

- A primary lease in the PostgreSQL metadata store, refreshed on a heartbeat and claimable after a fifteen-second staleness window, is taken with a compare-and-swap write so two indexer containers cannot both hold it. A new container waits for the old lease to expire rather than double-writing, which is what makes rolling deploys safe.
- A progress watchdog (three minutes by default) terminates the process when forward progress stalls, logging the stage, both tails and the age, because restarting from a checkpoint is cheaper than debugging a wedged process.
- A reorg-active window replays the last ten processed blocks by default on tip updates, with a finalised tail that far behind processing. Analytics reads only below the finalised tail.
- Missing prevouts (a spend whose creating output is not present) are repaired in place; earlier versions had to rematerialise current state from scratch.

Address-heavy explorer reads go through address-ordered read tables maintained by materialised views, so an address lookup is a prefix scan rather than a scan over write-optimised facts, and current-state UTXO lookups use bounded limit-by-key reads instead of the FINAL modifier so hot reads do not pay merge cost. Warehouse memory tuning is checked in rather than left in a shell history: server memory capped at 80 percent of RAM, four query threads and one insert thread, and external group-by and sort thresholds set to spill early. System log retention is capped at three days because a long backfill will otherwise fill the disk.

Access is per API key. Tokens are returned once and only a hash is stored. Audit events record the acting key without storing the token or request body. The first key can be created unauthenticated to bootstrap a deployment, and that route closes once a key exists.

## Domain boundaries

The platform code is organised the way domain-driven design would organise it, although the repository does not use the label. It has four modules, each one a bounded context: access control (API keys, tokens, budgets, audit events), the indexing pipeline, explorer queries, and analytics queries. Each module has the same layers: a domain layer for entities and invariants, an application layer for use cases, contracts that act as ports, and infrastructure adapters for the outside world. A small shared kernel holds what every module needs. The direction of dependencies is declared as architecture zones in the static-analysis config. Applications may import a module only through its public entry point, the domain layer may import only the shared kernel, and the shared kernel imports nothing. Boundary violations are reported as warnings rather than failing CI, a gap I would close.

The shared language is written down as well. The platform glossary defines fifteen terms, each with the wrong words to avoid: an API key is not a user or an account, an API token is not the API key it proves control of, and an analytics query is not a raw SQL endpoint. The same words are used in the code, the API documentation and the agent context, so a person and an agent reading any of them get the same meaning.

## Built to be read by agents

Request middleware runs ahead of the router, so unknown paths return a real 404 before the application shell renders: Markdown with sitemap and discovery links for non-browser clients, RFC 9457 problem details under the API paths, HTML for browsers. Route existence is derived from the generated route tree rather than a hand-maintained list. Every problem type's definition lives in one place and is rendered into the developer page and published into the site's OpenAPI 3.1 document from that same source, so documentation cannot describe behaviour the code does not have. Content negotiation uses a quality-value parser in which the most specific media range wins and a specific `q=0` overrides a wildcard; negotiated variants carry Vary and no-store so a CDN cannot serve HTML to something that asked for Markdown. Error pages default to Markdown, because browsers always declare `text/html` and anything that did not is not a browser.

Chat responses carry IETF RateLimit headers, including on requests rejected before acceptance, so a client can self-throttle. A deprecated transport alias carries Deprecation, Sunset and Link headers with a dated sunset. Discovery resources include an llms.txt document, an agent instructions page, Markdown variants of every information page, a sitemap and a Schema.org JSON-LD graph. The agent instructions page states limits as well as capabilities: do not infer ownership from an address, do not describe gross outputs as economic transfer value, treat a 404 as definitive.

A verifier script requests the built site as each of eight named crawler user agents and checks the negotiated representations, structured data, problem-details shape for every error class and the exact rate-limit header syntax, aborting loudly if edge bot protection intercepted the request so an infrastructure block is never mistaken for an application bug.

That last point matters in production. The site sits behind managed bot protection, and the firewall exception for a short list of public discovery paths is written knowing that a user-agent string is spoofable and is not authentication. Agents outside that allowlist are challenged at the edge, which I come back to below.

## Working with coding agents

Coding agents worked on the web repository under my review, on two Cursor branches, a Codex branch, a Claude Code branch and a Vercel branch, alongside my own feature and research branches. Five of the eight pull requests merged into the web repository came from those agent branches; by commit count that is nine of 97 non-merge commits, because agent work tended to arrive as one large squashed change. The platform repository had no agent branches; its only bot contributions are two Dependabot bumps.

Three things made this workable.

The first is a guardrail that is checked rather than reviewed. A custom script walks the TypeScript syntax tree of the whole web application and fails the build on type assertions, the `any` keyword and the `unknown` keyword. Eight vendored registry components and the generated route tree are exempted through an enumerated list with the reason documented in the gate itself, so the exemption cannot quietly grow. The script runs in the lint step, which runs in the single verification command, which runs in CI on every push and pull request.

The second is treating agent skills as a supply chain. Both repositories vendor their skills and pin them in a lockfile recording source repository, path and content hash: 28 on the web side, 25 on the platform side. Executable instructions pulled from third-party repositories deserve the same discipline as any other dependency.

The third is writing for two audiences. Both repositories carry an architecture document and a domain glossary that defines each product term along with the wrong terms to avoid and an example dialogue between a developer and a domain expert. The glossary entries that say "gross output value is not transfer value" and "avoid calling this an indexer API" were the most effective tool I found for stopping agents drifting into plausible but wrong domain language across many sessions. The web repository has two architecture decision records and a cutover rollback runbook with named triggers and data-handling constraints; the platform repository has a production runbook, a destructive rebuild runbook, and one decision record, for delivering mempool watch notifications through ZMQ, PostgreSQL NOTIFY and a one-shot server-sent event stream without adding infrastructure.

Four features were preceded by a research branch: the assistant runtime and gateway choice, web search source policy, local relational chat storage, and generative UI security. All four research documents landed on 16 July 2026, the implementations the following day. The pattern that worked was to give the agent a narrow question and a document to produce, read it, make the decision myself, and only then hand over an implementation task with the decision already made.

## Verification and release

Both repositories run the same verification command locally and in CI. The web command chains the strict typing gate, TypeScript in strict mode, Biome for formatting and lint, and the test suite, with a dependency audit on every push. The platform runs lint, typecheck and tests, then builds the production image as a separate gated job. A weekly security workflow runs CodeQL, dependency review, secret scanning and an image vulnerability scan that fails on critical or high findings for which a fix exists. Images publish for amd64 and arm64 with SBOM and provenance attestation.

From May to early September 2026 the production deploy was a manual, environment-protected workflow. It validated the environment, ran the full quality gate, built and pushed an image, resolved the tag to an immutable digest and deployed that digest. It refused to proceed if containers from a previous deployment shape still held ports or could compete for the indexer lease. It then checked liveness, heartbeat, the OpenAPI document and indexer health, and ran a production end-to-end suite. That suite created a disposable API key, exercised authenticated reads, per-key rate limiting and the documented 425 contract, compared the latest indexed block against an independent public Dogecoin API within a configured lag, and tore down what it created.

On 3 September 2026 I removed that workflow along with the separate local, managed and production compose files, and cut the platform down to one deployment shape: a single compose stack that anyone can run on one Docker host. Publishing is now separate from deploying. A version tag runs the quality gate, then publishes a multi-architecture image with SBOM and provenance attestation. The operator pins that image by digest in an override file, and rollback is redeploying the previous digest. CI also runs the production adapters against real services on every pull request and push to main. The cost is that nothing now deploys automatically or runs an end-to-end check against production after a deploy; the runbook's health and status checks are manual. The trade-off is one deployment path that anyone self-hosting can reproduce, in place of automation tied to my own server. I would bring the post-deploy suite back as a runbook command that works against any deployment.

Container health does not prove indexing freshness. The production runbook says so, citing the May 2026 recovery in which every container was healthy while the indexer was stuck on a missing prevout, the failure class the in-place repair added in June now handles.

## Technologies and standards

- Frontend: TypeScript, React 19, TanStack Start and Router, TanStack Query, Vercel AI SDK v6 UI message streams, assistant-ui, OpenUI, Tailwind v4, GSAP, Framer Motion, Recharts, SQLite compiled to WebAssembly over the Origin Private File System with Dexie over IndexedDB as fallback, Vercel.
- Platform: Bun, Elysia, ClickHouse, PostgreSQL with Drizzle, S3-compatible object storage, Dogecoin Core RPC, node-sql-parser, Docker, Caddy, GitHub Actions, GitHub Container Registry.
- AI runtime: Vercel AI Gateway against GPT-5.5, provider-executed web search, CoinGecko market data.
- HTTP and discovery: RFC 9457 problem details, OpenAPI 3.1, content negotiation with quality values and Vary, IETF RateLimit header fields, Deprecation and Sunset headers, HTTP 425 for not-ready reads, Schema.org JSON-LD, sitemap, llms.txt.
- Quality and supply chain: TypeScript strict mode, a custom AST typing gate, Biome, fallow architecture analysis, CodeQL, dependency review, gitleaks, Trivy, SBOM and provenance attestation, digest-pinned deploys, hash-pinned agent skills.

## Results

| Measure | Value |
| --- | --- |
| Tests | 441 passing across 76 files: web 329 in 3.7 s, platform 112 in 2.8 s (two integration tests skipped without Docker) |
| Typing gate | Zero type assertions, `any` or `unknown` in web application source outside eight enumerated vendored files; enforced in CI |
| Chat surface | 8 read-only tools plus web search, no write tools, 8-step and 30-second ceilings, last 20 messages |
| Analytics guard | AST-checked SQL, 3 allowed tables, mandatory finalised-height and time predicates, pre-execution cost estimate, 5 s / 50 M rows / 5 GB / 1,000 rows / 7 days, 30 per minute and 2 concurrent per key |
| Generative UI | 6 action types, 5 navigation hosts, 7 follow-up tools |
| Indexer safety | 15 s lease staleness with compare-and-swap claim, 180 s progress watchdog, 10-block reorg window |
| Skills supply chain | 53 vendored skills, each pinned by source, path and content hash |
| Agent-facing conformance | Verified against 8 named crawler user agents on a production build |

The performance and discoverability work of 9 September 2026 cut the hero image from a 1,468,655-byte PNG to WebP variants of 39,886 bytes at 1254 px and 9,116 bytes at 480 px, and the interface logo from 166,541 to 3,748 bytes; landing pages that all declared the homepage as canonical became self-canonical, and missing explorer records went from a 200 shell to a real 404. I did not measure field Core Web Vitals, so I claim no improvement there.

An AI-assisted audit three days earlier scored the site 49 out of 100 on SEO readiness. I committed the report unedited, including the categories it could not measure, because an audit that presents unmeasured categories as passing is worse than no audit.

I do not have traffic, user or revenue figures for this and will not guess.

## Limitations and what I would change

In September 2026 the production indexer was part-way through a full raw sync from genesis, with processing not yet started. The explorer treats that as maintenance and the chat reports the wait, but the product is not useful to a visitor during those days, and a multi-day resync whenever the raw store has to be rebuilt is a cost of the current single-instance design.

Agents outside a short user-agent allowlist are challenged or denied at the edge, including on the path where they would discover the error format. The application-level work is done; the operator decision about how far to open the firewall is not.

Rate limiting is in-process on both sides. That is correct for a single-region, single-instance deployment and wrong the moment either service scales horizontally. It is the reason the indexer has a leadership lease while the API rate limiter has no equivalent.

The redesign and the discoverability work each shipped as one large change, so I can confirm the improvements but cannot rank them. The problem-details definitions became a single source for documentation and the OpenAPI document only after the two had drifted apart once; that structure should have existed from the first error type.
