ArchitectLens

ArchitectLens is an automated reverse-engineering and architecture extraction tool. Point it at a codebase ZIP and it generates structured documentation from it: a Knowledge Sharing (KT) guide, and/or a formal SRS, BRD, HLD, and LLD document set — via a CLI or an MCP server, backed by Claude (default), OpenAI, Gemini, a local Ollama model, or AWS Bedrock.

Project status

Functional CLI and MCP server (v0.1.0). WBS.md tracks implementation progress against plan_doc.txt (the approved architecture plan).

Install

pip install -e .
# or, to enable specific extra providers:
pip install -e ".[openai]"
pip install -e ".[gemini]"
pip install -e ".[ollama]"
pip install -e ".[bedrock]"
# or all of them at once:
pip install -e ".[all-providers]"

This registers two console scripts: architectlens (CLI) and architectlens-mcp (MCP server).

CLI usage

# Knowledge Sharing / Framework Guide only
architectlens generate --zip ./codebase.zip --kt --out ./output

# Any combination of SRS/HLD/LLD (generated together, one coherent LLM call, split into separate files)
architectlens generate --zip ./codebase.zip --srs --hld --lld --brd --out ./output

# Every document type
architectlens generate --zip ./codebase.zip --all --out ./output

# Preview the composed prompts + codebase digest without calling any LLM
architectlens generate --zip ./codebase.zip --hld --dry-run

# Use a different provider/model
architectlens generate --zip ./codebase.zip --kt --provider openai --model gpt-4o

Run architectlens generate --help for the full flag reference. Output is written to <--out>/<project-name>/:

<project-name>/
  KT-Docs/knowledge-sharing-guide.md
  Reverse-Engineering/SRS.md
  Reverse-Engineering/HLD.md
  Reverse-Engineering/LLD.md
  Reverse-Engineering/BRD.md

MCP server

Start it directly with architectlens-mcp, or register it with an MCP client, e.g. in claude_desktop_config.json:

{
  "mcpServers": {
    "architectlens": {
      "command": "architectlens-mcp"
    }
  }
}

It exposes two tools:

• list_doc_types() — the doc type identifiers accepted below.
• generate_documentation(zip_path, doc_types, output_dir, provider="anthropic", model=None, dry_run=False) — same behavior as the CLI's generate command; returns {project_name, output_dir, files_written, warnings}.

Providers

Bedrock auth is handled entirely by boto3's standard credential chain, which already covers every AWS auth style without any special flags here — just set AWS_REGION/AWS_DEFAULT_REGION and, optionally, AWS_PROFILE:

• AWS SSO login — run aws sso login against a profile set up with aws configure sso, then set AWS_PROFILE to it.
• IAM user — static AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY (env vars, the shared credentials file, or a profile).
• Role / service account — an EC2 instance profile, ECS/Lambda execution role, or Kubernetes IRSA (AWS_ROLE_ARN + AWS_WEB_IDENTITY_TOKEN_FILE); boto3 picks these up automatically when running in that environment, no configuration needed here.

Environment variables

Both the CLI and the MCP server auto-load a .env file (via python-dotenv, looked up from the current working directory) before resolving any of these — a project-root .env is picked up with no extra flags. .env is git-ignored; never commit it.

Prompt templates

The LLM prompts that drive documentation generation live in src/architectlens/prompts/templates/:

• knowledge_sharing_guide.md — KT / Framework Guide generation
• srs_hld_lld.md — SRS, HLD, and LLD generation (section-selectable)
• brd.md — Business Requirements Document generation

Development

pip install -e ".[dev]"
pytest

# security checks (also run in CI on every push/PR)
bandit -r src
pip-audit

CI (.github/workflows/ci.yml) runs the test suite plus these two security checks on every push and pull request against main. Releases publish to PyPI via .github/workflows/publish-pypi.yml (trusted publishing, no stored token) on each GitHub Release.