# 🌑 Umbra - The Shadow Architect

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

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/username/umbra/actions/workflows/test.yml/badge.svg)](https://github.com/username/umbra/actions)

## 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

```bash
pip install umbra-architect
```

Or with Poetry:
```bash
git clone https://github.com/username/umbra.git
cd umbra
poetry install
```

### Setup

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

### Usage

```bash
# 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
```mermaid
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

```bash
# Run tests
poetry run pytest

# Lint
poetry run ruff check umbra/

# Format
poetry run ruff format umbra/
```

## 📜 License

MIT License - see [LICENSE](LICENSE) for details.

---

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

*Stop documenting. Start understanding.*
