README.md

---
title: CodeAtlas Enterprise
emoji: 🗺️
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
license: mit
short_description: IBM Bob-Powered Engineering Intelligence Platform
---

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://capsule-render.vercel.app/api?type=waving&color=0:0f172a,50:1e3a5f,100:38bdf8&height=200&section=header&text=🗺️%20CodeAtlas%20Enterprise&fontSize=42&fontColor=e0f2fe&animation=fadeIn&fontAlignY=35&desc=IBM%20Bob-Powered%20Engineering%20Intelligence&descSize=16&descColor=7dd3fc&descAlignY=55">
    <img src="https://capsule-render.vercel.app/api?type=waving&color=0:0f172a,50:1e3a5f,100:38bdf8&height=200&section=header&text=🗺️%20CodeAtlas%20Enterprise&fontSize=42&fontColor=e0f2fe&animation=fadeIn&fontAlignY=35&desc=IBM%20Bob-Powered%20Engineering%20Intelligence&descSize=16&descColor=7dd3fc&descAlignY=55" alt="CodeAtlas Enterprise Banner" width="100%" />
  </picture>
</p>

<h1 align="center">🗺️ CodeAtlas Enterprise</h1>

<p align="center">
  <strong>IBM Bob-Powered Engineering Intelligence Platform</strong><br/>
  Turn any GitHub repository into architecture maps, risk analysis, onboarding documentation, and AI-powered Q&A — in seconds.
</p>

<p align="center">
  <img src="https://img.shields.io/badge/React-18.3-61DAFB?style=for-the-badge&logo=react&logoColor=white" alt="React" />
  <img src="https://img.shields.io/badge/FastAPI-0.111-009688?style=for-the-badge&logo=fastapi&logoColor=white" alt="FastAPI" />
  <img src="https://img.shields.io/badge/IBM_Bob-Inference-052FAD?style=for-the-badge&logo=ibm&logoColor=white" alt="IBM Bob" />
  <img src="https://img.shields.io/badge/Vite-5.2-646CFF?style=for-the-badge&logo=vite&logoColor=white" alt="Vite" />
  <img src="https://img.shields.io/badge/Python-3.11+-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python" />
  <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License" />
</p>

<p align="center">
  <a href="#-features">Features</a> •
  <a href="#-architecture">Architecture</a> •
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-demo-flow">Demo Flow</a> •
  <a href="#-api-reference">API Reference</a> •
  <a href="#-deployment">Deployment</a>
</p>

---

## ✨ Features

CodeAtlas Enterprise transforms raw codebases into actionable engineering intelligence through **6 core modules**, each powered by IBM Bob AI inference:

| Module | Description | Key Capabilities |
|--------|-------------|-----------------|
| 🔄 **Repository Ingestion** | Clone & scan any public GitHub repo | File tree extraction, language detection, dependency parsing |
| 🏗️ **Architecture Intelligence** | AI-generated architecture maps | Interactive React Flow graphs, Mermaid diagrams, service discovery |
| 💬 **Engineering Assistant** | Repository-aware AI Q&A | Context-window answers, code location tracing, risk flagging |
| 💥 **Impact Analysis** | Change-risk blast radius prediction | Risk scoring, failure scenarios, deployment checklists |
| 📄 **Documentation Generation** | Auto-generated docs from code | Onboarding guides, API reference, Architecture Decision Records |
| 📊 **Engineering Metrics** | Codebase health scoring | Complexity index, maintainability grade, tech debt estimation |

### 🎯 What Makes It Special

- **🧠 IBM Bob AI**: Every intelligence module uses IBM Bob inference (Shell or HTTP) for production-quality analysis
- **🔁 Graceful Fallback**: Fully functional demo mode with deterministic local intelligence when no API key is configured
- **⚡ Background Jobs**: Long-running AI tasks execute as async background jobs — no request timeouts
- **🗺️ Rich Architecture Diagrams**: Layered Mermaid flowcharts with tech stack, service subgraphs, labeled dependencies, and CSS-styled nodes
- **🔄 Interactive Graphs**: Clickable React Flow service maps with node-level AI explanations
- **💾 Session Persistence**: Zustand stores with sessionStorage keep state across navigation

---

## 🏗️ Architecture

### System Overview

