Metadata-Version: 2.5
Name: archilens
Version: 0.2.2
Summary: AI-powered layered architecture & process flow visualization for Git repositories
Project-URL: Homepage, https://saurabh-oss.github.io/archilens/
Project-URL: Repository, https://github.com/saurabh-oss/archilens
Project-URL: Issues, https://github.com/saurabh-oss/archilens/issues
Project-URL: Changelog, https://github.com/saurabh-oss/archilens/releases
Author-email: Saurabh <fosslectures@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai,architecture,code-analysis,diagrams,github,llm,mermaid,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: anthropic<3,>=2.3.0
Requires-Dist: click>=8.1.0
Requires-Dist: gitpython>=3.1.40
Requires-Dist: jinja2>=3.1.0
Requires-Dist: litellm>=1.40.0
Requires-Dist: networkx>=3.1
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tree-sitter-go>=0.23.0
Requires-Dist: tree-sitter-java>=0.23.0
Requires-Dist: tree-sitter-javascript>=0.23.0
Requires-Dist: tree-sitter-python>=0.23.0
Requires-Dist: tree-sitter-typescript>=0.23.0
Requires-Dist: tree-sitter>=0.23.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pre-commit>=3.6; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.0.0; extra == 'mcp'
Provides-Extra: viewer
Requires-Dist: flask>=3.0; extra == 'viewer'
Description-Content-Type: text/markdown

# ArchiLens

**AI-powered layered architecture & process flow visualization for Git repositories.**

ArchiLens analyses your codebase and generates interactive, hierarchical architecture diagrams — from system-level context down to runtime process flows. Think of it as **Google Maps for codebases**: zoom from continents (system architecture) to cities (class-level components).

🌐 **Website**: https://saurabh-oss.github.io/archilens/  
📦 **Repository**: https://github.com/saurabh-oss/archilens

---

## How ArchiLens Compares

| Capability | CodeBoarding | GitDiagram | **ArchiLens** |
|---|---|---|---|
| How the architecture is derived | Static analysis + LLM | LLM | **Static analysis (Tree-sitter); LLM optional** |
| Runs with no LLM at all | ✗ | ✗ | **✓** |
| Hierarchical drill-down | ✓ (nested components) | ✗ | **✓ (L0 → L3)** |
| Architecture diff posted on PRs | ✓ | ✗ | **✓** |
| Fail CI on declared architecture rules | ✗ | ✗ | **✓** (layer and fan-out rules) |
| Business capability mapping | ✗ | ✗ | **✓** (declared in config) |
| Evolution across git tags | ✗ | ✗ | **✓** |
| Output formats | Mermaid | Mermaid, PNG | **Mermaid, D2, PlantUML** |
| Interactive viewer | ✓ | ✓ | ✓ (local) |
| MCP server for coding agents | ✓ | ✓ (hosted) | ✓ (local) |
| Process flow / sequence diagrams | ✗ | ✗ | ✓ (AI-inferred) |

<sub>Based on each project's README and docs as checked in October 2026. ✗ means we found no mention of the
capability. Corrections welcome — please open an issue.</sub>

> **Current limitation:** source is parsed for Python, JavaScript, TypeScript, Java and Go, but dependency
> edges *between modules* are currently only resolved for Python projects with a flat (non-`src/`) layout.
> Per-language import resolution is the focus of the next release.

---

## Diagram Levels

```
L0: System Context         ← Your system as a black box + external actors
L1: Module Architecture    ← Major modules/services + dependencies
L2: Component Detail       ← Classes, interfaces inside a module
L3: Process Flows          ← Runtime request lifecycles (AI-inferred)
```

---

## Quick Start

### Prerequisites

- Python 3.10+
- Git
- (Optional) Anthropic API key for AI features

### Installation

```bash
# From PyPI
pip install archilens

# With the interactive web viewer and/or the MCP server
pip install "archilens[viewer,mcp]"

# From source (development)
git clone https://github.com/saurabh-oss/archilens.git
cd archilens
python -m pip install -e ".[dev,viewer,mcp]"
```

> **Windows note**: If `pip` is blocked by policy, use `python -m pip install` instead.

### Initialize in Your Repository

```bash
cd /path/to/your/repo
python -m archilens init
```

This creates a `.archilens.yml` config file. Edit it to:
- Map modules to business capabilities
- Define entry points for process flow tracing
- Configure external systems for the L0 context diagram
- Set architecture rules for CI enforcement

### Generate Diagrams

