Mnthe Hardworker Marketplace Architecture Review

Architecture Review

Architecture and design pattern validation for ultrawork planning and verification phases.

What This Skill Provides

Structured approach to evaluating:

• Component boundaries and separation of concerns
• Modularity and coupling
• Design patterns and architectural principles
• Scalability and maintainability
• API design and interfaces

When to Use This Skill

During PLANNING phase:

• Reviewing planner's task decomposition
• Validating design documents
• Assessing technical approach
• Identifying architectural risks

During VERIFICATION phase:

• Ensuring implementation matches design
• Checking component boundaries
• Validating separation of concerns
• Reviewing integration points

Core Principles

1. Separation of Concerns (SoC)

Checklist:

[ ] Business logic separated from presentation
[ ] Data access layer isolated
[ ] Authentication/authorization in dedicated modules
[ ] Configuration separate from code
[ ] API routes separate from business logic
[ ] Validation logic reusable across layers
[ ] Error handling centralized
[ ] Logging abstracted

Red Flags:

• Business logic in React components
• Database queries in route handlers
• Authentication mixed with business logic
• Configuration hardcoded in multiple files

Examples:

// ❌ Bad: Mixed concerns
app.post('/api/users', async (req, res) => {
  // Authentication + validation + business logic + DB access in one place
  if (!req.headers.authorization) return res.status(401).json({ error: 'Unauthorized' });
  if (!req.body.email) return res.status(400).json({ error: 'Email required' });
  const user = await db.users.create(req.body);
  res.json(user);
});

// ✅ Good: Separated concerns
app.post('/api/users',
  authenticate,           // Auth middleware
  validateCreateUser,     // Validation middleware
  createUserHandler       // Route handler delegates to service
);

async function createUserHandler(req, res) {
  const user = await userService.createUser(req.body); // Business logic in service
  res.json(user);
}

2. Component Boundaries

Checklist:

[ ] Components have clear, single responsibilities
[ ] Component interfaces are well-defined
[ ] Dependencies flow in one direction (no circular deps)
[ ] Components are independently testable
[ ] Public APIs are minimal (principle of least exposure)
[ ] Internal implementation details are hidden
[ ] Components can be replaced without breaking others

Red Flags:

• Circular dependencies (A imports B, B imports A)
• God objects (classes with 10+ responsibilities)
• Tight coupling (changes in A always require changes in B)
• Leaky abstractions (internal details exposed)

Dependency Flow:

Presentation → Business Logic → Data Access → Database
     ↓              ↓                ↓
   UI Layer    Service Layer    Repository Layer

NEVER: Data Access → Presentation (wrong direction!)

3. Modularity and Coupling

Checklist:

[ ] Modules are cohesive (related functionality grouped)
[ ] Low coupling between modules
[ ] Shared code in libraries/utilities
[ ] Feature folders group related files
[ ] Module exports are explicit and minimal
[ ] Dependencies are injected (not hardcoded)
[ ] Configuration passed from outside

Cohesion vs Coupling:

Examples:

// ❌ Bad: High coupling, hardcoded dependencies
class UserService {
  constructor() {
    this.db = new PostgresDB(); // Hardcoded!
    this.logger = console;       // Hardcoded!
  }
}

// ✅ Good: Low coupling, dependency injection
class UserService {
  constructor(database, logger) {
    this.db = database;
    this.logger = logger;
  }
}

// Usage: dependencies injected
const userService = new UserService(
  new PostgresDB(config.db),
  new Logger(config.logging)
);

4. Design Patterns

Checklist:

[ ] Patterns used appropriately (not overengineered)
[ ] Consistent patterns across codebase
[ ] Standard patterns preferred over custom solutions
[ ] Patterns documented in code

Common Patterns:

Red Flags:

• Patterns used incorrectly
• Over-abstraction (patterns for simple problems)
• Mixing patterns inconsistently
• Custom patterns when standard ones exist

5. API Design

Checklist:

[ ] RESTful conventions followed (GET/POST/PUT/DELETE)
[ ] Consistent URL structure
[ ] Proper HTTP status codes
[ ] Versioning strategy defined
[ ] Request/response schemas documented
[ ] Error responses are consistent
[ ] Pagination for collections
[ ] Filtering and sorting supported where needed

REST Conventions:

Examples:

// ❌ Bad: Inconsistent, non-RESTful
POST /getUser
POST /deleteUser
GET /updateUser?id=123&name=John

// ✅ Good: RESTful, consistent
GET    /api/users/:id      (retrieve)
POST   /api/users          (create)
PUT    /api/users/:id      (update)
DELETE /api/users/:id      (delete)

6. Scalability Considerations