```mermaid
flowchart LR
  subgraph Client["⚛️ React Frontend (Vite)"]
    Pages["Pages\n(Landing, Ingestion, Dashboard,\nArchitecture, Workflow, Assistant,\nImpact, Documentation)"]
    Components["UI Components\n(React Flow, Mermaid,\nRecharts, GlassCards)"]
    State["Zustand Stores\n(Repo, Analysis, Graph)"]
    APIClient["Axios API Client"]
  end

  subgraph Server["🐍 FastAPI Backend"]
    Main["main.py\n(CORS, Routers, Health)"]
    subgraph Modules["Intelligence Modules"]
      Ingest["Ingestion\n(clone, scan, detect)"]
      Arch["Architecture\n(analyzer, graph_builder)"]
      Assist["Assistant\n(qa_engine)"]
      Impact["Impact\n(risk_engine)"]
      Docs["Documentation\n(doc_generator)"]
      Metrics["Metrics\n(metrics_engine)"]
    end
    Core["Core Layer\n(watsonx.py, config.py)"]
    Utils["Utilities\n(cache, jobs, context_builder)"]
  end

  subgraph AI["🤖 IBM Bob AI"]
    BobShell["Bob Shell CLI"]
    BobHTTP["Bob HTTP Endpoint"]
    LocalDemo["Local Demo Intelligence"]
  end

  subgraph External["🌐 External"]
    GitHub["GitHub Repos"]
  end

  Pages --> Components
  Pages --> APIClient
  APIClient -->|"REST API"| Main
  Main --> Modules
  Modules --> Core
  Modules --> Utils
  Core -->|"inference"| AI
  Ingest -->|"git clone"| GitHub
  State -.->|"sessionStorage"| Pages
```

### Tech Stack

| Layer | Technology | Purpose |
|-------|-----------|---------|
| **Frontend** | React 18, Vite 5, React Router v6 | SPA with client-side routing |
| **UI Libraries** | React Flow, Mermaid, Recharts, Framer Motion | Interactive graphs, diagrams, charts, animations |
| **State** | Zustand + sessionStorage | Persistent client state |
| **Styling** | Tailwind CSS 3, Lucide Icons | Utility-first design system |
| **HTTP** | Axios | API communication with timeout handling |
| **Backend** | FastAPI, Uvicorn | Async Python API server |
| **AI Engine** | IBM Bob (Shell + HTTP), Watsonx SDK | LLM inference with multi-provider fallback |
| **Git** | GitPython | Repository cloning and scanning |
| **Validation** | Pydantic v2, Pydantic Settings | Request/config validation |
| **HTTP Client** | httpx | Async HTTP for Bob API calls |

### Data Flow

```mermaid
sequenceDiagram
    participant U as User
    participant FE as React Frontend
    participant API as FastAPI Server
    participant Job as Background Job
    participant AI as IBM Bob
    participant GH as GitHub

    U->>FE: Enter repo URL
    FE->>API: POST /api/repo/ingest
    API->>GH: git clone (depth=1)
    GH-->>API: Repository files
    API->>API: Scan structure, detect tech, parse deps
    API-->>FE: repo_id + ingestion data

    U->>FE: Navigate to Architecture
    FE->>API: POST /api/architecture/analyze/start
    API->>Job: Create async background job
    API-->>FE: job_id (status: queued)
    Job->>AI: Architecture analysis prompt
    AI-->>Job: JSON analysis result
    Job->>Job: Build React Flow graph + Mermaid
    FE->>API: GET /api/architecture/analyze/jobs/{id}
    API-->>FE: Completed result with graph data

    U->>FE: Ask question in Assistant
    FE->>API: POST /api/assistant/ask
    API->>AI: Q&A prompt with repo context
    AI-->>API: Structured answer
    API-->>FE: answer, implementation, related, risks
```

### Directory Structure

```
codeatlas-enterprise/
├── backend/
│   ├── main.py                    # FastAPI app entry point
│   ├── requirements.txt           # Python dependencies
│   ├── core/
│   │   ├── config.py              # Pydantic settings (env-driven)
│   │   └── watsonx.py             # IBM Bob / Watsonx AI client
│   ├── models/
│   │   ├── repo.py                # Ingestion request/response models
│   │   ├── analysis.py            # Architecture & docs models
│   │   ├── graph.py               # React Flow graph models
│   │   └── risk.py                # Impact analysis models
│   ├── modules/
│   │   ├── ingestion/             # Clone, scan, detect, parse
│   │   ├── architecture/          # AI analysis + graph builder
│   │   ├── assistant/             # Repository Q&A engine
│   │   ├── impact/                # Change risk engine
│   │   ├── documentation/         # Doc generator (3 types)
│   │   └── metrics/               # Engineering health metrics
│   └── utils/
│       ├── cache.py               # In-memory caches
│       ├── jobs.py                # Async background job runner
│       ├── context_builder.py     # Prompt context assembly
│       └── file_utils.py          # File I/O helpers
├── frontend/
│   ├── index.html                 # Vite entry
│   ├── package.json               # Node dependencies
│   ├── vite.config.js             # Vite configuration
│   ├── tailwind.config.js         # Tailwind theme
│   └── src/
│       ├── App.jsx                # Route definitions
│       ├── main.jsx               # React mount
│       ├── index.css              # Global styles
│       ├── api/client.js          # Axios HTTP client
│       ├── store/                 # Zustand state stores
│       ├── pages/                 # 8 route pages
│       ├── components/            # Shared + domain components
│       └── utils/                 # Formatters, transformers, polling
├── .tools/
│   └── bob-shell/                 # Bundled IBM Bob Shell CLI
└── docs/
    └── banner.png                 # README banner
```