```bash
# Full analysis, with AI summaries if Anthropic credentials are available
# (ANTHROPIC_API_KEY or `ant auth login`). Without them, ArchiLens prints one
# warning and runs the static analysis only.
python -m archilens analyze --repo .

# Static analysis only, never calls an LLM
python -m archilens analyze --repo . --no-ai

# Generate only a specific level
python -m archilens analyze --repo . --level 1

# Choose output format: mermaid (default), d2, or plantuml
python -m archilens analyze --repo . --format d2

# Output as JSON (for programmatic use)
python -m archilens analyze --repo . --json-output > snapshot.json
```

### Interactive Web Viewer

```bash
python -m archilens serve --repo . --port 8765
```

Requires the `viewer` extra (`pip install "archilens[viewer]"`). Opens a dark-themed single-page app at
`http://127.0.0.1:8765`. It binds to loopback by default; `--host 0.0.0.0` exposes it to your network, and
the viewer has no authentication, so only do that on a trusted network. It includes:
- Sidebar navigation across all four diagram levels
- **Click any module** in the L1 diagram to drill into its L2 component view
- **Zoom controls** (−/+/Fit/1:1), **mouse-wheel zoom**, and **click-drag pan**
- Search/filter sidebar for large repos
- Live re-analysis without restarting the server

### Architecture Drift Detection

```bash
# Compare current branch against main
python -m archilens diff --base main --head HEAD

# Write the diff report to a file
python -m archilens diff --base v1.0 --head v2.0 --output drift.md
```

### Evolution Timeline

```bash
# Analyse architecture across all semver tags
python -m archilens history --repo . --tags

# Analyse specific refs
python -m archilens history --repo . --refs "v1.0,v1.5,v2.0,HEAD"
```

Produces a Mermaid timeline diagram and a full markdown evolution report showing module additions, removals, and LOC trends across your git history.

### MCP Server for AI Coding Agents

ArchiLens can serve its architecture model to coding agents (Claude Code, Cursor and other MCP clients),
so an agent can check where code belongs and whether a new import is allowed *before* it edits.

```bash
pip install "archilens[mcp]"

# Register with Claude Code (stdio transport)
claude mcp add archilens -- archilens serve-mcp --repo /path/to/repo

# Or run as an HTTP/SSE endpoint (binds to 127.0.0.1 by default)
archilens serve-mcp --repo /path/to/repo --transport sse --port 8766
```

| Tool | What it answers |
|---|---|
| `get_architecture_context(scope)` | Compact module map (`L1`), external systems (`L0`), one module's classes (`L2:<module>`), or capability groupings |
| `get_module_context(file_path)` | Which module owns a file, its capability, size, dependencies and dependants |
| `check_dependency_allowed(source_file, target_module)` | Whether an import would break a `no-layer-skip` rule in `.archilens.yml` |
| `find_capability_owner(feature_description)` | Which module and capability a feature most likely belongs to |

The server re-analyses automatically when the repository changes: a new commit, uncommitted edits,
a change to `.archilens.yml`, or an ArchiLens upgrade. Snapshots of clean work trees are cached in
`~/.archilens/snapshots.db`; `--refresh` clears the cache for the repository.

---

## Configuration Reference

The `.archilens.yml` file controls all analysis behaviour.

### Project

```yaml
project:
  name: "My Application"
  description: "What this system does"
  type: "microservices"  # monolith | microservices | modular-monolith | library
```

### Analysis

```yaml
analysis:
  languages: ["python", "typescript"]  # Auto-detected if omitted

  entry_points:
    - pattern: "**/*controller*.py"
      type: "http_handler"
    - pattern: "**/routes/**/*.ts"
      type: "http_handler"

  exclude:
    - "**/node_modules/**"
    - "**/__pycache__/**"
    - "**/venv/**"

  max_depth: 5
```

### Business Capability Mapping

```yaml
capabilities:
  - name: "Order Management"
    description: "Order lifecycle from creation to fulfillment"
    modules:
      - "src/orders/**"
      - "services/order-service/**"

  - name: "Payment Processing"
    modules:
      - "src/payments/**"
```

### External Systems

```yaml
external_systems:
  - name: "PostgreSQL"
    type: "database"
    description: "Primary data store"

  - name: "Stripe API"
    type: "external_api"
    description: "Payment processing"
```

### Diagram Output

```yaml
diagrams:
  output_dir: ".archilens/diagrams"
  format: "mermaid"   # mermaid | d2 | plantuml
  levels:
    - { level: 0, enabled: true }
    - { level: 1, enabled: true }
    - { level: 2, enabled: true }
    - { level: 3, enabled: true }
```

### AI Configuration

