umbra-architect 0.4.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
🎨 Dashboard	Beautiful interactive HTML reports
📝 Auto Summary	Natural language project description
🐍 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 .	Scan project + watch for changes
umbra ask	💬 Chat with your codebase
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
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.4)

• Python support
• JavaScript/TypeScript support
• Project summaries
• HTML export
• Ask Umbra - Chat with your codebase
• Health Score - Architecture quality grading
• Insights - Automatic issue detection
• Dashboard - Beautiful HTML reports

Coming Soon

• VS Code extension
• CI/CD integration (generate on PR)
• More languages (Go, Rust, Java)

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