archview 0.2.6

Interactive live architecture viewer for Python projects

ArchView

See your codebase. Understand it. Then change it.

ArchView gives you a live, interactive map of any Python project's architecture — right in your browser. It parses real Python (via AST, not regex) and follows references into shell scripts and config files, watches for changes, and updates the graph in real time.

Built for developers who vibe-code and need to stay oriented, or anyone inheriting a codebase they didn't write.

Why

You're 200 files deep in someone else's project. Or you're building fast and your own code is getting tangled. You need to see the structure — what depends on what, where the entry points are, which modules are isolated.

ArchView shows you all of that in seconds, and keeps updating as you code.

Install

pip install archview

Available on PyPI. Pure Python, works anywhere with Python 3.9+.

Usage

archview /path/to/your/project

Open http://localhost:8080 — that's it. If 8080 is taken, ArchView scans the next 100 ports and prints the one it picked.

# Custom port and refresh interval
archview /path/to/project --port 9000 --interval 5

Tip: point ArchView at your project's import root — the directory your code imports relative to. An edge is only drawn when an import resolves to a file inside the scanned tree, so from a import x connects only if a.py sits at the root you scanned. Scan a parent folder and those absolute imports won't resolve (the modules show up, just without arrows).

What you see

Color	Meaning
Green	Entry point — modules that import but aren't imported
Blue	Connector — modules that both import and are imported
Red	Utility — leaf modules only imported by others
Gray	Isolated — no import relationships
Red (bright)	Error — files that failed to parse

Features

Live refresh

Edit your code, save — the graph updates automatically. No restart needed.

Interactive exploration

• Hover a node to see its docstring, type, and exported symbols
• Click a node to highlight its direct dependencies
• Double-click to open the file in VS Code
• Drag nodes to rearrange the layout
• Click folders to collapse/expand entire packages

Dependency highlighting

Click a node and it plus its direct dependencies light up — everything else fades. Then hover a highlighted edge to see exactly which symbols are imported across it.

Annotations

Sketch directly on the graph to explain it. Draw boxes, add text labels, erase — useful for walking a teammate through the architecture or marking up a review. Annotations persist across launches.

Export

• PNG — screenshot the current view
• Save — persist node positions (restored on next launch)

Ignore patterns

# Exclude directories from analysis
archview ignore tests __pycache__ venv

# List current patterns
archview ignore --list

# Remove a pattern
archview ignore --remove tests

Patterns match any path segment or a file's stem (so tests hides tests/ and tests.py). Add a trailing slash to match a directory only — build/ ignores the build/ folder but keeps a file named build.py. The defaults (build/, dist/, venv/, __pycache__/, …) are all directory-anchored.

How it works

1. Collects source files — .py, plus .sh scripts and config files (.yaml/.json) — git-aware, respects .archviewignore
2. Parses Python via AST (imports, functions, classes); resolves shell-script and config references too
3. Builds a dependency graph with classified nodes
4. Renders it with Cytoscape.js + Dagre layout
5. Watches for changes and re-generates every N seconds

Zero dependencies — pure Python stdlib. The frontend ships bundled.

Example

Try it on the example project (hosted on GitHub):

git clone https://github.com/lm17918/archview.git archview-demo
cd archview-demo
pip install archview
archview examples

License

MIT