My Experience with Archify: Turning Source Code into Architecture Diagrams with Codex

Introduction

When working with an existing codebase, especially one that I didn't build from scratch, one of the most time-consuming tasks is understanding the overall architecture.

Before making any changes, I usually need to answer questions like:

• Where is the frontend?

• How is the backend/API structured?

• What database does the project use?

• How does authentication work?

• Which external services are involved?

• How is the application deployed?

• What happens when a request comes from the browser?

For a small project, reading through the repository manually is manageable. But as the codebase grows, following imports, API routes, configuration files, database connections, Docker files, and authentication logic can take a lot of time.

Recently, I tried Archify together with the Codex extension in Visual Studio Code / Codex / Claude to see if I could make this process easier.

My main question was simple:

Can an AI coding agent analyze my actual source code and generate an architecture diagram that accurately represents how the system is implemented?

After testing it on one of my projects, the result was surprisingly useful.

What is Archify?

Archify is an agent skill designed to generate visual technical diagrams from a codebase.

It can be used to create different types of diagrams, including:

• Architecture diagrams

• Workflows

• Sequence diagrams

• Data-flow diagrams

• Lifecycle diagrams

Instead of asking an AI coding agent to simply explain a repository in text, Archify gives it a more structured way to turn that analysis into a visual artifact.

What caught my attention is that the output isn't just a basic Mermaid diagram or a static image.

Archify generates a self-contained interactive HTML diagram that can be opened directly in the browser. It also provides presentation controls and export options such as SVG.

That makes it useful not only for understanding a repository but also for documentation, onboarding, technical discussions, and blog posts.

Why is it interesting?

My usual workflow when exploring an unfamiliar repository looks something like this:

Clone repository
      ↓
Read README
      ↓
Explore folder structure
      ↓
Find entry points
      ↓
Find API routes
      ↓
Check database
      ↓
Understand authentication
      ↓
Check infrastructure
      ↓
Build a mental architecture

AI coding agents already make this process much faster.

For example, I can ask Codex to analyze a repository and explain its architecture. The problem is that the result is usually text.

It might tell me something like:

Browser
  ↓
Nginx
  ↓
Next.js
  ↓
API Routes
  ↓
Prisma
  ↓
PostgreSQL

That's useful, but when I want to understand multiple flows or share the architecture with someone else, a diagram is much easier to work with.

Archify essentially adds another step:

Source Code
    ↓
AI Analysis
    ↓
Architecture Model
    ↓
Interactive Diagram

Another thing I find important is that I can explicitly tell the agent:

Only include components verified from the source code.

I don't want the AI to design what it thinks the architecture should look like.

I want it to visualize what is actually implemented in the repository.

That distinction is important when using AI for technical documentation.

How does it work?

The workflow is fairly straightforward.

I use Archify as a skill for Codex inside Visual Studio Code.

The overall process looks like this:

Repository
    ↓
Codex
    ↓
Archify Skill
    ↓
Analyze Source Code
    ↓
Identify Verified Components
    ↓
Build Architecture Definition
    ↓
Generate Interactive HTML
    ↓
Review / Present / Export

In my test project, Archify identified the main application flow as:

Web Browser
     ↓
Host Nginx
     ↓
Next.js Frontend
     ↓
Next.js Route Handlers
     ↓
Prisma Data Access
     ↓
PostgreSQL

It also detected other parts of the system, including:

Google Services

Admin Session Auth

Persistent Uploads

Docker Compose Network

These components were then connected to the primary application flow.

Instead of just knowing that "this project uses PostgreSQL and Prisma," I can immediately see where they sit in the architecture and how requests reach them.

Getting Started & Hands-on

For this experiment, I used the Codex extension directly inside Visual Studio Code.

Installing Archify

I installed the Archify skill with:

npx skills add tt-a1i/archify \
  --skill archify \
  --agent codex \
  --global \
  --copy \
  --yes

Here I'm installing the archify skill for Codex globally, so I can reuse it across different repositories.

After installing it, I opened the project I wanted to analyze in Visual Studio Code.

There wasn't much configuration needed after that.

I simply asked Codex to use the skill.

The Prompt I Used

This was my actual prompt:

Use the Archify skill to analyze this repository.

Create a high-level architecture diagram showing:

- frontend
- backend/API
- database
- authentication
- external services
- infrastructure
- primary request flow

Only include components verified from the source code.

Save the output to docs/architecture/.

I intentionally kept the prompt relatively simple.

Instead of telling Archify how the architecture should look, I only defined what information I wanted to see.

The most important instruction for me was:

Only include components verified from the source code.

When generating technical documentation with AI, accuracy matters much more to me than having a complex-looking diagram.

Generated Files

After Codex finished analyzing the repository, Archify generated the files inside:

docs/
└── architecture/
    ├── kdt-high-level.architecture.json
    ├── kdt-high-level.html
    └── kdt-high-level.visual-check.json

The most interesting one for me was:

kdt-high-level.html

Opening this file in the browser gives me the complete interactive architecture viewer.

And this is where Archify became much more interesting than a normal AI-generated architecture explanation.

The Generated Architecture

For my project, the primary request flow was represented approximately like this:

Web Browser
    │
    ▼
Host Nginx
    │
    ▼
Next.js Frontend
    │
    ▼
