README.md

metadata

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

🗺️ CodeAtlas Enterprise

IBM Bob-Powered Engineering Intelligence Platform
Turn any GitHub repository into architecture maps, risk analysis, onboarding documentation, and AI-powered Q&A — in seconds.

Features • Architecture • Quick Start • Demo Flow • API Reference • Deployment

---

✨ 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

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

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 for live AI inference

Backend Setup

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

cd frontend
npm install
npm run dev

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

Environment Configuration

Create backend/.env with your preferred AI provider:

# 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

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

{
  "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)

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 for details.

---

Built with 💙 for the IBM Bob Hackathon
CodeAtlas Enterprise — Engineering Intelligence, Mapped.