```yaml
ai:
  provider: "anthropic"        # anthropic | openai | ollama | litellm
  model: "claude-opus-5-5"     # cheaper option for one-line summaries: "claude-haiku-5-5"
  effort: "low"                # Claude 5 models: low | medium | high | xhigh | max (null = model default)
  features:
    process_flow_inference: true
    node_annotations: true
    capability_suggestions: true
    pattern_detection: true
    module_summaries: true
```

### CI Rules

```yaml
ci:
  drift_detection: true
  pr_comments: true
  rules:
    - name: "no-layer-skip"
      from: "src/presentation/**"
      to: "src/infrastructure/**"
      action: "warn"

    - name: "max-fan-out"
      threshold: 10
      action: "fail"
```

Two rule types exist today, and the rule's `name` selects the type: `no-layer-skip` (forbid dependencies
from modules matching `from` to modules matching `to`) and `max-fan-out` (limit a module's outgoing
dependencies). Rules with any other name are ignored. `action: "fail"` makes `archilens diff` exit with
status 1. Patterns are matched against module paths, and `dir/**` also matches `dir` itself.

---

## GitHub Actions Integration

### Using the ArchiLens action

The composite action runs the analysis, posts (and on later pushes, updates) one architecture-diff
comment per pull request, and uploads the diagrams as a workflow artifact:

```yaml
# .github/workflows/architecture.yml
name: Architecture
on:
  pull_request:

permissions:
  contents: read
  pull-requests: write   # to post the PR comment

jobs:
  archilens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0   # the diff needs the base commit
      - uses: saurabh-oss/archilens/github_action@v0.2.2
        with:
          enable-ai: "false"           # deterministic, no API key needed
          fail-on-violations: "true"   # fail the job on rules with action: "fail"
```

| Input | Default | Meaning |
|---|---|---|
| `repo-path` | `.` | Repository to analyse |
| `enable-ai` | `true` | AI summaries (needs `anthropic-api-key`) |
| `anthropic-api-key` | — | Passed as `ANTHROPIC_API_KEY` |
| `comment-on-pr` | `true` | Post or update the diff comment |
| `fail-on-violations` | `false` | Fail the job when a rule with `action: "fail"` is violated |
| `diagrams-output` | `.archilens/diagrams` | Where diagrams are written |

Outputs: `diagrams-path`, `has-changes`, `violations-count`. The report is also written to the job
summary. On pull requests from forks, GitHub gives the workflow a read-only token, so the comment can't be
posted; the action logs a warning and carries on.

### Writing the workflow yourself

Or add this workflow to your repository:

```yaml
# .github/workflows/archilens.yml
name: Architecture Analysis
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

jobs:
  architecture:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v7
        with:
          python-version: "3.12"

      - run: pip install archilens

      - name: Generate Diagrams
        if: github.event_name == 'push'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: python -m archilens analyze --repo . --output .archilens/diagrams

      - name: Commit Diagrams
        if: github.event_name == 'push'
        run: |
          git config user.name "ArchiLens Bot"
          git config user.email "archilens[bot]@users.noreply.github.com"
          git add .archilens/diagrams/
          git diff --cached --quiet || git commit -m "docs: update architecture diagrams [skip ci]"
          git push

      - name: PR Drift Detection
        if: github.event_name == 'pull_request'
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: python -m archilens diff --base origin/${{ github.base_ref }} --head HEAD
```

---

## Architecture of ArchiLens Itself

```
archilens/
├── archilens/                    # Core Python package
│   ├── __init__.py
│   ├── __main__.py               # Enables python -m archilens
│   ├── cli.py                    # Click CLI with Rich output
│   ├── config.py                 # YAML config loader + defaults
│   ├── engine.py                 # Main orchestrator pipeline
│   ├── models/
│   │   └── __init__.py           # Pydantic models (ArchSnapshot, nodes, edges, flows)
│   ├── analyzers/
│   │   ├── discovery.py          # File discovery + language detection
│   │   ├── dependencies.py       # Static analysis (imports, classes, call graph)
│   │   ├── treesitter.py         # Tree-sitter AST extraction (Python/JS/TS/Java/Go)
│   │   ├── diff.py               # Architecture diff engine
│   │   ├── evolution.py          # Git history evolution & timeline
│   │   └── git_utils.py          # Git ref checkout via blob reading
│   ├── generators/
│   │   ├── base.py               # DiagramGenerator ABC + factory
│   │   ├── mermaid.py            # Mermaid.js output (L0-L3)
│   │   ├── d2.py                 # D2 output (L0-L3)
│   │   └── plantuml.py           # PlantUML output (L0-L3)
│   ├── viewer/
│   │   ├── __init__.py
│   │   └── app.py                # Flask SPA with zoom/pan, drill-down
│   ├── mcp/
│   │   ├── server.py             # MCP server: architecture tools for coding agents
│   │   └── cache.py              # SQLite snapshot cache
│   ├── ai/
│   │   └── __init__.py           # LLM integration (Anthropic/OpenAI/Ollama)
│   └── utils/
│       └── __init__.py           # Module glob matching
├── docs/
│   └── index.html                # GitHub Pages landing site
├── github_action/
│   └── action.yml                # Composite GitHub Action
├── tests/                        # pytest suite (CLI, analysis, generators, MCP, viewer)
├── .archilens.yml                # Example configuration
├── .github/workflows/
│   ├── ci.yml                    # Tests, Ruff, mypy
│   ├── publish.yml               # PyPI release on v*.*.* tags
│   └── archilens.yml             # Example CI workflow
├── pyproject.toml                # Project metadata + dependencies
└── README.md
```

