Making a design decision explicit
Compare a draft with a revision that explains the choice and records the questions still to resolve.
Original draft
The service will use a queue for background tasks. We will add workers when traffic grows.
After revision
Requests place background jobs on a queue so users do not wait for them to finish. Workers process jobs independently. We still need to define expected job volume, acceptable delay, retry behaviour and failure reporting before approving the design.
- Reason
- Explain why the queue is needed.
- Assumptions
- Record expected load and acceptable delay.
- Open questions
- Define retries and failure reporting.
Illustrative draft and editorial feedback, not a captured response from Archie. Taffy’s local app reviews a selected section using the configured AI provider.
Why it exists
Engineers are expected to write architecture documentation but rarely get useful feedback while writing it. Taffy provides a structure for that work and an AI reviewer to help improve it before a design review.
Project versions
Each project contains versions. Each version has an overview and nine sections covering requirements, design, decisions, scaling and economics, diagrams, implementation structure, risks, evidence, and references. Authors can edit Markdown, use a structured form, or read a preview.
Diagrams can be uploaded or linked, organised by OSI layer, and reviewed against a checklist. System and C4 diagrams are included in every version; other diagrams can be added as needed.
AI review
Archie reviews one section at a time. It returns a Junior, Senior, Principal, or Staff level, a score out of ten, a direct summary, and suggested improvements. The feedback helps the author assess readiness for a design review.
How it works
Taffy combines a React interface with an Electron desktop app. Structured forms and the Markdown editor work on the same document, so authors can switch between them. A version exports as numbered Markdown files, a README table of contents, and an images folder. The result can be read outside Taffy.
Documents are stored locally and no account is required. AI reviews send the selected section to the configured model provider.
Repository drafts
Repository analysis is in progress. It uses selected material from a local repository to prepare architecture drafts. The user reviews and accepts or rejects each section; existing writing is never silently replaced. Selected repository material is sent to the configured model provider to generate drafts.
Taffy is a working macOS app used personally. The review coach is available in the local app; repository draft generation remains in progress.