Codebase Analysis

Codebase Analysis Skill

Overview

This skill provides techniques for extracting business requirements, domain knowledge, and technical specifications from existing codebases.

Analysis Objectives

When analyzing a codebase, seek to understand: 1. Domain Model: Core entities and their relationships 2. Business Rules: Validation, calculations, workflows 3. Integrations: External systems and data flows 4. User Capabilities: What users can do in the system 5. Technical Constraints: Architecture patterns and limitations

Analysis Process

Phase 1: Structure Discovery

1. Map project structure and organization 2. Identify main components and layers 3. Locate configuration and entry points 4. Understand build and deployment setup

Phase 2: Domain Model Extraction

1. Find entity/model definitions 2. Map relationships between entities 3. Identify domain vocabulary (ubiquitous language) 4. Document data types and constraints

Phase 3: Business Logic Identification

1. Locate service/business logic layers 2. Extract validation rules 3. Document calculations and formulas 4. Map state machines and workflows

Phase 4: Integration Mapping

1. Find API endpoints and contracts 2. Identify external service calls 3. Map data flows in/out of system 4. Document authentication patterns

Phase 5: Capability Documentation

1. List user-facing features 2. Map permissions and access control 3. Document user workflows 4. Identify edge cases and error handling

Code Pattern Recognition

Entity/Model Identification

Look for these patterns:

// C# Entity
public class Order { ... }

// Java Entity
@Entity
public class Order { ... }

// TypeScript Interface
interface Order { ... }

// Database Schema
CREATE TABLE orders ( ... )

Business Rule Indicators

Watch for these keywords and patterns:

• Validation: Validate, Check, Ensure, Must, Should
• Calculations: Calculate, Compute, Total, Sum
• Conditions: If, When, Unless, Only
• Constraints: Max, Min, Required, Limit

Service Layer Patterns

Identify business logic in:

// Service classes
public class OrderService { ... }

// Use cases / Application services
public class CreateOrderUseCase { ... }

// Command/Query handlers
public class CreateOrderHandler { ... }

API Endpoint Patterns

Look for:

// REST Controllers
[Route("api/orders")]
[HttpPost]
public async Task<Order> Create(...)

// Express routes
app.post('/api/orders', ...)

// GraphQL resolvers
Mutation: { createOrder: ... }

Analysis Heuristics

Finding Domain Models

1. Search for class, interface, type definitions 2. Look in folders named: Models, Entities, Domain 3. Check database migrations and schema files 4. Review ORM configurations

Finding Business Rules

1. Search for validation attributes/decorators 2. Look for throw statements (business exceptions) 3. Find conditional logic in services 4. Check for rule engines or policy patterns

Finding Integrations

1. Search for HTTP client usage 2. Look for message queue producers/consumers 3. Find database connection configurations 4. Check for external SDK imports

Finding User Capabilities

1. Review API endpoints and their permissions 2. Check UI components and forms 3. Look at authorization/role definitions 4. Review menu structures and navigation

Output Artifacts

Domain Model Documentation

## Entity: Order

### Attributes
| Name | Type | Description | Constraints |
|------|------|-------------|-------------|
| id | UUID | Unique identifier | Required |
| status | Enum | Order status | Required |
| total | Decimal | Order total | >= 0 |

### Relationships
- Order has many OrderItems (1:N)
- Order belongs to Customer (N:1)

### Business Rules
- Order total must equal sum of item totals
- Status can only transition: Draft -> Submitted -> Approved -> Completed

Business Rule Documentation

## Rule: Order Validation

### Description
Orders must meet these criteria before submission

### Conditions
1. Order must have at least one item
2. All items must have valid product references
3. Customer must have valid payment method
4. Total must be greater than $0

### Implementation
- File: src/Services/OrderService.cs
- Method: ValidateForSubmission()
- Line: 145-180

Integration Documentation

## Integration: Payment Gateway

### Type
REST API (Synchronous)

### Endpoint
POST https://api.payments.com/v1/charges

### Data Flow
- Input: Order total, Customer payment token
- Output: Transaction ID, Status

### Error Handling
- Timeout: Retry 3 times with exponential backoff
- Failure: Mark order as payment pending, notify support

### Implementation
- File: src/Integrations/PaymentGateway.cs

Code Search Patterns

Finding Entities (by language)

# C# / .NET
grep -r "public class.*Entity" --include="*.cs"
grep -r "\[Table\(" --include="*.cs"

