Archify Diagram Types: 5 Supported Formats and When to Use Each

Archify supports five diagram types—Architecture, Workflow, Sequence, Data Flow, and Lifecycle—each designed for specific technical documentation needs from high-level system maps to state-machine visualizations.

Archify is an open-source diagramming tool that generates self-contained HTML artifacts from natural language prompts. Understanding which diagram type to select ensures your visualization focuses on the evidence that matters while omitting unrelated detail. This guide covers all five supported types based on the tt-a1i/archify source code.

---

Architecture Diagrams

Use for: High-level component maps, service topologies, storage layouts, and security trust boundaries.

Architecture diagrams in Archify visualize runtime relationships between services, databases, caches, and external providers. They emphasize the primary request path and explicitly mark trust boundaries around sensitive components like databases or payment processors.

What to include in your prompt:

• System scope and core components
• Primary data flow direction
• Security boundaries requiring emphasis

Use Archify to draw a high‑level runtime architecture of the e‑commerce service.
Show the web front‑end, API gateway, auth service, Redis cache, PostgreSQL, and
external payment provider. Highlight the primary request path and place trust
boundaries around the database.

CLI command:

node archify/bin/archify.mjs generate architecture "high‑level runtime diagram of my service"

Reference implementation: examples/web-app.html demonstrates a runtime architecture map.

---

Workflow Diagrams

Use for: CI/CD pipelines, approval chains, operational runbooks, and tool-call sequences.

Workflow diagrams capture procedural sequences with branching logic. They excel at showing parallel stages, manual gates, and failure handling paths where multiple actors or systems coordinate.

What to include in your prompt:

• Participants and execution order
• Branch conditions and parallel tracks
• Exception handling and rollback paths

Generate a workflow diagram of our CI/CD pipeline. Include stages: Checkout,
Build, Test, Deploy to staging, Manual approval, Deploy to production. Show
parallel lint & unit‑test branches and highlight failure handling.

CLI command:

node archify/bin/archify.mjs generate workflow "CI/CD pipeline with approval step"

Reference implementation: examples/workflow-agent-tool-call.html shows agent tool-call workflows.

---

Sequence Diagrams

Use for: API call chains, cache-miss/fallback flows, authentication steps, and async traces.

Sequence diagrams in Archify emphasize temporal ordering and caller-callee relationships. They clarify timing-sensitive interactions where understanding the exact sequence of operations—especially failure fallbacks—matters more than static structure.

What to include in your prompt:

• Callers, callees, and return paths
• Timing-sensitive operations
• Alternative paths (cache misses, fallbacks)

Create a sequence diagram for a login flow: Browser → Web App → API →
JWT validation → Redis session lookup → PostgreSQL fallback. Keep the cache‑miss
path secondary.

CLI command:

node archify/bin/archify.mjs generate sequence "login flow with cache fallback"

Reference implementation: examples/sequence-cache-miss.html illustrates API fallback patterns.

---

Data Flow Diagrams

Use for: ETL/ELT pipelines, PII handling, governance boundaries, and data lineage tracking.

Data Flow diagrams map data movement through transforms, stores, and compliance boundaries. They explicitly mark governance concerns—particularly PII boundaries—making them essential for data architecture documentation subject to regulatory review.

What to include in your prompt:

• Data sources and ingestion points
• Transform stages and storage targets
• Governance boundaries and compliance gates

Draw a data‑flow diagram for our analytics pipeline. Include sources (Web App,
Mobile), ingest (Edge API), governance (PII consent gate), storage (Warehouse,
Feature Store) and consumers (Dashboards, Experimentation). Mark the PII
boundary around the consent gate.

CLI command:

node archify/bin/archify.mjs generate dataflow "analytics pipeline with PII boundary"

Reference implementation: examples/dataflow-product-analytics.html contains a full analytics pipeline example.

---

Lifecycle Diagrams

Use for: State-machine visualizations, object lifecycles, retry mechanisms, and terminal outcome modeling.

Lifecycle diagrams represent state transitions with explicit handling for wait states, retry loops, and cancellation paths. They clarify systems where entities progress through defined states with non-linear exit conditions.

What to include in your prompt:

• Defined states and triggering events
• Retry and timeout behaviors
• Terminal states and failure exhaustion

Produce a lifecycle diagram for an order processing job. Show states:
Queued → Running → Retry (if failure) → Cancelled / Completed. Include a wait
state for payment confirmation and a terminal "Failed" state for exhausted
retries.

CLI command:

node archify/bin/archify.mjs generate lifecycle "order processing job states"

Reference implementation: examples/lifecycle-agent-run.html demonstrates state-machine patterns.

---

How Archify Validates Diagram Types

The CLI entry point at archify/bin/archify.mjs validates the diagram_type parameter against supported values before invoking the appropriate renderer. The smoke test in scripts/package-smoke.mjs exercises all five types to verify correct generation:

# From scripts/package-smoke.mjs - validates diagram_type parameter passing

node archify/bin/archify.mjs generate <type> "<description>"

All commands produce a self-contained HTML artifact with optional PNG/SVG export via embedded rendering libraries.

---

Choosing the Right Diagram Type

Archify's "question-first" design philosophy recommends matching your bounded question to the appropriate diagram recipe:

If your question involves...	Select	Focus
"What components exist and how do they connect?"	Architecture	Static topology, trust boundaries
"What steps execute and in what order?"	Workflow	Procedural sequence, branching logic
"Who calls whom and when?"	Sequence	Temporal ordering, fallback paths
"Where does data come from and where does it go?"	Data Flow	Transform lineage, compliance boundaries
"What states exist and how do transitions work?"	Lifecycle	State machine, retry/cancel semantics

---

Summary

• Architecture diagrams map high-level service topologies and security boundaries
• Workflow diagrams capture procedural sequences with branching and parallel execution
• Sequence diagrams emphasize caller-callee timing and fallback chains
• Data Flow diagrams track data lineage through governance and compliance boundaries
• Lifecycle diagrams model state machines with explicit retry and terminal handling

All five types are validated through archify/bin/archify.mjs and demonstrated in the examples/ directory of the tt-a1i/archify repository.

---

Frequently Asked Questions

Can I generate multiple diagram types from the same prompt?

No. Archify’s CLI validates a single diagram_type parameter per invocation. For comprehensive documentation, run separate commands for each diagram type with appropriately scoped prompts that focus each visualization on a specific question.

Does Archify support custom diagram types beyond the five listed?

As implemented in tt-a1i/archify, the five types are hardcoded in the CLI validator and renderer dispatch logic. Extending support would require modifying archify/bin/archify.mjs to recognize additional type strings and implement corresponding rendering logic.

What output formats does Archify produce?

Every generation produces a self-contained HTML artifact with embedded CSS/JS for interactive viewing. Optional PNG and SVG exports are available through command-line flags, as verified in scripts/package-smoke.mjs.

How does Archify differ from Mermaid or PlantUML?

Archify emphasizes bounded, purpose-built diagram types selected to match specific architectural questions, rather than general-purpose syntax. Outputs are self-contained HTML files rather than source files requiring separate rendering infrastructure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}