Metadata-Version: 2.4
Name: archview
Version: 0.2.7
Summary: Interactive live architecture viewer for Python projects
Author-email: Lorenzo Mirante <lorenzomirante@outlook.com>
License: MIT
Project-URL: Homepage, https://github.com/lm17918/archview
Project-URL: Repository, https://github.com/lm17918/archview
Project-URL: Issues, https://github.com/lm17918/archview/issues
Keywords: architecture,dependency-graph,visualization,ast,python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: flake8>=7.0.0; extra == "dev"
Dynamic: license-file

# 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.

![ArchView overview — live dependency graph updating as code changes](https://raw.githubusercontent.com/lm17918/archview/main/docs/overview.gif)

![Drawing annotations — sketching boxes and labels directly on the graph](https://raw.githubusercontent.com/lm17918/archview/main/docs/drawing.gif)

## 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

```bash
pip install archview
```

Available on [PyPI](https://pypi.org/project/archview/). Pure Python, works anywhere with Python 3.9+.

## Usage

```bash
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.

```bash
# 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

```bash
# 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](https://js.cytoscape.org/) + [Dagre](https://github.com/dagrejs/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):

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

## License

MIT
