archifyiOpen the studio

A practical Archify tutorial

Your first Archify
diagram.

Start with a small system, give your coding agent a clear request, and check the diagram before sharing it. No repository is needed for your first example.

The architecture walkthrough below is based on Archify v3.0.1. Release guidance was reviewed October 26, 2026 against upstream v3.2.0. The installer follows the upstream distribution; check the installed version before using version-specific features.

01. Install the Archify skill

Start with a supported coding agent and the local tools required by its environment. The upstream documentation covers Cursor, Claude Code, Codex CLI, and OpenCode. Run the published installer in your terminal:

npx skills add tt-a1i/archify -g

Follow the installer’s agent selection. The -g option installs the skill at the user level. If your agent is already open, refresh its skills or restart the session as needed. This command installs a third-party skill; review the upstream source and installer prompts before proceeding.

Read the upstream installation instructions ↗

Archify 3.1: choose the diagram type and workflow

The upstream Archify 3.1.0 release adds entity relationship diagrams (ERD), class/interface diagrams, trees, timelines, and waterfalls to its architecture, workflow, sequence, dataflow, and lifecycle views. These are capabilities of the local open-source skill; installing a new release does not upgrade previously generated HTML artifacts or the separate Archifyi service.

For a system of services and data stores, follow the architecture walkthrough below. For database relationships or the timing of messages, choose the corresponding upstream diagram type and consult its version-specific documentation. Archifyi’s browser workspace currently supports architecture diagrams and runs a pinned 3.0.1-based renderer; it does not offer the full set of upstream 3.1 diagram types.

New installations follow the current upstream distribution. Existing local installations need an owner-initiated update; check the Archify 3.1.0 release and upgrade notes ↗ before changing a working environment. Review the result in a browser even when automated validation passes. Timeline and waterfall values should be supported by evidence before you present them as measured facts.

Prefer a browser workflow for a software architecture map? Start with the editable SaaS architecture template or the system context example. Both explain each component and let you adapt the connections in Archifyi.

Archify 3.2: when to use a one-page explainer

If your reader needs a written answer alongside the diagram, the upstream 3.2 release adds a one-page explainer workflow from a Markdown draft. Panels can combine explanations, source references, and interactive diagrams. Use a focused question for each panel, and distinguish evidence from illustrative examples.

For example, ask your coding agent to explain how a browser request reaches the database, include the architecture diagram, and cite the files that support each relationship. Review the cited evidence and rendered page before sharing; a valid diagram does not establish that an explanation is correct.

The upstream workflow includes browser image exports and printing to PDF. See the Archify 3.2 release notes ↗ for its authoring and delivery instructions. This explainer workflow belongs to the original skill; it is not an available input or export mode in Archifyi’s hosted architecture workspace. For an architecture map in the browser, continue with the editable diagram examples.

02. Describe one request path

You do not need a repository to start. Give the agent a small, explicit system rather than asking it to invent your entire application. Try this prompt:

Use Archify to map a small web application.
Show Browser -> API -> PostgreSQL as the main path.
Add Redis Cache as a dependency of the API.
Label the cache as optional and list assumptions separately.
Keep this as an architecture diagram, not a runtime trace.

This prompt is an example, not a tested description of your system. Replace component names and connections with facts you know. If the agent reads a repository, request supporting files for inferred relationships and review them.

03. Inspect the picture, then refine it

Open the generated HTML file in your browser. Check that the important components appear, that arrows point in the intended direction, and that names match the source material. A renderer can validate diagram structure without proving your business assumptions.

Make one focused change at a time. For example: “Add an authentication service called by the API, and explain where authorization occurs.” Then compare the result with your intended design. Keep the source alongside the artifact so the next change starts from the same model.

  • Remove relationships that were guessed without evidence.
  • Separate an optional dependency from the main request path.
  • Explain a failure case in notes before adding more arrows.
  • Save a reviewed version before making a larger revision.

04. Share the artifact with context

The upstream workflow produces an HTML artifact that can be opened in a browser. Before sending it, check what descriptions, source references, and project details it contains. Include a short statement of what the diagram represents and when it was reviewed.

If you prefer a hosted workflow, learn about Archifyi’s browser workspace. Its availability and enabled features are shown on the site. The workspace and the local open-source skill are separate ways to work.

When the result is not what you expected

The agent does not recognize Archify

Confirm the installer targeted the agent you are using. Refresh that agent’s skill discovery, start a new session, and explicitly ask it to use Archify. Consult the upstream instructions for its current installation path.

The diagram has too many components

Choose a single question, such as “How does a browser request reach the database?” Ask for a small set of core components and move supporting detail into descriptions.

The diagram looks right, but the architecture is wrong

Check the input and repository evidence. A valid diagram is not an architecture audit. Correct the connections or assumptions, regenerate, and have someone who knows the system review it.

I want to copy an example instead

Use the architecture diagram examples. Each has a readable connection template that you can edit before asking an agent or an available Archifyi workspace to render it.