~/wiki
Récent+ Ajouter

Architecture Audit Methodology

Confiance : medium
architecture-auditcode-reviewtechnical-debtmethodologycursor-idesystematic-analysiscodebase-healthdevelopment-process

Systematic approach to evaluating codebase architecture and technical debt through structured analysis. Demonstrated in the cursor-ide archipel-kombucha-project audit, this methodology provides a comprehensive framework for assessing code quality, architecture patterns, and technical debt accumulation.

Audit Structure

Three-Phase Analysis Framework

  1. Architecture Strengths Assessment

    • Identify well-implemented patterns and decisions
    • Document positive architectural choices
    • Highlight maintainable code structures

  2. Friction Points and Improvements

    • Prioritized list of architectural issues
    • Impact and effort estimation for each issue
    • Focus on patterns that impede development velocity

  3. Technical Debt Inventory

    • Systematic identification of code quality issues
    • Grep-based analysis for common debt indicators
    • Dead code and unused export detection

Analysis Dimensions

Pattern Consistency Assessment

  • Query Centralization: Verify data access patterns are centralized (e.g., queries.ts files vs direct Prisma in components)
  • Server-First Architecture: Validate "use client" usage only when necessary
  • Responsibility Separation: Clear boundaries between pages, components, and lib functions
  • Import Consistency: Standardized import patterns across the codebase

Technical Health Indicators

  • Complexity Analysis: Identify files with high cyclomatic complexity (>500 lines)
  • Error Handling Coverage: Try/catch blocks in API routes, error boundaries implementation
  • Type Safety: TypeScript usage patterns, any-types, assertion patterns

Technical Debt Detection

Systematic grep searches for common debt indicators:

  • TODO|FIXME|XXX|HACK comments
  • @ts-expect-error|@ts-ignore suppressions
  • eslint-disable overrides
  • as any|: any\b type assertions

Audit Depth Levels

Light Audit

  • High-level architecture review
  • Major pattern violations
  • Critical technical debt only

Medium Audit

  • Targeted analysis of key files and patterns
  • Balanced coverage without exhaustive review
  • Focus on development velocity impacts

Deep Audit

  • Line-by-line comprehensive review
  • Full technical debt inventory
  • Performance and security analysis

Implementation Best Practices

Pre-Audit Preparation

  1. Context Files Review: README, architecture docs, schema definitions
  2. Structure Overview: Directory layout and file organization patterns
  3. Technology Stack Assessment: Framework versions, dependencies, hosting

Documentation Standards

  • File References: Point to specific files and line numbers rather than including long code blocks
  • Impact Assessment: Estimate both impact and effort for identified issues
  • Prioritization: Rank issues by development velocity impact

Tooling Integration

Modern IDEs like cursor-ide enable efficient audit workflows through:

  • Multi-file analysis capabilities
  • Grep-based pattern searches
  • Contextual code understanding
  • Structured report generation

Common Architecture Patterns to Evaluate

Next.js Specific Patterns

  • Dynamic Rendering: Consistent use of export const dynamic directives
  • App Router Architecture: Proper page/layout/component organization
  • Server/Client Boundary: Appropriate use of server vs client components

Database and State Management

  • ORM Usage: Consistent query patterns and connection management
  • Data Validation: Input sanitization and type safety
  • Caching Strategy: Appropriate use of caching mechanisms

Security and Monitoring

  • Authentication Implementation: Consistent auth patterns across routes
  • Error Tracking: Proper error boundary and monitoring setup
  • Security Headers: Appropriate security configuration

Limitations and Considerations

Incomplete Audit Risks

As demonstrated in the archipel-kombucha-project case, audit sessions can be interrupted, leading to:

  • Partial analysis that may miss critical issues
  • Incomplete technical debt inventory
  • Unfinished prioritization of improvements

Context Dependency

Architecture audits must consider:

  • Team size and experience level
  • Business requirements and constraints
  • Timeline and resource availability
  • Existing technical decisions and constraints

See also