explore-codebase

Explore Codebase Workflow

Purpose

Systematically analyze an existing codebase to understand its architecture, patterns, and conventions, producing documentation for consistent development.

Trigger

• Joining a new project
• Before implementing a significant feature
• Onboarding new team members
• Documenting an undocumented codebase
• Understanding unfamiliar code areas

Outputs

• Architecture documentation
• Coding standards documentation
• Pattern library
• Dependency map

Workflow Steps

Step 1: Project Overview

Gather basic information:

PROJECT METADATA:
├── Name: [Project name]
├── Purpose: [What does it do?]
├── Tech stack: [Languages, frameworks, databases]
├── Repository: [Location, structure]
└── Documentation: [Existing docs location]

Commands to run:
$ ls -la                    # Root structure
$ cat README.md             # Project overview
$ cat package.json          # Node.js dependencies
$ cat requirements.txt      # Python dependencies
$ cat *.csproj             # .NET dependencies

Step 2: Analyze Directory Structure

Map the codebase organization:

ROOT/
├── src/                    [Source code]
│   ├── controllers/        [Request handlers]
│   ├── services/           [Business logic]
│   ├── models/             [Data structures]
│   ├── repositories/       [Data access]
│   └── utils/              [Utilities]
├── tests/                  [Test files]
├── docs/                   [Documentation]
├── scripts/                [Build/deploy scripts]
├── config/                 [Configuration]
└── infrastructure/         [IaC, Docker, etc.]

Identify patterns:
□ Layered architecture?
□ Feature-based organization?
□ Domain-driven structure?
□ Monorepo or single project?

Step 3: Identify Architecture Pattern

Determine the architectural style:

COMMON PATTERNS:
├── Layered/N-Tier
│   └── Presentation → Business → Data
├── Clean Architecture
│   └── Domain → Application → Infrastructure
├── Hexagonal (Ports & Adapters)
│   └── Core with ports, adapters implement
├── Microservices
│   └── Independent deployable services
├── Modular Monolith
│   └── Single deploy, modular internals
└── Event-Driven
    └── Components communicate via events

Document:
- Primary pattern used
- Deviations from pattern
- Boundaries between layers/modules