---

## 🚀 Quick Start

### Prerequisites

- **Python 3.11+** with pip
- **Node.js 18+** with npm
- *(Optional)* IBM Bob API key from [bob.ibm.com](https://bob.ibm.com) for live AI inference

### Backend Setup

```bash
cd backend
python -m venv venv

# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

pip install -r requirements.txt
copy .env.example .env        # Windows
# cp .env.example .env        # macOS/Linux

uvicorn main:app --reload --port 8000
```

### Frontend Setup

```bash
cd frontend
npm install
npm run dev
```

Open **http://localhost:5173** in your browser.

### Environment Configuration

Create `backend/.env` with your preferred AI provider:

```env
# Option 1: IBM Bob Inference API key (recommended)
AI_PROVIDER=bob
BOB_API_KEY=your_ibm_bob_inference_api_key

# Option 2: Direct Bob HTTP endpoint
BOB_API_URL=https://your-bob-endpoint.ibm.com/v1/chat/completions
BOB_API_KEY=your_key

# Option 3: Watsonx SDK (requires project ID)
AI_PROVIDER=watsonx
WATSONX_API_KEY=your_watsonx_api_key
WATSONX_PROJECT_ID=your_project_id

# Option 4: No keys = automatic local demo mode (no setup needed!)
AI_PROVIDER=auto
```

> **💡 No API key?** CodeAtlas works fully without any keys using deterministic local intelligence. Every feature remains functional with realistic demo output.

---

## 🎬 Demo Flow

### 1. Landing Page
Choose **Analyze Repository** to begin the intelligence pipeline.

### 2. Repository Ingestion
Enter a public GitHub URL (e.g., `https://github.com/tiangolo/fastapi`).
CodeAtlas clones, scans file structure, detects technologies, and parses dependencies.

### 3. Dashboard
Review at a glance:
- 📊 Repository metrics (files, lines, complexity)
- 🔧 Detected tech stack (frameworks, languages, databases)
- 🏗️ Architecture summary
- ⚠️ Risk areas

### 4. Architecture Intelligence
Explore the AI-generated architecture:
- **Mermaid Diagram**: Layered flowchart with Tech Stack, Frontend, API, Backend, AI, Storage subgraphs
- **React Flow Graph**: Interactive node graph — click any service for AI-powered explanation
- **Business Workflows**: Unified project workflow with step-by-step trace

### 5. Engineering Assistant
Ask natural language questions about the codebase:
- *"How does authentication work?"*
- *"What happens when a user creates an order?"*
- *"Which files handle database migrations?"*

### 6. Impact Analysis
Select any file and get:
- Risk level (LOW → CRITICAL) with score
- Impacted services and APIs
- Failure scenarios with probability
- Recommended tests and deployment checklist

### 7. Documentation Generation
Generate three document types:
- **Onboarding Guide**: Setup, architecture, key files, workflows
- **API Reference**: Detected endpoints, auth, testing guidance
- **Architecture ADR**: Decisions, service boundaries, data flow, risks

### 8. Workflow Visualization
Review and explore detected repository workflows with interactive flow diagrams.

---

## 📡 API Reference

### Base URL: `http://localhost:8000`

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/health` | Server health check |
| `GET` | `/api/ai/status` | AI provider status |
| `GET` | `/api/ai/ping` | Test AI inference round-trip |
| `POST` | `/api/repo/ingest` | Ingest a GitHub repository |
| `POST` | `/api/repo/ingest-local` | Ingest a local directory |
| `GET` | `/api/repo/{id}/status` | Repository status |
| `POST` | `/api/architecture/analyze` | Synchronous architecture analysis |
| `POST` | `/api/architecture/analyze/start` | Start background architecture job |
| `GET` | `/api/architecture/analyze/jobs/{id}` | Poll architecture job status |
| `GET` | `/api/architecture/{id}/cached` | Get cached analysis |
| `GET` | `/api/architecture/{id}/workflow` | Get workflow diagram |
| `POST` | `/api/assistant/ask` | Ask a repository question |
| `POST` | `/api/impact/analyze` | Analyze change impact |
| `POST` | `/api/docs/generate` | Synchronous doc generation |
| `POST` | `/api/docs/generate/start` | Start background doc job |
| `GET` | `/api/docs/generate/jobs/{id}` | Poll docs job status |
| `GET` | `/api/metrics/{id}` | Get engineering metrics |
| `POST` | `/api/metrics/{id}/start` | Start background metrics job |
| `GET` | `/api/metrics/jobs/{id}` | Poll metrics job status |
| `GET` | `/api/jobs` | List all background jobs |

### Example: Ingest a Repository

```bash
curl -X POST http://localhost:8000/api/repo/ingest \
  -H "Content-Type: application/json" \
  -d '{"github_url": "https://github.com/tiangolo/fastapi"}'
```

```json
{
  "repo_id": "a1b2c3d4",
  "status": "ingested",
  "technologies": {
    "frameworks": ["FastAPI"],
    "languages": [{"name": "Python", "file_count": 245}],
    "databases": [],
    "devops": ["GitHub Actions"]
  },
  "structure": {"total_files": 312, "total_lines": 48500},
  "message": "Repository analyzed: 312 files, 48500 lines of code"
}
```

---

## 🚢 Deployment

### Docker (Recommended)

```bash
docker build -t codeatlas-enterprise .
docker run -p 7860:7860 -e BOB_API_KEY=your_key codeatlas-enterprise
```

### Hugging Face Spaces

This project is deployed on HF Spaces. The `Dockerfile` builds both frontend and backend into a single container:

1. Frontend is built with `npm run build` → static files served by FastAPI
2. Backend runs on Uvicorn at port 7860
3. All configuration via environment variables (Secrets in HF Spaces settings)

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `AI_PROVIDER` | No | `auto` | `bob`, `watsonx`, or `auto` |
| `BOB_API_KEY` | No | — | IBM Bob inference API key |
| `BOB_API_URL` | No | — | Direct Bob HTTP endpoint |
| `WATSONX_API_KEY` | No | — | Watsonx SDK API key |
| `WATSONX_PROJECT_ID` | No | — | Watsonx project ID |
| `BOB_TIMEOUT_SECONDS` | No | `600` | Max AI inference timeout |
| `CORS_ORIGINS` | No | `localhost` | Allowed CORS origins |

---

## 🔧 Intelligence Pipeline

### How the AI Architecture Diagram Works

```
GitHub Repo URL
      │
      ▼
┌─────────────┐     ┌──────────────┐     ┌───────────────┐
│  Git Clone   │────▶│  File Scan    │────▶│  Tech Detect   │
│  (depth=1)   │     │  (structure)  │     │  (frameworks)  │
└─────────────┘     └──────────────┘     └───────────────┘
                                                  │
                                                  ▼
                                    ┌──────────────────────┐
                                    │  Context Builder      │
                                    │  (compact repo prompt)│
                                    └──────────────────────┘
                                                  │
                                                  ▼
                                    ┌──────────────────────┐
                                    │  IBM Bob Inference    │
                                    │  (architecture JSON)  │
                                    └──────────────────────┘
                                                  │
                              ┌───────────────────┼───────────────────┐
                              ▼                   ▼                   ▼
                    ┌─────────────┐    ┌──────────────┐    ┌─────────────┐
                    │ React Flow   │    │ Mermaid       │    │ Workflows   │
                    │ Graph Builder│    │ Diagram       │    │ Synthesis   │
                    └─────────────┘    └──────────────┘    └─────────────┘
```

The Mermaid diagram includes:
- **Tech Stack subgraph** — detected frameworks, languages, databases, DevOps
- **Frontend Client** — pages, UI component domains, API client, state management
- **API Layer** — route surfaces, REST endpoints
- **Backend Services** — individual domain engine modules
- **AI / Middleware** — IBM Bob inference bridge
- **Security & Auth** — authentication and authorization modules
- **Data & Storage** — persistence layer with database detection
- **Utilities** — configuration, shared helpers, DevOps/CI

---

## 🧩 Key Design Decisions

1. **Multi-provider AI**: Bob Shell → Bob HTTP → Watsonx SDK → Local Demo fallback chain
2. **Background jobs**: Long AI tasks run as `asyncio.create_task()` with polling API
3. **In-memory caching**: `repo_cache`, `analysis_cache`, `metrics_cache`, `docs_cache` for hackathon speed
4. **Context windows**: `context_builder.py` assembles compact, high-signal prompts within token limits
5. **React enrichment**: Specialized file-tree scanning for React+FastAPI stacks with granular service discovery
6. **Deterministic fallback**: Local intelligence produces realistic architecture with 14+ services, 25+ dependencies

---

## 📝 License

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

---

<p align="center">
  Built with 💙 for the IBM Bob Hackathon<br/>
  <strong>CodeAtlas Enterprise</strong> — Engineering Intelligence, Mapped.
</p>