| name | codebase-architecture-analysis |
| description | Analyze a GitHub codebase to create comprehensive architecture documentation including ASCII diagrams, component relationships, data flow, hosting infrastructure, and file structure assessment. |
| compatibility | Requires git, GitHub authentication via PAT, and network access to GitHub |
| license | MIT |
Codebase Architecture Analysis
When to use this skill
Use this skill when you need to understand the high-level architecture and structure of a codebase. Specifically, use it when you need to:
- Create architecture diagrams for documentation
- Understand component relationships and dependencies
- Assess hosting infrastructure and deployment architecture
- Generate comprehensive architectural overviews
- Document data flow between system components
- Create visual representations of code organization
Overview
This skill guides a specialized agent through a comprehensive analysis of a GitHub repository to produce detailed architecture documentation. The analysis includes ASCII diagrams, component maps, infrastructure details, and file-level assessments.
Workflow
Step 1: Repository Setup
Input required:
- GitHub repository URL or
owner/repo format
- Optional: Specific branch or commit to analyze
Actions:
- Clone the repository using the GitHub PAT from environment variables
- Verify the repository is cloned successfully
- Document the repository metadata (language, size, structure)
YOU MUST CLONE THE REPOSITORY AND INSPECT THE FILES USING BASH TOOLS AND GIT CLI RATHER THAN MCP.
Step 2: Codebase Discovery and Assessment
Analyze the directory structure:
- Map the complete directory tree
- Identify major components/modules/packages
- Classify directories by purpose (src, config, tests, build, etc.)
- Count files by type (TypeScript, Python, JSON, etc.)
- Identify entry points and main application files
For each file, assess:
- File type and purpose
- Size and complexity
- Key imports and dependencies
- What module/component it belongs to
- Role in the overall system
Step 3: Create Architecture Diagrams
Create multiple ASCII diagrams:
-
System Architecture Diagram
- High-level components and their relationships
- External systems and services
- Data flow between components
-
Deployment Architecture
- Hosting infrastructure (cloud platform, containers, etc.)
- Service relationships
- Network and database layers
-
File Structure Diagram
- Directory hierarchy showing major components
- Key files and their purposes
- Organization by feature or layer
-
Data Flow Diagram
- How data moves through the system
- API endpoints and their interactions
- Database access patterns
Example ASCII diagram structure:
┌─────────────────────────────────────────────────┐
│ Client (React) │
├─────────────────────────────────────────────────┤
│ - Components │
│ - Pages │
│ - State Management │
└────────────────┬────────────────────────────────┘
│ HTTP/WebSocket
┌────────────────▼────────────────────────────────┐
│ Backend Server (Node.js) │
├─────────────────────────────────────────────────┤
│ - API Routes │
│ - Authentication │
│ - Business Logic │
└────────────────┬────────────────────────────────┘
│
┌────────────────▼────────────────────────────────┐
│ Database & External APIs │
├─────────────────────────────────────────────────┤
│ - PostgreSQL / MongoDB │
│ - Third-party Services │
└─────────────────────────────────────────────────┘
Step 4: Component Analysis
For each major component, document:
- Purpose and responsibilities
- Key files and entry points
- External dependencies
- Interactions with other components
- API surface (if applicable)
Document component categories:
- Frontend Components: UI components, pages, layouts
- Backend Services: API endpoints, middleware, handlers
- Business Logic: Core algorithms, processing
- Infrastructure: Configuration, build, deployment
- Testing: Test utilities, test files
- Documentation: READMEs, specs, guides
Step 5: Technology Stack Assessment
Identify and document:
- Programming languages used
- Key frameworks and libraries
- Database systems
- External services and APIs
- Development tools and build systems
- Container/deployment technologies
- Version numbers where significant
Step 6: Hosting and Infrastructure Analysis
Assess the deployment architecture:
- Identify hosting platform (AWS, GCP, Vercel, Cloudflare, etc.)
- Document service configuration
- Environment variables
- Build processes
- Deployment scripts
- Identify infrastructure-as-code files (Terraform, Docker, etc.)
- Document scaling considerations
- Identify external service dependencies
Step 7: Generate Final Documentation
Create a comprehensive architecture document including:
-
Executive Summary
- Project purpose
- High-level architecture overview
- Technology stack
- Hosting platform and deployment
-
Architecture Diagrams (multiple views as described in Step 3)
-
Component Catalog
- List of major components
- Purpose of each
- Key files
- Dependencies
-
File Structure Overview
- Directory layout with purposes
- Important files highlighted
-
Data Flow Explanation
- How requests are processed
- Database interactions
- External API calls
-
Technology Details
- Language versions
- Framework versions
- Key library versions
- Database schema summary (if visible in code)
-
Deployment and Hosting
- Hosting platform details
- Build and deployment process
- Environment configuration
- Scaling considerations
-
Dependencies and Integrations
- List of external services
- API integrations
- Authentication/authorization approach
Common Patterns
For Monolithic Applications
- Single codebase containing frontend, backend, and shared logic
- Clear separation between presentation, business logic, and data layers
- Review package.json/requirements.txt for all dependencies
For Microservices
- Multiple services in separate directories or repositories
- Service communication documented in deployment config
- API contracts between services
- Separate databases per service (typically)
For Full-Stack Web Applications
- Frontend framework (React, Vue, Angular, etc.)
- Backend framework (Node.js/Express, Python/Django, etc.)
- Database (SQL or NoSQL)
- API layer connecting frontend and backend
Edge Cases
Large Codebases:
- Focus on major components first
- Group related files together
- Create summary before diving into details
Polyglot Repositories:
- Separate analysis by language when relevant
- Document language integration points
- Highlight cross-language dependencies
Complex Infrastructure:
- Document infrastructure-as-code separately
- Identify deployment stages (dev, staging, prod)
- Note auto-scaling or load balancing configurations
Output Format
The final architecture analysis should be delivered as:
- A comprehensive Markdown document with embedded ASCII diagrams
- Clear section headers and navigation
- Links between related sections
- Visual hierarchy showing component relationships
- Concise but complete descriptions
Tools and Resources
The agent may use:
- Git commands to explore repository structure
- File reading tools to examine source code
- Text parsing to extract key information
- ASCII art libraries for diagram generation
Example Use Case
User Request: "Analyze the architecture of the user-management microservice in our platform"
Agent Process:
- Clones the user-management repository
- Maps the directory structure (controllers, models, tests, config)
- Creates ASCII diagrams showing:
- Service components (auth handler, user DB access, role manager)
- Data flow (API request → controller → service → database)
- Deployment (Docker container → Kubernetes → PostgreSQL)
- Documents all dependencies and integrations
- Provides complete architecture documentation
Success Criteria
The analysis is complete when:
- ✅ Repository successfully cloned and analyzed
- ✅ All major components identified
- ✅ Multiple ASCII diagrams created showing different views
- ✅ File structure documented and explained
- ✅ Technology stack clearly identified
- ✅ Hosting/deployment architecture understood
- ✅ Data flow between components visible
- ✅ Comprehensive documentation generated