Next.js Route Handlers
    │
    ▼
Prisma Data Access
    │
    ▼
PostgreSQL

This matched the actual implementation of my project quite well.

The diagram also showed relationships such as:

Browser → Nginx
HTTPS request

Nginx → Next.js
reverse proxy

Route Handler → Prisma
application queries

Prisma → PostgreSQL
PostgreSQL protocol

It also identified authentication separately:

Admin Session Auth
        ↓
Next.js Route Handlers

And other integrations such as Google services and persistent uploads were shown outside the main request flow.

This made the architecture much easier to understand than reading a long text explanation.

Light version:

Dark version:

Guided Views

One feature I particularly liked was Guided Views.

Instead of trying to understand every connection at once, the generated UI lets me explore specific flows individually.

For my project, Archify generated views such as:

01 Primary request flow
02 Admin authentication
03 Uploads and external services

This is a small feature, but it makes a big difference when the diagram starts getting more complicated.

Instead of staring at a large network of boxes and arrows, I can focus on one story at a time.

Exporting the Diagram

The generated viewer also includes export functionality.

I can export the architecture as SVG and reuse it in:

• README files

• Technical documentation

• Blog posts

• Presentations

• Internal project documentation

I like this because the diagram isn't locked inside the AI conversation.

The AI generates an actual artifact that I can keep together with the repository.

What I Like & Don't Like

After testing Archify on a real project, there are several things I really like about it.

The first is the UI/UX.

The generated diagram looks polished and is easy to navigate. Components are visually separated into categories such as frontend, backend, database, security, cloud, and external services.

The second is the visual flow.

I can quickly understand how a request travels through the system without reading multiple configuration and implementation files.

For example:

Browser
   ↓
Nginx
   ↓
Next.js
   ↓
Route Handler
   ↓
Prisma
   ↓
PostgreSQL

The third—and probably most important—is accuracy.

At least for the project I tested, the generated architecture matched the actual source implementation quite well.

That was the thing I cared about most before trying Archify.

A beautiful diagram isn't very useful if the AI invents components that don't exist.

The fourth thing I like is the export support, especially SVG. It means I can easily reuse the result outside Archify.

However, I still wouldn't treat an AI-generated architecture diagram as an absolute source of truth.

My preferred workflow is still:

Generate Diagram
      ↓
Compare with Source
      ↓
Check Missing Components
      ↓
Check Relationships
      ↓
Adjust Prompt
      ↓
Regenerate if necessary

There is also another limitation to consider.

Not everything about a production architecture necessarily exists inside a single repository.

For example, some infrastructure information might live in:

Infrastructure repository
CI/CD configuration
Cloud configuration
Environment variables
Secret management
External services
Reverse proxy configuration

If Archify can't find evidence for something in the repository, it obviously can't reliably visualize it.

This is also why I prefer using the instruction:

Only include components verified from the source code.

I'd rather have a smaller but accurate diagram than a complete-looking architecture based on assumptions.

When Should You Use It?

I think one of the best use cases for Archify is exploring an unfamiliar codebase.

When I clone a repository, I can first ask Codex:

Use the Archify skill to analyze this repository.

and generate a high-level architecture diagram.

Then I can use that diagram as a map for exploring the code:

Architecture Diagram
        ↓
Understand Major Components
        ↓
Choose a Component
        ↓
Read Its Implementation
        ↓
Follow the Detailed Flow

I can also see Archify being useful for:

• Onboarding developers

• Understanding legacy projects

• Reviewing open-source repositories

• Creating technical documentation

• Architecture discussions

• Preparing README diagrams

• Writing technical blog posts

• Preparing architecture slides

I don't think it replaces reading the source code.

Instead, it gives me something very useful before I start reading deeply:

A mental model of the system.

Once I understand the big picture, navigating the repository becomes much easier.

Final Thoughts

After trying Archify with Codex inside Visual Studio Code, I really like this workflow.

Previously, I mostly used AI coding agents like this:

Repository
    ↓
AI
    ↓
Text Explanation

With Archify, the workflow becomes:

Repository
    ↓
Codex
    ↓
Archify
    ↓
Verified Architecture
    ↓
Interactive Diagram
    ↓
SVG / Documentation

For me, that's a much more useful output.

The generated UI looks clean, the request flows are easy to follow, Guided Views make larger diagrams easier to explore, and the export functionality makes the result reusable.

Most importantly, the architecture generated from my test repository was quite accurate compared with the actual implementation.

That's what makes Archify interesting to me.

It also shows a broader use case for AI agent skills.

Instead of using an AI coding agent only to answer questions or generate code, we can use skills to create real development artifacts that stay with the project.

In this case, I went from:

"Can you explain this repository?"

to:

"Analyze the repository and create an architecture artifact I can actually use."

For developers who frequently explore unfamiliar repositories, review open-source projects, maintain legacy applications, or need better project documentation, I think Archify is definitely worth trying.

And for my next repository, I'll probably start with the exact same prompt:

Use the Archify skill to analyze this repository.

Create a high-level architecture diagram showing:

- frontend
- backend/API
- database
- authentication
- external services
- infrastructure
- primary request flow

Only include components verified from the source code.

Save the output to docs/architecture/.

Simple prompt, but a surprisingly useful result.