AutoC4 Project Documentation

Project Overview

AutoC4 is an AI-driven codebase analysis and C4 architecture generation platform that combines advanced code parsing, AI-powered summarization, vector embeddings, and intelligent search capabilities to automatically generate C4 architecture models from source code repositories.

Architecture

Frontend Application

Technology Stack:

• React 18.2.0 with TypeScript
• Material-UI (MUI) v5.15.15 for UI components
• Vite as build tool and development server
• React Router DOM v6.22.3 for navigation
• TanStack React Query v5.28.9 for data fetching and state management
• Axios for HTTP client
• React Markdown for rendering markdown content

Key Features:

• Responsive dashboard with system status monitoring
• Repository analysis interface supporting GitHub, GitLab, Bitbucket, and ZIP uploads
• Real-time pipeline progress tracking
• Interactive C4 model viewer with four levels (System Context, Containers, Components, Code)
• Chat interface for natural language codebase queries
• Modern dark/light theme with Material Design principles

Application Structure:

txt
Copy

Backend Application

Technology Stack:

• NestJS framework with TypeScript
• Tree-sitter for AST parsing (JavaScript, TypeScript, Python, Java)
• Azure OpenAI for AI completions and embeddings
• Azure AI Search for vector and hybrid search
• Simple-git for Git repository operations
• JSZip for archive handling
• UUID for unique identifier generation

Core Services:

1. IngestionService: Handles repository cloning and ZIP file extraction

   • Supports GitHub, GitLab, Bitbucket (public/private)
   • ZIP file upload and extraction
   • Repository validation and branch detection

2. ParserService: AST-based code analysis

   • Multi-language support (JS, TS, Python, Java)
   • Extracts classes, functions, methods, imports, exports
   • Generates structured project representations

3. SummarizationService: AI-powered code summarization

   • Azure OpenAI integration for code analysis
   • Generates summaries with complexity analysis
   • Extracts key features and dependencies

4. EmbeddingService: Vector embedding generation

   • text-embedding-ada-002 model integration
   • Batch processing with rate limiting
   • 1536-dimensional vectors for semantic search

5. SearchService: Azure AI Search integration

   • Hybrid search (keyword + vector)
   • Index management and document operations
   • Faceted search with filtering capabilities

6. PipelineService: Orchestrates the analysis workflow

   • Multi-stage processing pipeline
   • Real-time progress tracking
   • Error handling and recovery

7. AgentService: AI agent for C4 model generation

   • Tool-based architecture for codebase exploration
   • Structured C4 model output
   • Multi-level architecture analysis

8. ChatService: RAG-based chat interface

   • Context-aware responses using retrieved code
   • Conversation history management
   • Source attribution and relevance scoring

Data Flow and Processing Pipeline

Stage 1: Repository Ingestion

• Repository URL validation and authentication
• Git cloning or ZIP extraction to temporary directory
• Metadata collection (size, file count, repository type)

Stage 2: Code

• Tree-sitter AST parsing for supported languages
• Extraction of code structures (classes, functions, methods)
• Import/export relationship analysis
• Generation of structured project representation

Stage 3: Code Summarization

• AI-powered analysis of code components
• Generation of natural language summaries
• Complexity assessment and feature extraction
• Dependency identification

Stage 4: Vector Embedding Generation

• Conversion of summaries to vector embeddings
• Batch processing for efficiency
• 1536-dimensional vectors using Azure OpenAI

Stage 5: Search Indexing

• Azure AI Search index creation/update
• Document upload with metadata
• Vector search configuration
• Full-text and hybrid search setup

Stage 6: C4 Model Generation

• AI agent-based architecture analysis
• Multi-level C4 model creation:
  • C1: System Context (actors, external systems)
  • C2: Containers (applications, databases)
  • C3: Components (modules, services)
  • C4: Code (classes, functions)

API Endpoints

Analysis API (/api/v1/analysis)

• POST / - Create repository analysis
• POST /upload - Upload ZIP file analysis
• POST /branches - Get repository branches
• GET /:id/status - Get analysis status
• POST /:id/c4-model - Generate C4 model
• GET /:id/c4-model - Retrieve C4 model
• GET /:id/files - Get file structure

Chat API (/api/v1/chat)

• POST / - Send chat message
• GET /:id/info - Get analysis info
• GET /:id/suggestions - Get suggested questions

System API (/api)

• GET /health - System health check
• GET / - Application information

Data Models

Analysis Request

typescript
Copy

Project Structure

typescript
Copy

C4 Model

typescript
Copy

Configuration

Environment Variables

bash
Copy

Frontend Configuration

bash
Copy

File System Structure

Temporary Analysis Storage

txt
Copy

Azure AI Search Indexes

• Index naming: c4mcp-codebase-{analysis-id}
• Vector dimensions: 1536 (text-embedding-ada-002)
• Search algorithms: HNSW for vector search
• Document schema includes code chunks, summaries, embeddings, metadata

Supported Languages and File Types

Fully Supported (AST Parsing):

• JavaScript (.js, .jsx)
• TypeScript (.ts, .tsx)
• Python (.py)
• Java (.java)

Repository Sources:

• GitHub (public/private)
• GitLab (public/private)
• Bitbucket (public/private)
• ZIP file upload (max 100MB)

Key Features

1. Multi-Source Repository Ingestion: Support for major Git providers with authentication
2. Advanced Code Parsing: AST-based analysis with Tree-sitter for accurate code structure extraction
3. AI-Powered Analysis: Azure OpenAI integration for intelligent code summarization and C4 generation
4. Semantic Search: Vector embeddings with hybrid search capabilities
5. Interactive C4 Models: Four-level architecture visualization with drill-down capabilities
6. Natural Language Chat: RAG-based conversational interface for codebase exploration
7. Real-time Processing: Live pipeline progress tracking with detailed status updates
8. Comprehensive API: RESTful API with OpenAPI documentation

Technical Specifications

• Frontend Build: Vite-based development and production builds
• Backend Framework: NestJS with dependency injection and modular architecture
• Database: Stateless design using Azure AI Search for persistence
• Authentication: Personal Access Token support for private repositories
• File Processing: Streaming file operations with configurable batch sizes
• Error Handling: Comprehensive error boundaries and graceful degradation
• Performance: Optimized for large codebases with efficient chunking and batching