Live product · open source · hosted AI or local inference
Archwoven
Turn ideas and repositories into architecture you can explore, inspect and edit.
- Problem
- AI diagrams need an editable model and inspectable source evidence.
- Decision
- Keep an editable, evidence-aware system model and reserve AI spending before every paid attempt.
- Result
- 4 views · SVG, PNG & JSON exports
Hosted AI or local inference. Costs are estimates; source coverage stays explicit.
Problem
An unfamiliar codebase is difficult to explain, and a polished AI-generated diagram can conceal unsupported connections. I wanted a product that helps someone move from an idea or repository to an explorable model, inspect where its claims came from, refine it and take the result into a review or handover.
My contribution
I built the product from the interactive workspace through model validation, repository ingestion and extraction, provider integration, job recovery, storage and deployment. The engineering work also includes per-task usage reporting, spending admission controls and evaluation harnesses, so the AI feature has an inspectable operating model as well as a usable interface.
AI usage, cost & spending controls
AI spending is part of the product design. Each task exposes what it used, while a separate ledger decides whether the next paid attempt can begin.
Account for the whole task
Last task shows the provider and model, input and output tokens, cache writes and reads, repairs, retries and estimated API cost. Repairs and retries contribute to the task rather than disappearing behind a successful final diagram. The provider invoice is authoritative; token-based estimates are not a billing receipt.
Reserve before spending
Before every paid attempt, the server atomically reserves its worst-case input and output cost against visitor, network, daily, monthly and annual caps. Admission counts settled spend plus held reservations. Repairs and retries need their own reservation; reaching a cap pauses new paid calls while existing diagrams remain usable when hosting and storage are healthy.
Keep unknown usage visible
Missing usage is marked incomplete, and unknown prices display Cost unavailable. Missing usage, provider failures and crashes retain the spending hold until reconciled. A reported charge above its reservation pauses paid work for inspection. An unknown charge cannot silently become zero.
Separate local inference from free infrastructure
Ollama runs show Local inference with no external API charge. Hardware and electricity are not measured. Hosted task estimates also exclude Vercel and Redis costs; the deployment guide calls for monitoring those services separately.
Constraints
- Read repository source without executing it; pin evidence to the analysed commit and keep coverage gaps visible.
- Validate a structured system model before rendering; distinguish structural validity from architectural correctness.
- Make editing, recovery and exports useful beyond the generation step, including when paid AI calls pause.
- Bound paid attempts before inference, including repair and retry costs, across concurrent hosted requests.
- Support hosted AI and local/private inference without presenting local compute as cost-free.
Architecture & consequential decisions
The engineering decision
Keep an editable, evidence-aware system model and reserve AI spending before every paid attempt.
- Validate modelTyped JSON → graph checksBounded repair before rendering
- Inspect evidenceDescribed · supported · inferredClaims link to the analysed commit
- Track AI usageTokens, cache, retries and costReserve spending before paid attempts
Usage visibility + spending admission
AI spending is part of the product design. Each task exposes what it used, while a separate ledger decides whether the next paid attempt can begin.
Why this choice?
Keep an editable, evidence-aware system model and reserve AI spending before every paid attempt.
Alternative: Generate only a finished picture. A picture is easy to share but loses the editable model and inspectable claims. Typed JSON adds validation and rendering work, while supporting multiple views, refinement and portable exports.
ONE MODEL, MULTIPLE VIEWS
A description or extracted repository becomes typed JSON, then passes schema and graph checks before deterministic rendering. Bounded repair addresses invalid output. The same system model supports architecture, sequence, data-model and component-detail views, plus SVG, PNG and editable JSON exports. Validation checks structure; it cannot prove every architectural claim.
EVIDENCE SURVIVES THE DIAGRAM
Components and relationships distinguish described, source-supported, inferred and proposed claims. Repository evidence links to files at the analysed commit. Spring Boot and FastAPI receive framework-aware extraction; other repositories receive a bounded source-module and import map. A static import is not proof of a runtime interaction.
A WORKSPACE BEYOND THE FIRST RESPONSE
Users can arrange and rename elements, refine in words, undo changes and export their work. Hosted jobs and recovery copies use Redis; the local/private deployment uses SQLite and Ollama. Hosted recovery copies expire 24 hours after the last change, while the browser retains up to 20 diagrams until deleted or site data is cleared. JSON downloads provide a portable editable copy.
ADMISSION INCLUDES STORAGE AND SPENDING
Hosted job admission reserves temporary storage capacity before inference and checks paid-attempt reservations against spending caps. Full storage refuses new work before a provider call. Redis outages block server-backed saves and recovery; a diagram already on screen remains downloadable. These boundaries keep resource failures visible in the product flow.
SEPARATE PRODUCT CHECKS FROM MODEL EVIDENCE
Browser suites exercise job lifecycle, keyboard use, exports, responsive layouts and accessibility with recorded fixtures. Separate real-provider runs retain outputs, model identity, usage, latency and ground truth. Fixture success establishes application behavior, not live-provider quality; the small recorded evaluations do not establish general diagram accuracy.
Alternatives considered
Generate only a finished picture
Trade-off: A picture is easy to share but loses the editable model and inspectable claims. Typed JSON adds validation and rendering work, while supporting multiple views, refinement and portable exports.
Treat source imports as runtime topology
Trade-off: That would produce more confident diagrams at the cost of unsupported connections. I keep narrower extraction coverage and explicit provenance, accepting visible gaps.
Show cost only after a successful task
Trade-off: A completed-task total cannot stop concurrent calls from overspending, and can hide failed attempts. Pre-call reservations control admission; reported task usage provides a separate explanation of consumption.
Make the product hosted-only
Trade-off: Hosted inference lowers setup effort but requires external model calls and shared limits. A local Ollama path adds deployment work and hardware requirements, while supporting private inference.
What the results show
Usable product surface
4 views · 3 export formats
Architecture, sequence, data model and component detail; SVG, PNG and editable JSON. Product capabilities at the reviewed revision, not a quality score.
One recorded task
16,121 tokens · ~$0.0775
Public MCP Observatory import recorded 2026-10-20: 14,748 input + 778 output + 595 cache-write tokens, no cache reads, repairs or retries. Estimated API cost only; not a price guarantee or total infrastructure cost.
Recorded description evaluation
7/7 first-pass valid
Seven hosted descriptions across four view types, recorded 2026-10-17; median 14.2 seconds and $0.2726 total. Small saved evaluation; structural validity is not architectural correctness.
Recorded import evaluation
5/6 first-pass valid
Six hosted imports across four pinned repositories, recorded 2026-10-17; median 35 seconds and $0.10–0.32 each. These runs are separate from the later single-task example and are not general accuracy or pricing claims.
Limitations
- Framework-aware extraction covers Spring Boot and FastAPI. Other repositories receive a bounded module/import map; static analysis cannot establish every runtime connection.
- Schema and graph validity do not guarantee correct architecture. Evidence categories and unknowns need the reader’s judgment.
- Recorded provider evaluations are small, dated runs. Browser fixtures and CI checks do not establish live-provider quality or every deployment’s acceptance.
- Task costs are estimates from reported usage and supported prices. Missing usage stays incomplete; provider invoices and infrastructure charges require separate review.
- Hosted recovery is temporary. Browser copies depend on site data; download JSON to keep editable work.
- Repository-documented browser coverage does not establish screen-reader, physical-device, Firefox or Safari-application behavior.
Reproduce it yourself
- Open the linked live product, then its workspace. Start with an available diagram to inspect and export without requesting new AI work.
- For a new task, describe a system or import a public repository. Hosted AI has shared usage limits; inspect Last task for model identity, token usage, repairs, retries and estimated cost.
- Use Node.js 24 and the repository’s pinned pnpm 12.9.1 for a local checkout. Follow the pinned README for Ollama setup or a hosted provider configuration.
- Run pnpm build, pnpm test, pnpm typecheck and pnpm bench:selftest using the testing guide’s setup instructions.
- Read the saved provider evaluations and visual provenance alongside their outputs. Paid evaluation reruns require their own explicit allowance and ledger.