umbra-architect 0.5.0

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

🌑 Umbra

The Shadow Architect
AI-powered architecture diagrams that update in real-time as you code.

Problem • Solution • Quick Start • Features • Demo

---

😰 The Problem

You're using Cursor, Copilot, or ChatGPT to write code faster than ever. But there's a catch:

You no longer understand your own codebase.

• Documentation is always outdated
• Architecture diagrams are lies
• New team members are lost
• You forgot what that service does

💡 The Solution

Umbra watches your code and maintains a living architecture diagram that updates automatically.

Save file → Umbra detects → AI analyzes → Diagram updates

No more manual documentation. No more outdated diagrams. Just code.

🚀 Quick Start

1. Install

pip install umbra-architect

2. Configure

Get a free API key from Google AI Studio, then:

# Set your API key
export GOOGLE_API_KEY="your-api-key"

# Or create a .env file in your project
echo "GOOGLE_API_KEY=your-api-key" > .env

3. Run

cd your-project
umbra watch .

That's it! Open output/LIVE_ARCHITECTURE.md to see your architecture.

✨ Features

Feature	Description
🔍 Smart Analysis	AI understands semantic changes, not just syntax
📊 Live Diagrams	Mermaid.js diagrams update in real-time
💬 Ask Umbra	Chat with your codebase in natural language
🏥 Health Score	Get an A-F grade for your architecture
⚠️ Auto Insights	Detect god files, high coupling, issues
🎨 Modern Dashboard	Beautiful glassmorphism UI with Bento grid
📝 Auto Summary	Natural language project description
🕐 Recent Changes	AI-powered descriptions of code changes
🔎 Search (Ctrl+K)	Command palette to search your codebase
📥 SVG Export	Download diagrams in vector format
🐍 Python Support	Full Python codebase analysis
⚛️ JS/TS Support	React, Next.js, Express, and more

🎬 Demo

Before: 40 files, no clue what's happening

my-project/
├── src/
│   ├── services/
│   │   ├── auth.py
│   │   ├── payments.py
│   │   ├── notifications.py
│   │   └── ...20 more files
│   ├── api/
│   └── utils/
└── ???

After: Clear architecture in seconds

graph LR
    subgraph Core["Core Services"]
        API[API Gateway]
        Auth[Authentication]
        Payments[Payments]
    end
    
    subgraph External["External APIs"]
        Stripe[Stripe]
        Firebase[Firebase Auth]
    end
    
    subgraph Data["Data Stores"]
        DB[(PostgreSQL)]
    end
    
    API --> Auth
    API --> Payments
    Auth --> Firebase
    Payments --> Stripe
    Payments --> DB

Plus a human-readable summary:

Type: FastAPI Backend
Stack: Python, PostgreSQL, Stripe, Firebase
What it does: E-commerce API with authentication and payment processing

📖 Commands

Command	Description
umbra watch .	🚀 All-in-one: Scan + Watch + Chat Server + Dashboard
umbra watch . --open	Same as above, auto-opens dashboard in browser
umbra watch . --no-scan	Skip initial scan, only watch for changes
umbra ask	💬 Chat with your codebase (interactive)
umbra ask -q "How does auth work?"	Ask a single question
umbra insights	🏥 Show health score & issues
umbra dashboard report.html	🎨 Export stunning HTML dashboard
umbra scan .	One-time full scan (no watch)
umbra export report.html	Simple HTML export

🛠️ Configuration

Create a .env file in your project:

GOOGLE_API_KEY=your-api-key
GEMINI_MODEL=models/gemini-flash-latest
OUTPUT_FILE=./output/LIVE_ARCHITECTURE.md
DEBOUNCE_SECONDS=2

🤔 How It Works

1. Watch - Monitors your files for changes (Python, JS, TS)
2. Analyze - AI determines if the change is structural or cosmetic
3. Update - Only structural changes update the diagram
4. Visualize - Mermaid diagram renders in VS Code or browser

What's "structural"?

✅ Updates Diagram	❌ Ignored
New service class	Renaming variables
External API call	Adding comments
Database connection	Formatting code
Inter-service communication	Test files

🗺️ Roadmap

Current (v0.5)

• Python support
• JavaScript/TypeScript support
• Project summaries
• HTML export
• Ask Umbra - Chat with your codebase
• Health Score - Architecture quality grading
• Insights - Automatic issue detection
• Modern Dashboard - Glassmorphism UI with Bento grid
• Hybrid Mode - Watch + Chat server + Auto-refresh
• Recent Changes - AI-powered change tracking
• Search (Ctrl+K) - Command palette search
• SVG Export - Download diagrams

Coming Soon

• VS Code extension
• CI/CD integration (generate on PR)
• More languages (Go, Rust, Java)
• Click on diagram nodes to view file

Future Vision

• AI Code Analysis - Find bugs and issues automatically
• Auto-Fix Suggestions - AI-powered code corrections
• Team Collaboration - Share architecture across team

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

# Clone
git clone https://github.com/rida12b/Umbra.git
cd Umbra

# Install
poetry install

# Test
poetry run pytest

📜 License

MIT License - see LICENSE for details.

---

Stop documenting. Start understanding.

⭐ Star us on GitHub