archify

Clone URL: https://github.com/moses-y/archify

The Problem

Generating polished technical diagrams typically requires manual drawing, external tools, or fragile markdown‑based flowcharts. Engineers spend cycles aligning boxes, styling themes, and exporting to multiple formats—work that is repetitive and error‑prone.

What This Does

Archify is a single‑file HTML generator that turns plain‑English system descriptions into architecture, workflow, sequence, data‑flow, or lifecycle diagrams. The code lives in archify/ with five renderer modules (render-architecture.mjs, render-dataflow.mjs, render-lifecycle.mjs, render-sequence.mjs, render-workflow.mjs) each drawing a specific diagram type. A shared utility set—archify/renderers/shared/utils.mjs, geometry.mjs, cli.mjs—provides rendering logic, while shared/validator.mjs validates input schemas defined under schemas/. The generated HTML is self‑contained, supports a dark/light theme toggle (persisted per session), and can export PNG, JPEG, WebP, or SVG at up to 4× source resolution. Examples appear in examples/ and a live demo is at docs/index.html.

How It Is Wired

Entry point: docs/index.html (built HTML served for preview).
Import graph: 14 internal modules connected by 19 edges; no circular dependencies. The most connected modules are archify/renderers/shared/cli (5 importers, 2 imported, instability 0.29) and archify/renderers/shared/utils (7 importers, 0 imported, instability 0).
Renderer flow: a description is parsed, validated by validator.mjs, then dispatched to the appropriate renderer. Each renderer pulls geometry helpers and shared utilities, producing an SVG that is rasterised to PNG/JPEG/WebP on export.
Duplicated code: 25 repeated 6‑line blocks appear across render-architecture.mjs, render-dataflow.mjs, render-lifecycle.mjs, and render-workflow.mjs—a clear DRY opportunity.
High branching density: validator.mjs, render-architecture.mjs, and render-dataflow.mjs each contain ~22 branch points over ~63 lines, suggesting decision‑heavy logic that could be decomposed via a strategy or table‑dispatch pattern.

How To Use It

Step	Command / Action
Setup	`cd archify && npm install` (dependencies declared in `archify/package.json`).
Run locally	Open `docs/index.html` in a browser, or invoke the skill from your agent environment (Claude, Codex CLI, opencode).
Generate a diagram	Provide a plain‑English description to the agent skill; e.g., “Draw an architecture with a front‑end, API server, PostgreSQL cache, and Redis queue.”
Toggle theme & export	Press T to switch dark/light, E to open the export UI; choose PNG, JPEG, WebP, or SVG. Append `?theme=light` or `?openExport=1` to the URL for deterministic screenshots.

No environment variables or API keys are required—the diagrams are purely client‑side.

Real‑World Use

A senior engineer describes a micro‑service platform: “Frontend React app calls an auth service, which queries a PostgreSQL database and caches frequently‑read rows in Redis. The order service publishes events to a Kafka topic that a data‑flow pipeline consumes.” Archify instantly returns a single HTML file showing boxes, connectors, semantic colors, and a theme toggle. The engineer copies the PNG to Slack, embeds the SVG in a README, and iterates by chat (“add a rate‑limit bucket”) without re‑opening a design tool.

Code Health & Issues

HIGH – Pin third‑party GitHub Actions to a commit SHA (.github/workflows). The workflow softprops/action-gh-release@v2 can shift; lock to a SHA and let Dependabot bump it.
MEDIUM – Declare least‑privilege permissions for GITHUB_TOKEN (.github/workflows/ci.yml). Add permissions: contents: read at the top of the workflow and widen per‑job where needed.
MEDIUM – Enable Dependabot or Renovate (no bot configured). Commit .github/dependabot.yml covering npm and github-actions.
MEDIUM – Gate pull requests on a dependency vulnerability scan. Add dependency-review-action on pull_request or run osv-scanner on push/schedule.
MEDIUM – Set persist-credentials: false on checkout (.github/workflows/ci.yml). The token stays in .git/config; pass an explicit token only to the push step.
LOW – Set timeout-minutes on workflow jobs (2 jobs have no timeout). Add a realistic bound to each job to avoid overlapping runs.

The Bottom Line

Archify delivers a fast, zero‑dependency way to turn textual system specs into shareable, theme‑aware diagrams with multiple export formats—ideal for quick technical communication and iteration via chat. The codebase is modular but contains duplicated rendering logic and some decision‑dense validation that could be refactored for maintainability. SDLC hygiene is solid (tests, CI, license, lockfile) but the repository would benefit from pinned Action SHAs, Dependabot, and a dependency‑scan gate. Use it when you need diagrams without design overhead; plan a short refactor to reduce code duplication and improve long‑term stability.