faysilalshareef/advisor

Architecture Advisor

Decision Matrix

| Factor | VSA | Clean Arch | DDD | Modular Monolith | Microservices | |--------|-----|-----------|-----|-------------------|---------------| | Team size | 1-3 | 2-8 | 3-10 | 4-15 | 5+ per service | | Domain complexity | Low | Medium | High | High | Very High | | Expected scale | Small-Medium | Medium | Medium-Large | Large | Very Large | | Deployment model | Single | Single | Single | Single | Independent | | Data isolation | Shared DB | Shared DB | Bounded contexts | Schema per module | DB per service | | Time to first feature | Fastest | Fast | Medium | Medium | Slowest | | Long-term maintainability | Good | Very Good | Excellent | Excellent | Excellent (per service) |

Questionnaire

1. Team Size

• 1-3 developers → VSA or Clean Architecture
• 4-10 developers → Clean Architecture, DDD, or Modular Monolith
• 10+ developers → Modular Monolith or Microservices

2. Domain Complexity

• Simple CRUD (few business rules) → VSA
• Moderate (validation, workflows) → Clean Architecture
• Complex (invariants, aggregates, domain events) → DDD
• Multiple bounded contexts → Modular Monolith or Microservices

3. Scalability Needs

• Single deployment sufficient → VSA, Clean Arch, DDD, or Modular Monolith
• Independent scaling per feature → Microservices

4. Data Ownership

• Single database acceptable → VSA, Clean Architecture
• Schema isolation needed → Modular Monolith
• Database per service required → Microservices

5. Deployment Independence

• Deploy everything together → Any monolithic pattern
• Deploy features independently → Microservices

Recommendations

Vertical Slice Architecture (VSA)

Choose when: Small team, simple-to-moderate domain, rapid prototyping.

Features/
├── CreateOrder/
│   ├── CreateOrderCommand.cs
│   ├── CreateOrderHandler.cs
│   └── CreateOrderEndpoint.cs
└── GetOrders/
    ├── GetOrdersQuery.cs
    └── GetOrdersEndpoint.cs

Pros: Minimal boilerplate, feature-focused, easy to understand. Cons: Harder to enforce boundaries as project grows.

Clean Architecture

Choose when: Medium team, moderate complexity, clear layer boundaries needed.

Domain/         → Entities, value objects (zero dependencies)
Application/    → Commands, queries, handlers (depends on Domain)
Infrastructure/ → EF Core, external services (depends on Application)
Api/            → Controllers, endpoints (depends on Application)

Pros: Clear dependency direction, testable, well-documented pattern. Cons: More boilerplate than VSA, can feel heavy for simple features.

Domain-Driven Design (DDD)

Choose when: Complex domain with rich business rules, multiple aggregates.

Domain/
├── Aggregates/Order/
│   ├── Order.cs (aggregate root)
│   ├── OrderItem.cs (entity)
│   └── Money.cs (value object)
├── Events/
│   └── OrderCreated.cs
└── Interfaces/
    └── IOrderRepository.cs

Pros: Models complex business logic accurately, ubiquitous language. Cons: Steeper learning curve, overkill for simple CRUD.

Modular Monolith

Choose when: Large team, multiple feature areas, want independence without microservice overhead.

Modules/
├── Orders/
│   ├── OrdersModule.cs
│   ├── Domain/
│   ├── Application/
│   └── Infrastructure/ (own DbContext, own schema)
└── Customers/
    ├── CustomersModule.cs
    └── ...

Pros: Module independence, single deployment, easier than microservices. Cons: Requires discipline to maintain module boundaries.

Microservices (CQRS + Event Sourcing)

Choose when: Very large scale, independent deployment needed, multiple teams per service.

{Company}.{Domain}.Commands/    → Event-sourced aggregates
{Company}.{Domain}.Queries/     → Read-side projections
{Company}.{Domain}.Processor/   → Event routing
{Company}.Gateways.{Domain}/    → REST API gateway

Pros: Independent scaling/deployment, fault isolation, team autonomy. Cons: Operational complexity, eventual consistency, network overhead.

Migration Paths

VSA → Clean Architecture (add layers when complexity grows)
Clean Architecture → DDD (add aggregates, domain events when needed)
DDD → Modular Monolith (split into modules when team grows)
Modular Monolith → Microservices (extract modules to services when scale demands)

Anti-Patterns

| Anti-Pattern | Correct Approach | |---|---| | Starting with microservices | Start monolithic, extract later | | DDD for simple CRUD | Use VSA or Clean Architecture | | Mixing architecture styles in one project | Pick one, be consistent | | Choosing based on hype | Choose based on team size + domain complexity |

Detect Existing Patterns

# Check for VSA (feature folders)
find . -type d -name "Features" | head -5

# Check for Clean Architecture (layer folders)
ls -d */Domain */Application */Infrastructure */Api 2>/dev/null

# Check for DDD (aggregates)
grep -r "AggregateRoot\|IAggregateRoot" --include="*.cs" | head -3

# Check for Modular Monolith (modules)
find . -type d -name "Modules" | head -3

# Check for Microservices
grep -r "Aggregate<\|Event<\|IEventData" --include="*.cs" | head -3

Adding to Existing Project

1. Detect the current architecture before suggesting changes
2. Never change architecture mid-feature — complete the current work first
3. Recommend migration only when pain points are clearly identified
4. Incremental migration: one module/feature at a time