umbra-architect 0.2.0

The Shadow Architect - AI-powered live architecture diagrams that update as you code

🌑 Umbra - The Shadow Architect

Understand any codebase in 30 seconds. AI-powered architecture diagrams that update in real-time as you code.

The Problem

As AI accelerates code generation (Cursor, Copilot, etc.), developers lose track of their own architecture. Documentation rots. Diagrams become lies. New team members are lost.

The Solution

Umbra watches your codebase and maintains a living architecture diagram. It uses LLM-powered semantic analysis to understand what changed, not just how.

Save file → Umbra detects → AI analyzes → Diagram updates → You understand

✨ Features

Feature	Description
🔍 Smart Detection	Differentiates cosmetic refactors from structural changes
📊 Live Diagrams	Mermaid.js diagrams that update in real-time
📝 Auto Summary	Natural language project summary generated automatically
🌐 HTML Export	Standalone interactive HTML files to share
⚡ Fast	Under 5 seconds per analysis
🔒 Read-Only	Never modifies your code

🚀 Quick Start

Installation

pip install umbra-architect

Or with Poetry:

git clone https://github.com/username/umbra.git
cd umbra
poetry install

Setup

# Copy and configure
cp .env.example .env
# Add your GOOGLE_API_KEY to .env

Usage

# Scan & watch a project (recommended)
umbra watch .

# Just scan without watching
umbra scan .

# Export to HTML
umbra export architecture.html

# Skip initial scan (faster startup)
umbra watch . --no-scan

📖 Output Example

When you run umbra watch ., you get:

1. Project Summary

**Type:** FastAPI Backend with RAG Pipeline
**Stack:** Python, PostgreSQL, Google Gemini, Supabase Auth
**Size:** 40 files, 3 main services

### What it does
This project is a document processing API that ingests documents,
processes them with AI, and enables semantic search.

### Key Entry Points
- `main.py` → API Gateway (FastAPI)
- `services/ai.py` → AI Processing Service

### External Dependencies
- Google Gemini API (AI processing)
- PostgreSQL (Data storage)

2. Architecture Diagram

graph LR
    subgraph Core["Core Services"]
        API[API Gateway]
        AI[AI Processing]
        Auth[Authentication]
    end
    
    subgraph External["External APIs"]
        Gemini[Google Gemini]
        Supabase[Supabase Auth]
    end
    
    subgraph Data["Data Stores"]
        DB[(PostgreSQL)]
    end
    
    API --> AI
    API --> Auth
    AI --> Gemini
    AI --> DB
    Auth --> Supabase

🎯 What Gets Detected

✅ Structural Changes	❌ Ignored
Main services/classes	Utilities, helpers
External APIs (Stripe, AWS...)	Internal libraries
Database connections	Comments, docstrings
Message queues	Type hints, formatting
Inter-service communication	Test files

⚙️ Configuration

Variable	Default	Description
GOOGLE_API_KEY	-	Google API key for Gemini
GEMINI_MODEL	models/gemini-flash-latest	Model to use
OUTPUT_FILE	./output/LIVE_ARCHITECTURE.md	Output file
DEBOUNCE_SECONDS	2	Delay before analyzing

🛠️ Commands

Command	Description
umbra watch [PATH]	Scan then watch for changes
umbra watch . --no-scan	Watch only (skip initial scan)
umbra scan [PATH]	One-time full project scan
umbra export FILE.html	Export to interactive HTML
umbra init	Create empty architecture file
umbra validate FILE	Validate Mermaid syntax

🔮 Roadmap

• Multi-language support (JavaScript, TypeScript, Go)
• VS Code Extension
• CI/CD Integration (generate on PR)
• Team collaboration features

🧪 Development

# Run tests
poetry run pytest

# Lint
poetry run ruff check umbra/

# Format
poetry run ruff format umbra/

📜 License

MIT License - see LICENSE for details.

---

Built with 🖤 for developers who want to understand their code.

Stop documenting. Start understanding.