archmap

I wanted a map before reading the code

When I open an unfamiliar project, I do not want to start with every file equally important.

I want the first map.

Where are the entry points? Where are the models? Which files are only configuration? Which modules depend on which other modules? Is this a small tool with a clean shape, or a folder full of hidden complexity?

You can discover all of that manually, but it takes time. You open the tree, jump between imports, read filenames, follow conventions, and slowly build a mental model in your head.

That mental model is useful, but it is also temporary. It stays with the person who did the reading. It gets stale when the project changes. And it is rarely written down unless somebody has the patience to draw a diagram.

So I built archmap, a new open source project for briefly reviewing any app architecture and making the result presentable as a single self-contained HTML file.

What it does

archmap scans a project folder, builds a quick architecture overview, and generates one standalone interactive HTML file.

No server.

No database.

No external assets.

No runtime dependencies.

Just run:

archmap /path/to/project

Then open the generated *-architecture.html file in a browser.

The report gives you a few useful views:

• an overview of files, lines, languages, classes, functions, and dependency edges
• inferred architecture layers such as entry points, config, models, API, services, data access, integrations, UI, utilities, tests, docs, and build/ops
• internal dependency links between project files
• a collapsible file tree
• a searchable component reference
• a side panel for each file with its imports, classes, functions, methods, and links to related files

The important part is that everything is embedded in a single HTML file. The project data is serialized as JSON inside the page, so the report is easy to share, archive, or attach to documentation.

The architecture is deliberately boring

The tool itself is pure Python.

That choice matters. I wanted it to be easy to install, easy to run, and easy to package as a standalone binary later. A tool like this should not ask for much before it gives you value.

The pipeline is simple:

1. scan the project tree
2. analyze each source file
3. classify files into architecture layers
4. resolve internal dependencies
5. render the result into HTML

The scanner skips the usual noise: .git, node_modules, build folders, virtual environments, caches, binary assets, lockfiles, and files larger than about 2 MB. It also honors .gitignore by default.

Python files get deeper analysis through the standard library ast module. That means classes, functions, methods, imports, and module docstrings can be extracted more reliably.

Other languages use lightweight heuristics. That is not perfect, but it is practical. The goal is not to become a compiler for every language. The goal is to produce a useful architecture map quickly.

Layer detection is heuristic, but useful

Architecture is often visible in names.

A file under src/api/routes.js probably belongs to an API layer. A file under models/ is probably a data model. A Dockerfile, pyproject.toml, or GitHub Actions workflow belongs closer to build and operations. A file named cli.py or main.go is likely an entry point.

archmap uses those signals to classify files into layers.

It looks at directory names, filename hints, and extensions. Directory names carry the strongest signal. Filename hints come next. Extensions are a weaker fallback.

This is not a formal architecture rule system. It is a first-pass classifier.

That is enough for the intended use case. When you are trying to understand a project quickly, a good approximation is much better than a blank page.

Dependency links make the map more useful

A file tree tells you where things live.

A dependency graph tells you how things relate.

archmap tries to resolve imports between files in the same project. For Python, it handles dotted imports and relative imports. For JavaScript and similar languages, it handles path-style imports where possible.

The report then shows both directions:

• what this file depends on
• what uses this file

That second direction is often the more useful one. When you are thinking about changing a file, you usually want to know who will be affected.

It is not trying to replace deeper tools

There are limits.

archmap is not a full static analyzer. It does not understand every framework. It does not evaluate dynamic imports. It does not know your domain architecture. It cannot tell whether your layering is correct.

And for non-Python languages, the extraction is intentionally heuristic.

That is fine.

I see this as a fast orientation tool, not a formal verification tool. It gives you enough structure to start reading with better context.

The difference is similar to looking at a city map before walking through the streets. The map will not show every detail, but it prevents you from wandering blindly.

Why a single HTML file

I like tools that leave behind simple artifacts.

A standalone HTML file is boring in the best way. You can open it locally. You can send it to someone. You can keep it next to release notes. You can regenerate it whenever the project changes.

There is no service to run and no account to create.

That also makes it useful in environments where source code cannot leave the machine. You can generate the report locally and keep it local.

Installation

The package is published as archmap-cli and provides the archmap command.

With pipx:

pipx install archmap-cli

Or with pip:

pip install archmap-cli

Then:

archmap .

A few useful options:

# scan a specific project
archmap /path/to/project

# write to a custom output file
archmap /path/to/project -o architecture.html

# set the display name
archmap /path/to/project --name "My Service"

# open the generated report after building it
archmap /path/to/project --open

# ignore .gitignore rules
archmap /path/to/project --no-gitignore

What I like about this kind of tool

It does not ask you to change your workflow.

It does not require you to annotate your code.

It does not need a configuration file before it can do something useful.

You point it at a folder and it gives you a map.

That is enough for many moments: onboarding, refactoring, reviewing a small service, auditing an old project, or handing work to another developer.

A map does not have to be perfect to be helpful.

It only has to make the next step clearer.

Closing thought

Most developers eventually build a private map of every project they touch.

archmap turns part of that private map into a real artifact.

Not the final truth of the codebase. Not complete documentation. Not architecture governance.

Just a useful first look.

And sometimes that is exactly what you need before making good decisions.