# Java
grep -r "@Entity" --include="*.java"

# TypeScript
grep -r "interface.*{" --include="*.ts"

Finding Validation Rules

# C# Attributes
grep -r "\[Required\]|\[Range\]|\[StringLength\]" --include="*.cs"

# Java Annotations
grep -r "@NotNull|@Size|@Valid" --include="*.java"

# Custom validation
grep -r "Validate|throw.*Exception" --include="*.cs"

Finding API Endpoints

# .NET Controllers
grep -r "\[Http.*\]|\[Route\(" --include="*.cs"

# Express.js
grep -r "app\.(get|post|put|delete)\(" --include="*.js"

Reverse Engineering Tips

Start With Entry Points

1. Find main() or startup configuration 2. Follow dependency injection setup 3. Trace from API controllers to services to data

Follow the Data

1. Start with database schema or entities 2. Trace how data flows through system 3. Map CRUD operations for each entity

Look for Tests

1. Unit tests reveal expected behavior 2. Integration tests show workflows 3. Test data shows valid/invalid scenarios

Check Documentation

1. Look for README files 2. Check API documentation (Swagger/OpenAPI) 3. Review code comments and XML docs

Questions to Answer

After analysis, you should be able to answer:

1. What entities exist and how do they relate? 2. What can users do in this system? 3. What business rules govern behavior? 4. What external systems does this integrate with? 5. What are the key workflows? 6. What constraints exist (technical and business)? 7. What data does the system manage? 8. Who has access to what?

See patterns.md for common architectural patterns to identify.

Common Architectural Patterns to Identify

Architectural Patterns

Layered Architecture

Presentation Layer (UI/API)
    ↓
Application Layer (Services/Use Cases)
    ↓
Domain Layer (Entities/Business Logic)
    ↓
Infrastructure Layer (Database/External Services)

Indicators:

• Folder structure: Controllers, Services, Domain, Infrastructure
• Clear separation of concerns
• Dependencies flow downward

Business Analysis Implications:

• Business logic concentrated in Domain/Application layers
• Validation rules often in Domain layer
• Integration points in Infrastructure layer

Clean Architecture / Hexagonal

        External World
             ↓
    [Adapters/Controllers]
             ↓
      [Use Cases/Services]
             ↓
        [Domain Core]

Indicators:

• Ports and Adapters folders
• Interface-based design
• Domain has no external dependencies

Business Analysis Implications:

• Use cases represent discrete business capabilities
• Domain models are pure business logic
• Easy to trace requirements to use cases

Microservices

[Service A] ←→ [Message Broker] ←→ [Service B]
     ↓                                   ↓
[Database A]                       [Database B]

Indicators:

• Multiple deployable units
• API gateway configuration
• Message queue usage
• Service discovery

Business Analysis Implications:

• Each service = bounded context
• Business capabilities split across services
• Integration complexity between services

Event-Driven Architecture

[Producer] → [Event Bus] → [Consumer 1]
                        → [Consumer 2]

Indicators:

• Event classes/DTOs
• Message handlers
• Pub/sub patterns
• Event sourcing

Business Analysis Implications:

• Business events = important domain actions
• Eventual consistency considerations
• Audit trail through event history

CQRS (Command Query Responsibility Segregation)

Commands → [Write Model] → [Event Store]
                              ↓
Queries  → [Read Model]  ← [Projections]

Indicators:

• Separate command and query handlers
• Different models for read/write
• Event handlers updating read models

Business Analysis Implications:

• Commands = user actions that change state
• Queries = information users need
• Clear separation of capabilities

Domain Patterns

Entity

Core business object with identity.

public class Order
{
    public Guid Id { get; }
    public OrderStatus Status { get; private set; }
    public List<OrderItem> Items { get; }
}

Business Analysis Implications:

• Entities = nouns in business vocabulary
• Properties = data attributes to document
• Methods = business operations/rules

Value Object

Immutable object defined by attributes.

public record Money(decimal Amount, string Currency);
public record Address(string Street, string City, string PostalCode);

Business Analysis Implications:

• Value objects = complex attributes
• Immutability = business constraint
• Often represent measurable concepts

Aggregate

Cluster of entities with consistency boundary.

public class Order  // Aggregate Root
{
    private List<OrderItem> _items;

    public void AddItem(Product product, int quantity)
    {
        // Business rules enforced here
    }
}

Business Analysis Implications:

