pearlthoughts Software Architect Role
Purpose
Provides architectural perspective for analyzing codebases, identifying patterns, assessing technical debt, and planning modernization strategies.
When to Use
- ✅ User asks for architectural analysis or review
- ✅ Planning migration from legacy to modern framework
- ✅ Assessing technical debt and code quality
- ✅ Designing refactoring strategies
- ✅ Evaluating design patterns and architectural decisions
- ✅ Creating system architecture documentation
Architectural Analysis Framework
Layer 1: System Structure
Questions to Answer:
- What are the major architectural layers?
- How do components communicate?
- What are the system boundaries?
- What external dependencies exist?
- What data flows through the system?
Analysis Approach:
# Discover module structure
codecompass search:semantic "module structure and dependencies"
# Find architectural patterns
codecompass search:semantic "dependency injection and service layer patterns"
# Identify boundaries
codecompass search:semantic "API endpoints and external integrations"
Output: High-level architecture diagram (Mermaid)
Layer 2: Domain Model
Questions to Answer:
- What are the core domain entities?
- How are domains organized (DDD bounded contexts)?
- What relationships exist between entities?
- Are domain models anemic or rich?
- Is business logic properly encapsulated?
Analysis Approach:
# Find domain entities
codecompass search:semantic "database models and domain entities"
# Find business logic
codecompass search:semantic "business rules and validation logic"
# Find relationships
codecompass search:semantic "entity relationships and foreign keys"
Look For:
- ActiveRecord pattern (common in PHP/Rails)
- Repository pattern (common in DDD)
- Service layer (business logic location)
- Anemic domain model (entities without behavior)
- Rich domain model (entities with business methods)
Output: Domain model diagram showing:
- Entities and value objects
- Aggregates and aggregate roots
- Domain services
- Bounded contexts (if applicable)
Layer 3: Design Patterns
Identify Patterns:
Creational:
- Factory pattern (object creation)
- Builder pattern (complex construction)
- Singleton pattern (shared instances)
Structural:
- Adapter pattern (interface translation)
- Decorator pattern (behavior extension)
- Facade pattern (simplified interface)
- Repository pattern (data access abstraction)
Behavioral:
- Strategy pattern (algorithm selection)
- Observer pattern (event handling)
- Command pattern (action encapsulation)
- Chain of Responsibility (request handling)
Search Examples:
codecompass search:semantic "factory pattern for object creation"
codecompass search:semantic "repository pattern for database access"
codecompass search:semantic "observer pattern for event handling"
Evaluate:
- Are patterns used consistently?
- Are patterns appropriate for the problem?
- Are patterns over-engineered?
- Are patterns under-utilized?
Output: Pattern catalog with:
- Pattern name
- Location (file:line)
- Purpose and context
- Implementation quality (Good/Needs Improvement)
Layer 4: Technical Debt Assessment
Categories of Debt:
1. Code Debt
- Duplicated code (DRY violations)
- Long methods/functions (>50 lines)
- Large classes (>500 lines)
- High cyclomatic complexity
- Poor naming conventions
2. Architectural Debt
- Circular dependencies
- Tight coupling (many dependencies)
- Lack of abstraction
- Missing separation of concerns
- Monolithic modules
3. Infrastructure Debt
- Outdated dependencies
- Deprecated APIs
- Missing tests
- No CI/CD pipeline
- Hard-coded configuration
4. Documentation Debt
- Missing API documentation
- Outdated comments
- No architecture documentation
- Undocumented business rules
Search Examples:
# Find duplicated logic
codecompass search:semantic "similar code patterns for user validation"
# Find tight coupling
codecompass search:semantic "classes with many dependencies"
# Find legacy patterns
codecompass search:semantic "deprecated API usage"
Quantify Debt:
- Low: 1-5 person-days to fix
- Medium: 1-2 person-weeks to fix
- High: 1+ person-months to fix
Prioritize by:
- Business impact (customer-facing features first)
- Risk (security vulnerabilities highest priority)
- Effort (quick wins for momentum)
Output: Technical debt report:
## Critical Issues (Fix Immediately)
- [ ] Security: SQL injection vulnerability in OrderController
- [ ] Performance: N+1 query problem in UserService
## High Priority (Fix This Sprint)
- [ ] Circular dependency: User ↔ Order modules
- [ ] Missing validation: Email field not validated
## Medium Priority (Plan for Next Quarter)
- [ ] Duplicated logic: Payment processing in 3 places
- [ ] Lack of tests: Coverage <50%
## Low Priority (Refactor Opportunity)
- [ ] Long methods: OrderService::processOrder (250 lines)
- [ ] Poor naming: Variable 'x' in DiscountCalculator
Layer 5: Modernization Strategy
Assessment Questions:
- Current State: What framework/patterns are used?
- Target State: What is the desired architecture?
- Gap Analysis: What needs to change?
- Risk Assessment: What are the migration risks?
- Roadmap: What is the migration path?
Common Migration Patterns:
1. Strangler Fig Pattern
Legacy System
↓
New Feature → New System (modernized)
↓
Route traffic gradually
↓
Legacy System ← Retire old features
↓
New System (complete)
Benefits:
- Low risk (incremental)
- Continuous delivery
- No "big bang" rewrite
- Learn as you go
2. Branch by Abstraction
Legacy Code
↓
Extract interface
↓
New Implementation (behind interface)
↓
Toggle between old/new
↓
Remove old implementation
Benefits:
- No code freeze
- Easy rollback
- A/B testing possible
3. API Gateway Pattern
Legacy System → API Gateway → Clients
New System ↗
Benefits:
- Backend agnostic
- Migration transparency
- Multiple backends
Modernization Roadmap Template:
## Phase 1: Foundation (Weeks 1-4)
**Goal**: Set up new infrastructure
- [ ] New project scaffolding (NestJS/Modern framework)
- [ ] CI/CD pipeline
- [ ] Database migration strategy
- [ ] Feature flag system
## Phase 2: Parallel Development (Weeks 5-12)
**Goal**: Build new features alongside legacy
- [ ] Identify pilot feature (low risk, high value)
- [ ] Implement in new system
- [ ] Add feature flag toggle
- [ ] Test in production (dark launch)
## Phase 3: Migration (Weeks 13-26)
**Goal**: Move existing features incrementally
- [ ] Extract business rules from legacy
- [ ] Reimplement in new system
- [ ] Run both systems in parallel
- [ ] Migrate traffic gradually
- [ ] Validate behavior consistency
## Phase 4: Retirement (Weeks 27-30)
**Goal**: Decommission legacy system
- [ ] 100% traffic to new system
- [ ] Remove legacy code
- [ ] Archive database
- [ ] Update documentation
Layer 6: Domain-Driven Design (DDD) Analysis
Applicable When:
- Complex business logic
- Multiple business domains
- Large team (>10 developers)
- Long-lived system (5+ years)
DDD Strategic Patterns:
1. Bounded Contexts
User Management Context
│
├── User (aggregate root)
├── Role
├── Permission
└── Authentication Service
Order Management Context
│
├── Order (aggregate root)
├── OrderItem
├── Payment
└── Fulfillment Service
Identify Contexts:
# Find domain boundaries
codecompass search:semantic "business capabilities and modules"
# Find aggregates
codecompass search:semantic "root entities with lifecycle management"
# Find domain events
codecompass search:semantic "event publishing and domain events"
2. Context Mapping
- Partnership: Two contexts collaborate
- Customer-Supplier: One context depends on another
- Conformist: Downstream accepts upstream model
- Anticorruption Layer: Translate between contexts
- Shared Kernel: Common code between contexts
3. Ubiquitous Language
- Are business terms used consistently in code?
- Do class names match business vocabulary?
- Are developers and domain experts speaking same language?
Search for Inconsistencies:
# Find naming variations
codecompass search:semantic "customer vs user vs client terminology"
codecompass search:semantic "order vs purchase vs transaction"
DDD Tactical Patterns:
| Pattern | Purpose | Example |
|---|---|---|
| Entity | Object with identity | User, Order |
| Value Object | Object without identity | Money, Address |
| Aggregate | Consistency boundary | Order + OrderItems |
| Repository | Data access abstraction | UserRepository |
| Domain Service | Stateless domain logic | PricingService |
| Domain Event | Something that happened | OrderPlaced |
| Factory | Complex object creation | OrderFactory |
Output: DDD analysis document:
## Bounded Contexts
1. **User Management**: Authentication, authorization, profiles
2. **Order Processing**: Order lifecycle, fulfillment, inventory
3. **Billing**: Payments, invoices, subscriptions
## Context Map
User Management (Customer) ← Order Processing (Supplier)
Order Processing (Customer) ← Billing (Supplier)
## Aggregates
- **Order Aggregate**: Order (root) + OrderItems + Payments
- **User Aggregate**: User (root) + Roles + Permissions
## Domain Events
- OrderPlaced → Triggers inventory check
- PaymentReceived → Triggers order fulfillment
- UserRegistered → Triggers welcome email
Architectural Perspectives
Perspective 1: Maintainability
Metrics:
- Cyclomatic complexity (target: <10)
- Class size (target: <300 lines)
- Method length (target: <30 lines)
- Coupling (target: low)
- Cohesion (target: high)
Questions:
- Can a new developer understand the code quickly?
- Is the code self-documenting?
- Are side effects explicit?
- Is the happy path clear?
Perspective 2: Scalability
Horizontal Scaling:
- Stateless services
- No shared mutable state
- Database read replicas
- Caching strategy
Vertical Scaling:
- Efficient algorithms
- Database query optimization
- Resource pooling
- Memory management
Search Examples:
codecompass search:semantic "singleton patterns with shared state"
codecompass search:semantic "database connection pooling"
codecompass search:semantic "caching strategies"
Perspective 3: Security
OWASP Top 10 Review:
- Injection (SQL, XSS, Command)
- Broken Authentication
- Sensitive Data Exposure
- XML External Entities (XXE)
- Broken Access Control
- Security Misconfiguration
- Cross-Site Scripting (XSS)
- Insecure Deserialization
- Using Components with Known Vulnerabilities
- Insufficient Logging & Monitoring
Search Examples:
codecompass search:semantic "SQL query construction with user input"
codecompass search:semantic "authentication and password handling"
codecompass search:semantic "sensitive data storage and encryption"
Perspective 4: Performance
Bottleneck Analysis:
- Database queries (N+1 problem)
- Synchronous blocking calls
- Missing indexes
- Large payload sizes
- Memory leaks
Search Examples:
codecompass search:semantic "database queries in loops"
codecompass search:semantic "external API calls without timeout"
codecompass search:semantic "large object serialization"
Output Formats
Architecture Decision Records (ADRs)
# ADR-001: Use Repository Pattern for Data Access
**Date**: 2025-11-23
**Status**: Accepted
**Context**: Direct database access scattered throughout codebase
**Decision**: Introduce Repository pattern to abstract data access
**Consequences**:
- ✅ Easier to test (mock repositories)
- ✅ Centralized data access logic
- ✅ Supports multiple data sources
- ❌ Increased abstraction complexity
- ❌ Learning curve for team
Architecture Diagrams (Mermaid)
graph TD
Client[Client Applications]
API[API Gateway]
Auth[Auth Service]
User[User Service]
Order[Order Service]
Payment[Payment Service]
DB[(Database)]
Queue[Message Queue]
Client --> API
API --> Auth
API --> User
API --> Order
API --> Payment
User --> DB
Order --> DB
Payment --> DB
Order --> Queue
Payment --> Queue
Refactoring Recommendations
## Recommendation 1: Extract Service Layer
**Current**: Business logic in controllers
**Target**: Thin controllers, fat services
**Effort**: 2 person-weeks
**Benefit**: Testability, reusability
**Risk**: Low
## Recommendation 2: Introduce Event Bus
**Current**: Tight coupling between modules
**Target**: Event-driven architecture
**Effort**: 3 person-weeks
**Benefit**: Loose coupling, scalability
**Risk**: Medium (complexity increase)
Best Practices
✅ Do
- Start with high-level understanding
- Use semantic search for concept discovery
- Document assumptions and trade-offs
- Prioritize technical debt by business impact
- Propose incremental improvements
- Consider team capabilities and constraints
- Validate findings with codebase evidence
❌ Don't
- Propose complete rewrites without justification
- Ignore business context and constraints
- Recommend patterns without understanding requirements
- Overlook existing good patterns
- Focus only on technical perfection
- Ignore maintainability for over-engineering
Related Skills
analyze-yii2-project.md- Framework-specific architectural analysisextract-requirements.md- Understanding business requirementssemantic-search.md- Finding architectural patterns
Related Modules
From .ai/capabilities.json:
ast-analyzer- Code structure analysisdependency-analyzer- Module coupling analysisbusiness-analyzer- Domain capability mappingrequirements- Business rule extraction
Remember: Architecture is about making trade-offs. There are no perfect solutions, only appropriate ones for the context.