### Pipeline Flow

```
  .archilens.yml          Source Code           Git History
       │                      │                      │
       ▼                      ▼                      ▼
  ┌──────────┐      ┌──────────────────┐     ┌────────────┐
  │  Config   │      │    Discovery     │     │  Git Utils │
  │  Loader   │      │  (Tree-sitter)   │     │ (evolution │
  └────┬─────┘      └───────┬──────────┘     │  + diff)   │
       │                    │                └─────┬──────┘
       ▼                    ▼                      │
  ┌─────────────────────────────────────────────────────────┐
  │                    Analysis Engine                       │
  │  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐  │
  │  │   Static    │  │     AI       │  │   Metrics &   │  │
  │  │  Analysis   │  │  Augmentation│  │   Patterns    │  │
  │  └──────┬──────┘  └──────┬───────┘  └───────┬───────┘  │
  │         └────────┬────────┘──────────────────┘          │
  └──────────────────┼──────────────────────────────────────┘
                     ▼
              ┌──────────────┐
              │ ArchSnapshot │  (Pydantic: nodes + edges + flows)
              └──────┬───────┘
                     │
       ┌─────────────┼──────────────┐
       ▼             ▼              ▼
  ┌─────────┐  ┌──────────┐  ┌──────────┐
  │Mermaid  │  │    D2    │  │ PlantUML │
  │  (L0-3) │  │  (L0-3)  │  │  (L0-3)  │
  └────┬────┘  └──────────┘  └──────────┘
       │
       ▼
  ┌──────────┐   ┌──────────┐   ┌──────────┐
  │ Web      │   │   Diff   │   │   JSON   │
  │ Viewer   │   │  Report  │   │  Export  │
  └──────────┘   └──────────┘   └──────────┘
```

---

## Development Setup

```bash
# Clone the repository
git clone https://github.com/saurabh-oss/archilens.git
cd archilens

# Create virtual environment
python -m venv .venv
source .venv/bin/activate   # Linux/Mac
# .venv\Scripts\activate    # Windows

# Install with dev dependencies (viewer and mcp extras are needed by the tests and mypy)
python -m pip install -e ".[dev,viewer,mcp]"

# Run tests
pytest tests/ -v --cov=archilens

# Lint
ruff check archilens/
ruff format --check archilens/
mypy archilens/
```

---

## Roadmap

- [x] Core static analysis engine (multi-language via Tree-sitter + regex fallback)
- [x] L0-L3 Mermaid diagram generation
- [x] D2 and PlantUML output formats
- [x] AI-powered process flow inference and module summaries
- [x] Architecture drift detection (diff engine with CI rules)
- [x] Git history evolution timeline (`archilens history`)
- [x] GitHub Action for CI/CD
- [x] Business capability mapping
- [x] CLI with Rich output (`analyze`, `diff`, `history`, `serve`, `init`)
- [x] Interactive web viewer with zoom/pan and click-to-drill-down
- [x] GitHub Pages landing site
- [x] PyPI release (`pip install archilens`)
- [ ] VS Code extension
- [ ] GitHub App (persistent bot with richer PR integration)
- [ ] Monorepo support (multi-service cross-repo analysis)
- [ ] OpenTelemetry integration (runtime architecture from traces)

---

## Contributing

Contributions are welcome! Key areas:

1. **Language parsers** — Add Tree-sitter grammars for more languages (Ruby, Rust, C#, etc.)
2. **Pattern detection** — Expand the set of recognized architectural patterns (CQRS, Saga, etc.)
3. **VS Code extension** — TypeScript extension surfacing L2/L3 diagrams inline
4. **GitHub App** — Probot/Node.js app for persistent PR bot integration

---

## License

MIT — see [LICENSE](LICENSE).
