Codebase Analysis Patterns

A systematic framework for analyzing codebases across 14 technical areas. This skill provides the analysis structure and signals to look for when examining a repository.

Technical Areas

1. System Overview

Purpose: Understand the project at a high level.

Signals to extract:

• •Project name (from package.json, pyproject.toml, go.mod, etc.)
• •Project type: monolith, microservices, fullstack, library, CLI tool
• •Purpose/domain: e-commerce, SaaS, developer tool, etc.
• •Maturity level: prototype, MVP, production, legacy

Detection patterns:

# Check for project metadata
package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml
README.md (first paragraph often describes purpose)

2. Technology Stack

Purpose: Identify languages, frameworks, and tools.

Signals to extract:

• •Primary languages (by file extension distribution)
• •Frameworks (React, Vue, Django, FastAPI, Spring, etc.)
• •Databases (PostgreSQL, MongoDB, Redis, etc.)
• •Cloud providers (AWS, GCP, Azure indicators)
• •API styles (REST, GraphQL, gRPC, WebSocket)

Detection patterns:

# Language detection
*.ts, *.tsx → TypeScript
*.py → Python
*.go → Go
*.rs → Rust
*.java → Java

# Framework detection
next.config.* → Next.js
angular.json → Angular
settings.py + urls.py → Django
main.py + FastAPI import → FastAPI

3. Architecture Pattern

Purpose: Identify the structural design.

Signals to extract:

• •Type: layered, hexagonal, microservices, serverless, event-driven
• •Layers: presentation, business logic, data access, infrastructure
• •Communication: sync HTTP, async messaging, event bus
• •Design patterns: repository, factory, observer, CQRS, etc.

Detection patterns:

# Layered architecture signals
/controllers or /handlers → presentation layer
/services or /usecases → business logic layer
/repositories or /dal → data access layer

