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 ```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. ---
Built with π for the IBM Bob Hackathon
CodeAtlas Enterprise β Engineering Intelligence, Mapped.