Checklist:

[ ] Stateless design (no server-side state)
[ ] Database queries optimized (indexes, joins)
[ ] Caching strategy defined
[ ] Async operations for I/O
[ ] Rate limiting implemented
[ ] Pagination on large datasets
[ ] Background jobs for heavy processing
[ ] CDN for static assets

Red Flags:

• Storing state in memory (server-side sessions)
• Synchronous blocking operations
• No caching for expensive operations
• Loading entire tables
• Missing indexes on query columns

Layer Architecture Patterns

3-Tier Architecture

┌─────────────────────┐
│  Presentation Layer │  (UI, API routes)
└──────────┬──────────┘
           │
┌──────────▼──────────┐
│   Business Layer    │  (Services, logic)
└──────────┬──────────┘
           │
┌──────────▼──────────┐
│    Data Layer       │  (Repositories, DB)
└─────────────────────┘

Rules:

• Upper layers can call lower layers
• Lower layers CANNOT call upper layers
• Layers communicate via interfaces

Feature-Based Structure

src/
├── features/
│   ├── auth/
│   │   ├── auth.service.ts
│   │   ├── auth.controller.ts
│   │   ├── auth.repository.ts
│   │   └── auth.test.ts
│   ├── users/
│   │   ├── user.service.ts
│   │   ├── user.controller.ts
│   │   └── user.repository.ts
├── shared/
│   ├── utils/
│   ├── middleware/
│   └── types/

Benefits:

• Related code together
• Easy to find files
• Scalable structure
• Clear ownership

Review Process

Step 1: High-Level Assessment

Answer:

• What is the overall architecture pattern?
• Are responsibilities clearly separated?
• Is the dependency flow correct?
• Can components be tested independently?

Step 2: Component Analysis

For each component:

• What is its single responsibility?
• What are its dependencies?
• Is its interface minimal and clear?
• Is it properly abstracted?

Step 3: Integration Review

Check:

• How do components communicate?
• Are interfaces well-defined?
• Is error handling consistent?
• Are transactions handled correctly?

Step 4: Design Document Review

Verify:

• Design rationale is documented
• Trade-offs are explained
• Alternative approaches considered
• Scalability addressed
• Security considered

Architecture Smells

Design Principles (SOLID)

S - Single Responsibility Principle

Each class/module has one reason to change.

// ❌ Bad: Multiple responsibilities
class UserManager {
  createUser() { /* ... */ }
  sendEmail() { /* ... */ }
  logActivity() { /* ... */ }
}

// ✅ Good: Single responsibility
class UserService {
  createUser() { /* ... */ }
}
class EmailService {
  sendEmail() { /* ... */ }
}

O - Open/Closed Principle

Open for extension, closed for modification.

// ❌ Bad: Must modify for new types
function calculateShipping(order) {
  if (order.type === 'standard') return 5;
  if (order.type === 'express') return 15;
  // Must modify function for new types
}

// ✅ Good: Extend via strategy pattern
class StandardShipping {
  calculate() { return 5; }
}
class ExpressShipping {
  calculate() { return 15; }
}

L - Liskov Substitution Principle

Subtypes must be substitutable for base types.

I - Interface Segregation Principle

Many small interfaces better than one large interface.

D - Dependency Inversion Principle

Depend on abstractions, not concrete implementations.

Evidence Collection

When reviewing architecture:

# Add architecture assessment to evidence
bun "{SCRIPTS_PATH}/task-update.js" --session ${CLAUDE_SESSION_ID} --id verify \
  --add-evidence "Architecture Review: PASS" \
  --add-evidence "- Clear separation of concerns" \
  --add-evidence "- Proper component boundaries" \
  --add-evidence "- No circular dependencies" \
  --add-evidence "- RESTful API design"

Common Issues and Fixes

Integration with Ultrawork

During PLANNING Phase

# Review design document
Read("$SESSION_DIR/docs/plans/design.md")

# Check task decomposition aligns with architecture
bun "{SCRIPTS_PATH}/task-list.js" --session ${CLAUDE_SESSION_ID}

# Validate component boundaries in plan

During VERIFICATION Phase

# Check implementation matches design
git diff

# Verify component boundaries maintained
# Check for circular dependencies
# Validate layer separation

Quick Reference

Must-have architecture standards:

• Clear layer separation (presentation/business/data)
• Single responsibility per component
• Dependency injection for flexibility
• RESTful API conventions
• No circular dependencies

Red flags:

• Business logic in presentation layer
• Circular dependencies
• God objects/classes
• Tight coupling
• Inconsistent patterns

Converted and distributed by TomeVault — claim your Tome and manage your conversions.