# Microservices signals
Multiple Dockerfiles or docker-compose services
/services/* with independent package files
API gateway configuration

4. Frontend Structure

Purpose: Understand client-side organization.

Signals to extract:

• •Framework: React, Vue, Angular, Svelte, etc.
• •State management: Redux, Zustand, Vuex, NgRx, etc.
• •Build tool: Vite, Webpack, esbuild, Turbopack
• •Entry point: index.html, main.tsx, App.vue
• •Component organization: atomic, feature-based, page-based

Detection patterns:

# React patterns
/components, /hooks, /contexts
useState, useEffect, useContext imports

# State management
/store, /redux, /state directories
createStore, configureStore, create (zustand)

5. Backend Structure

Purpose: Understand server-side organization.

Signals to extract:

• •Framework: Express, FastAPI, Django, Spring Boot, etc.
• •API style: REST, GraphQL, gRPC
• •Module decomposition: by feature, by layer, by domain
• •Entry points: main.py, index.ts, Application.java

Detection patterns:

# API route patterns
/routes, /api, /endpoints directories
@app.route, @router.get, @GetMapping decorators

# Module patterns
/modules/*/  → feature-based
/domain/*/   → domain-driven

6. Module/Service Inventory

Purpose: Catalog major components.

Signals to extract:

• •Module/service names
• •Types: API, worker, scheduler, gateway
• •Paths and entry points
• •Dependencies (internal and external)
• •Public interfaces (exported functions, API endpoints)

Output format:

7. Data Stores

Purpose: Identify persistence mechanisms.

Signals to extract:

• •Databases: PostgreSQL, MySQL, MongoDB, DynamoDB
• •Caches: Redis, Memcached
• •Search: Elasticsearch, Algolia
• •File storage: S3, GCS, local filesystem
• •Purpose of each store

Detection patterns:

# Database configuration
DATABASE_URL, MONGO_URI environment variables
/migrations, /prisma, /drizzle directories
*.sql files, schema definitions

# Cache patterns
REDIS_URL, redis.createClient()
@Cacheable annotations

8. External Integrations

Purpose: Map third-party connections.

Signals to extract:

• •Service names (Stripe, Twilio, SendGrid, etc.)
• •Integration methods (SDK, REST API, webhook)
• •Authentication (API keys, OAuth, certificates)
• •Failure handling (retries, circuit breakers, fallbacks)

Detection patterns:

# SDK imports
import stripe, from '@stripe/stripe-js'
import twilio, from 'twilio'

# API client patterns
/integrations, /clients, /external directories
fetch('https://api.stripe.com/...')

9. Key Workflows

Purpose: Trace critical user journeys.

Signals to extract:

• •Workflow names (checkout, onboarding, report generation)
• •Actors (user, admin, system, scheduler)
• •Steps and sequence
• •Services involved
• •Error scenarios and handling

Detection patterns:

# Workflow indicators
/workflows, /flows, /sagas directories
State machines, step functions
Transaction boundaries

10. Deployment Architecture

Purpose: Understand infrastructure and deployment.

Signals to extract:

• •Containerization: Docker, Podman
• •Orchestration: Kubernetes, ECS, Docker Compose
• •IaC: Terraform, CloudFormation, Pulumi
• •Environments: dev, staging, production
• •CI/CD: GitHub Actions, GitLab CI, Jenkins

Detection patterns:

# Container configuration
Dockerfile, docker-compose.yml
.dockerignore

# IaC patterns
/terraform, /infrastructure, /infra directories
*.tf, *.yaml (CloudFormation), Pulumi.*

# CI/CD
.github/workflows/, .gitlab-ci.yml, Jenkinsfile

11. Testing & CI/CD

Purpose: Understand quality assurance approach.

Signals to extract:

• •Test structure: unit, integration, e2e
• •Test frameworks: Jest, Pytest, JUnit, Cypress
• •Coverage targets and tools
• •Linting and formatting: ESLint, Prettier, Black, Ruff
• •Deployment process and stages

Detection patterns:

# Test directories
/tests, /__tests__, /spec, /e2e
*.test.ts, *.spec.py, *_test.go

# CI configuration
.github/workflows/*.yml
test, lint, build, deploy stages

12. Security Architecture

Purpose: Identify security mechanisms.

Signals to extract:

• •Authentication: JWT, OAuth2, SAML, API keys
• •Authorization: RBAC, ABAC, policies
• •Secrets management: environment variables, Vault, AWS Secrets
• •Encryption: at-rest, in-transit, field-level
• •Security headers and middleware

Detection patterns:

# Auth patterns
/auth, /security directories
passport, next-auth, @nestjs/passport imports
JWT verification middleware

# Secrets
.env files (check .gitignore)
secrets/, vault configuration

13. File Structure & Entry Points

Purpose: Map the repository organization.

Signals to extract:

• •Top-level directory purposes
• •Critical entry points (main files, CLI entry)
• •Configuration files and their roles
• •Generated vs source directories

Output format:

/
├── src/           → Source code
├── tests/         → Test files
├── docs/          → Documentation
├── scripts/       → Build/deploy scripts
├── config/        → Configuration files
└── dist/          → Build output (generated)

14. Other Technical Areas

Purpose: Capture anything not covered above.

Potential areas:

• •Observability: logging, metrics, tracing
• •Feature flags and A/B testing
• •Internationalization (i18n)
• •Accessibility (a11y)
• •Performance optimization patterns
• •Background job processing
• •Real-time features (WebSocket, SSE)

Analysis Process

1. •Scan project structure — Glob for directories and key files
2. •Detect technology — Check manifest files (package.json, etc.)
3. •Identify entry points — Find main files for each component
4. •Map dependencies — Internal and external dependencies
5. •Extract architecture — Recognize patterns from code structure
6. •Document modules/services — Create inventory of major components
7. •Discover integrations — Find external API calls and webhooks
8. •Map workflows — Trace major user journeys through code
9. •Validate completeness — Ensure all 14 areas are examined

Completeness Scoring

Version: 1.0 Last Updated: 2026-01-22