Primary question: Do the typed JSON contract, deterministic checks, and single-file HTML output make architecture review faster and more trustworthy than the diagram tool you use today?
RepoDaily adoption score
RepoDaily rates this as 92/100 (strong) for adoption: evidence, installation path, production risk, differentiation, license clarity, and AI/agent fit are scored from the article sources and adoption notes.
5 source(s) across 3 source category/categories, plus a RepoDaily-specific evidence module when available.
6 workflow step(s), 5 next-action step(s), and 3 command/install signal(s) were detected.
Trending momentum is +1,002 stars, with maintenance/release/issue signals counted when present.
Risk is marked medium, with 5 security note(s) and 4 explicit skip condition(s).
3 opportunity lens item(s), 5 alternative(s), and 4 type-specific section(s) support differentiation.
License source or license wording is present.
7 AI/agent-related signal(s) were detected in the article text and metadata.
Project overview
Archify is an agent skill — a package you add to Raven, Cursor, Claude Code, Codex CLI, or OpenCode — that turns a codebase or a written system description into a polished, interactive system map, directly in chat. Installation is one command: `npx skills add tt-a1i/archify -g`. The output is a single self-contained HTML file covering five diagram types — architecture, workflow, sequence, data-flow, and lifecycle — with four presets, dark and light themes, built-in brand marks, and finite motion. Alongside the HTML you get crisp exports to PNG, SVG, WebM, and 1200×630 share cards.
The differentiator is not the drawing quality; it is the claim that every interaction stays grounded. Archify uses a typed JSON intermediate representation and deterministic checks, and its README promises you can search nodes, optionally open revision-verified source, trace upstream and downstream authored reach and exact routes, compare roles, and play guided stories without inventing topology. For code review, two validated snapshots can be compared as Before / Delta / After, with exact added, removed, changed, moved, and rerouted facts — the kind of output you could actually attach to a pull request.
The project is versioned and moving quickly. The development identity is v2.16.0-dev.0, sitting in the changelog's Unreleased section with bounded Viewer localization: all five renderers now accept `meta.locale` values `en` and `zh-CN` for renderer-owned UI, accessibility copy, default legends, and document titles, without translating authored content. The last tagged release, 2.15.0 (2026-08-17), shipped authored brand identity with 107 provenance-backed vector marks and an `archify brands` discovery command, sequence column fitting via `meta.column_fit: "spread"`, and an isolated DeepSeek Harness bundle named `@tt-a1i/archify-dsh`. Release 2.14.0 (2026-08-11) added `archify visual-check <output.html> --json`, which measures first-screen containment at 1440×900, 1600×1000, 1920×1080, and 2048×1320.
Lineage and licensing are worth stating plainly. The LICENSE file is MIT, with two copyright lines: 2025 Cocoon AI for the original "architecture-diagram-generator" and 2026 tt-a1i for Archify. The renderer package lives in `archify/`, supports Node.js 18 and later, and CI covers Node 18, 20, 22, and 24. On 2026-08-27 the repository sat at rank #5 with 1,002 stars in the period, primary language HTML, and a Trendshift badge plus two named sponsors — APINEBULA and EverMind, whose Raven harness supports Archify as a Skill.
Why it is trending now
- 1,002 stars within the trending period at rank #5, driven by a README that leads with a one-command install: `npx skills add tt-a1i/archify -g`.
- Cross-agent support out of the box: Raven, Cursor, Claude Code, Codex CLI, and OpenCode, plus a dedicated DeepSeek Harness quick start added in 2.15.0.
- Output is one self-contained HTML file — no server, no runtime dependency — with PNG, SVG, WebM, and 1200×630 share-card exports from the same artifact.
- Verifiability as a feature: typed JSON IR, deterministic checks, revision-verified source links, and Before/Delta/After snapshot diffs with exact added, removed, changed, moved, and rerouted facts.
- Fast release cadence with concrete ship dates: 2.14.0 on 2026-08-11 and 2.15.0 on 2026-08-17, each with named features and fixed defects rather than vague improvements.
Problem it solves
- Architecture diagrams rot because they are hand-drawn in tools disconnected from the code they describe.
- When agents generate diagrams, reviewers cannot tell whether the topology was verified or invented; Archify's answer is a typed JSON contract plus deterministic checks and revision-verified source links.
- Diagram files live in separate editors, so sharing a reviewable, interactive view usually means screenshots or paid hosted services.
- Reviewing an architecture change before merge has no standard artifact; Archify positions Before/Delta/After snapshots with exact delta facts as that artifact.
- Export quality collapses at presentation sizes, so 2.14.0 added containment measurement at 1440×900 through 2048×1320 and share cards at 1200×630.
How it works
- Install the skill globally in a Node.js 18+ environment: `npx skills add tt-a1i/archify -g`. Cursor users get exact global and project commands from the agent-aware quick start at tt-a1i.github.io/archify/start.html?agent=cursor&type=architecture.
- Prompt your agent with the README's example: `Use archify to map this repository's runtime architecture.`
- The agent compiles the repository or system description into Archify's schema-v1 typed JSON intermediate representation; authored geometry such as `via`, named routes, channels, sides, and label placement remains authoritative.
- Validators and renderers check geometry, projected text, z-order, masks, interaction, and export in real browser layout; agent-facing failures land in `diagnostics[]` with a stable `code`, precise `subject`, concrete `evidence`, and executable `supportedFixes`.
- You receive one self-contained HTML file — five diagram types, four presets, dark and light themes — plus PNG, SVG, WebM, and 1200×630 share-card exports.
- Optionally run `archify visual-check <output.html> --json` to measure first-screen containment at 1440×900, 1600×1000, 1920×1080, and 2048×1320, with light and dark evidence at the two endpoint sizes.
Product demo and interface preview
Architecture read: a contract, not a picture generator
The renderer package lives in `archify/` and supports Node.js 18 and later, with CI covering Node 18, 20, 22, and 24. CONTRIBUTING.md is explicit that Archify's public behavior is larger than a renderer function and lists what counts as contracts: existing schema-v1 typed JSON remains valid unless a reviewed change introduces a breaking rule with a migration path, and explicit authored geometry — `via`, named routes, channels, sides, label placement — stays authoritative rather than being silently rewritten.
Failure handling is designed for agents, not humans scraping logs: agent-facing failures belong in `diagnostics[]` with a stable `code`, precise `subject`, concrete `evidence`, and executable `supportedFixes`. The guide also separates the `standard` tier, which preserves broad compatibility, from `showcase`, where a new failure must identify a real, repairable defect and return a stable machine-readable diagnostic. A recurring engineering note anchors the whole design: a valid SVG is not automatically a good diagram, because geometry, projected text, z-order, masks, interaction, export, and real browser layout can fail independently.
Version 2.15.0 added an authored brand identity layer: all five diagram types accept an explicit `brand` on primary nodes, the catalogue holds 107 provenance-backed vector marks discoverable via `archify brands`, unknown official URLs go through a digest-pinned capture command, the pipeline verifies the authored SHA-256 before embedding into the standalone HTML, and rendering fails closed on drift, malformed content, unsafe destinations, or a diagram-wide timeout. Remote SVG is rejected outright. The unreleased v2.16.0-dev.0 adds `meta.locale` with values `en` and `zh-CN` across all five renderers, localizing only Viewer-owned UI, accessibility copy, default legends, document titles, and language metadata — authored copy is never translated, and unsupported authored languages fall back to an explicitly disclosed English Viewer.
Command surface
- `npx skills add tt-a1i/archify -g` — global skill install from the README; a Cursor-specific quick start lives at tt-a1i.github.io/archify/start.html?agent=cursor&type=architecture.
- `Use archify to map this repository's runtime architecture.` — the README's canonical first prompt to your agent.
- `archify brands` — brand catalogue discovery introduced with the 107 provenance-backed vector marks in 2.15.0.
- `archify visual-check <output.html> --json` — added in 2.14.0; measures first-screen containment at 1440×900, 1600×1000, 1920×1080, and 2048×1320, captures light and dark evidence at the two endpoint sizes, writes a relative-path contact sheet, and emits a machine receipt that stays `visualReview: "pending"`; Chrome absence is reported as `skipped` rather than a false pass.
- `--quality` without a value is now rejected by the CLI instead of silently accepting an incomplete command (2.15.0 fix).
- `meta.column_fit: "spread"` — opt-in wide viewBox layout for sequence diagrams (2.15.0); the fixed-width layout remains the default.
Try-it path
- Use a Node.js 18 or later environment; the changelog describes the runtime as zero-install and dependency-free.
- Install with `npx skills add tt-a1i/archify -g`, then open the repository whose architecture you can verify from memory.
- Prompt the agent to map the repository's runtime architecture and wait for the single HTML artifact.
- Inside the HTML, search for a node you know, trace its upstream and downstream authored reach, and use the option to open revision-verified source.
- Run `archify visual-check <output.html> --json` and check the containment measurements at 1440×900 and 2048×1320, plus the pending visualReview receipt.
- Introduce one deliberate error in the JSON IR and confirm the failure arrives as a `diagnostics[]` entry with code, subject, evidence, and supportedFixes rather than a broken render.
Maintenance risk
- The current identity is v2.16.0-dev.0 in the changelog's Unreleased section; the latest tagged release is 2.15.0 from 2026-08-17. Anything pulled from main may carry unreleased behavior such as the `meta.locale` localization.
- The changelog shows a tight cadence — 2.14.0 on 2026-08-11 and 2.15.0 on 2026-08-17 — which is good for fixes but means contract surface is still moving.
- The MIT LICENSE carries two copyright lines: 2025 Cocoon AI (original "architecture-diagram-generator") and 2026 tt-a1i (Archify), so project governance has already changed hands once.
- Contract governance lives in CONTRIBUTING.md rather than an external spec: schema, renderer contract, validation rule, installation path, and export changes require a planning issue first, with user value, compatibility boundary, and non-goals agreed before implementation.
- Offsets: CI covers Node 18, 20, 22, and 24; DeepSeek Harness packaging acceptance checks cover macOS, Linux, and Windows command resolution; and the 2.15.0 DSH bundle adds no probing, telemetry, or behavior changes for non-DSH users.
Who should pay attention?
Good fit if
- Reviewing architecture changes before merge, using Before/Delta/After snapshots with exact added, removed, changed, moved, and rerouted facts attached to the pull request.
- Anyone working in Cursor, Claude Code, Codex CLI, Raven, or OpenCode who wants diagrams generated in-chat instead of in a separate editor.
- Onboarding documents and design reviews where a single self-contained HTML file can be attached, opened offline, and explored interactively.
- Bilingual documentation: the unreleased `meta.locale` support localizes the Viewer chrome to `en` and `zh-CN` without touching authored content.
Skip for now if
- Skip it if you need a hosted, always-live diagram service or a plugin inside Confluence or Notion — the artifact is a static, self-contained HTML file.
- Skip it if you expect translated diagram content: `meta.locale` localizes only renderer-owned Viewer UI, legends, titles, and accessibility copy; authored copy keeps its original language.
- Skip it if you must pin a stable tag — the current identity is the development version v2.16.0-dev.0, so wait for the tag if 2.15.0 lacks a feature you need from Unreleased.
- Skip it if your brand pipeline depends on remote SVG marks: 2.15.0 explicitly rejects remote SVG and fails closed on unverified brand bytes.
Risks and cautions
MIT licensing, a dependency-free Node 18 runtime, CI across four Node versions, and a written compatibility contract lower the technical risk, but the project self-identifies as a development version, changed stewardship once, and concentrates contract decisions in one contributor base.
- The README and changelog both point at v2.16.0-dev.0 as the current identity; the newest shipped behavior (Viewer localization) is only in the Unreleased section.
- The dual copyright in LICENSE — 2025 Cocoon AI for the original "architecture-diagram-generator" and 2026 tt-a1i — shows the codebase already survived one change of hands.
- Compatibility guarantees (schema-v1 validity, authored geometry authority, `standard` tier behavior) are enforced through CONTRIBUTING.md norms and review, not an externally versioned specification.
- Positive offsets: zero-install dependency-free Node 18 runtime, CI on Node 18/20/22/24, visual-check reporting Chrome absence as `skipped` rather than a false pass, and digest-pinned, SHA-256-verified brand assets that fail closed.
- MIT License: free to use, copy, modify, merge, publish, distribute, sublicense, and sell, with notice retention; the file carries the standard no-warranty disclaimer.
- Brand assets are hostile-input hardened by design: unknown official URLs require a digest-pinned capture; render, validate, and deliver re-fetch bounded PNG/JPEG/WebP/ICO bytes, verify the authored SHA-256, embed into the standalone HTML, and fail closed on drift, malformed content, unsafe destinations, or a diagram-wide timeout; remote SVG is rejected.
- CONTRIBUTING.md forbids secrets, access tokens, credentials, private repository content, personal data, and customer data in prompts, JSON fixtures, logs, screenshots, generated artifacts, and package tests.
- Security vulnerabilities must go through GitHub's private security reporting for this repository, not public issues or published exploit details.
- The DeepSeek Harness distribution `@tt-a1i/archify-dsh` is a Skill-only bundle that adds no probing, telemetry, or behavior changes for non-DSH users, per the 2.15.0 changelog.
Alternatives to compare
| Approach | When to use | Trade-off |
|---|---|---|
Mermaid | You need text-defined diagrams that render natively inside GitHub and other markdown hosts, without an agent in the loop or snapshot diffing. | Free, open source (MIT). |
D2 | You want a standalone declarative diagram language and CLI with no dependency on a coding agent. | Free, open source. |
PlantUML | You need standards-shaped UML output from plain-text definitions and already have a rendering pipeline. | Free, open source; review license terms before embedding in proprietary tooling. |
diagrams.net (draw.io) | You need manual GUI layout and whiteboarding rather than generated, contract-validated maps. | Free, open source; hosted app and some integrations are paid. |
Structurizr DSL | You model systems with the C4 method and want a workspace-backed single source of truth for multiple views. | Free, open source DSL; the cloud service is sold separately. |
What this trend reveals
Merge-gate architecture diffs
Before/Delta/After comparison with exact added, removed, changed, moved, and rerouted facts is the one capability none of the mainstream diagram tools ship, and it maps cleanly onto pull request review.
Generate two validated snapshots around a real refactor PR and check whether the delta facts match what you verified by hand in the diff.
Bilingual internal documentation
The unreleased `meta.locale` values `en` and `zh-CN` localize Viewer UI, accessibility copy, default legends, and document titles across all five renderers, with an explicitly disclosed English fallback for unsupported authored languages.
Render one diagram twice with `meta.locale` set to `en` and `zh-CN`, and confirm the Viewer chrome, legends, and title change while authored labels do not.
Brand-consistent external docs
The 107 provenance-backed vector marks, `archify brands` discovery, and SHA-256-verified embedding let generated diagrams carry official logos without manual asset wrangling.
Check whether your organization's mark is in the catalogue, then re-render once and confirm the digest-pinned capture path verifies instead of silently re-fetching.
RepoDaily verdict
Archify earns its 1,002-star day by attacking the two weakest properties of generated diagrams — trust and shareability — with a typed JSON contract, deterministic checks, agent-readable `diagnostics[]` failures, and one self-contained HTML file with crisp PNG, SVG, WebM, and 1200×630 exports. The Before/Delta/After snapshot diff with exact added, removed, changed, moved, and rerouted facts is genuinely uncommon among diagram tools. Pin to tagged 2.15.0 rather than the v2.16.0-dev.0 development identity if you need stability, read CONTRIBUTING.md's contract rules before depending on schema-v1 output, and note the 2025 Cocoon AI lineage in the MIT LICENSE.