• Aggregate root = transaction boundary
• Internal entities managed through root
• Business rules enforced at aggregate level

Repository

Data access abstraction.

public interface IOrderRepository
{
    Task<Order> GetById(Guid id);
    Task Save(Order order);
}

Business Analysis Implications:

• Shows what data operations exist
• Query methods reveal reporting needs
• Save patterns show persistence requirements

Domain Service

Business logic that doesn't belong to entity.

public class PricingService
{
    public decimal CalculateDiscount(Order order, Customer customer)
    {
        // Cross-entity business logic
    }
}

Business Analysis Implications:

• Complex business rules spanning entities
• Calculations and algorithms
• Policy implementations

Domain Events

Records of something that happened.

public class OrderPlacedEvent
{
    public Guid OrderId { get; }
    public DateTime PlacedAt { get; }
    public decimal Total { get; }
}

Business Analysis Implications:

• Significant business occurrences
• Triggers for side effects
• Audit and compliance relevant

State Patterns

State Machine

Explicit state transitions.

public enum OrderStatus
{
    Draft,
    Submitted,
    Approved,
    Shipped,
    Delivered,
    Cancelled
}

// Valid transitions
// Draft → Submitted
// Submitted → Approved | Cancelled
// Approved → Shipped | Cancelled
// Shipped → Delivered

Business Analysis Implications:

• Document all valid states
• Document valid transitions
• Document conditions for transitions
• Map to business workflows

Workflow / Saga

Long-running business process.

public class OrderFulfillmentSaga
{
    public void Handle(OrderPlaced event)
    {
        // Step 1: Reserve inventory
        // Step 2: Charge payment
        // Step 3: Ship order
    }
}

Business Analysis Implications:

• Multi-step business processes
• Compensation logic (rollback)
• External system coordination

Validation Patterns

Attribute-Based Validation

public class CreateOrderRequest
{
    [Required]
    public Guid CustomerId { get; set; }

    [Range(1, 100)]
    public int Quantity { get; set; }

    [StringLength(500)]
    public string Notes { get; set; }
}

Specification Pattern

public class OrderCanBeSubmittedSpec : ISpecification<Order>
{
    public bool IsSatisfiedBy(Order order)
    {
        return order.Items.Any()
            && order.Total > 0
            && order.Customer.HasValidPayment;
    }
}

Fluent Validation

public class OrderValidator : AbstractValidator<Order>
{
    public OrderValidator()
    {
        RuleFor(o => o.Items).NotEmpty()
            .WithMessage("Order must have items");
        RuleFor(o => o.Total).GreaterThan(0);
    }
}

Business Analysis Implications:

• Each validation rule = business requirement
• Error messages = business language
• Conditions = business constraints

Integration Patterns

API Gateway

Central entry point for services.

Business Analysis Implications:

• Single view of system capabilities
• Cross-cutting concerns (auth, rate limiting)
• API versioning strategy

Message Queue

Asynchronous communication.

Business Analysis Implications:

• Eventual consistency trade-offs
• Retry and dead-letter handling
• Message ordering requirements

Anti-Corruption Layer

Translation between contexts.

public class LegacyOrderAdapter
{
    public Order TranslateFromLegacy(LegacyOrder legacy)
    {
        // Map legacy format to new domain model
    }
}

Business Analysis Implications:

• Integration with legacy systems
• Data transformation rules
• Boundary between contexts

Security Patterns

Role-Based Access Control (RBAC)

[Authorize(Roles = "Admin,Manager")]
public async Task<IActionResult> ApproveOrder(...)

Policy-Based Authorization

[Authorize(Policy = "CanApproveOrders")]

Claims-Based Identity

if (User.HasClaim("Department", "Sales"))
{
    // Allow access to sales data
}

Business Analysis Implications:

• Who can do what (authorization matrix)
• Role definitions and permissions
• Compliance requirements

Pattern Detection Checklist

When analyzing code, look for:

• [ ] Project Structure: What architectural pattern is used?
• [ ] Entities: What are the core domain objects?
• [ ] Value Objects: What complex attributes exist?
• [ ] Aggregates: What are the consistency boundaries?
• [ ] Services: Where is business logic concentrated?
• [ ] Events: What significant things happen?
• [ ] States: What lifecycle states exist?
• [ ] Workflows: What multi-step processes exist?
• [ ] Validations: What business rules are enforced?
• [ ] Integrations: What external systems are involved?
• [ ] Security: Who can do what?