system-prompts-and-models-of-ai-tools/salesflow-saas/.claude/commands/architecture-review.md

/architecture-review — Architecture Review for Dealix

Review the codebase architecture for consistency, correctness, and maintainability.

Steps

1. Service Boundary Analysis

Scan all services in backend/app/services/:

ls backend/app/services/*.py backend/app/services/*/*.py

For each service, check:

• Single Responsibility: Does it handle one domain concern or is it a grab bag?
• Dependency Direction: Services should depend on abstractions, not on each other circularly
• Size: Flag services over 500 lines as candidates for splitting
• Naming: Service name should match its domain (lead_service.py handles leads, not deals)

2. Import Cycle Detection

Check for circular imports between service modules:

grep -rn "^from app.services" backend/app/services/ --include="*.py"
grep -rn "^import app.services" backend/app/services/ --include="*.py"

Build a dependency graph and flag any cycles. Common problematic patterns:

• Service A imports Service B which imports Service A
• Circular through models: Service -> Model -> Service

3. Model Relationship Audit

Scan all SQLAlchemy models in backend/app/models/:

ls backend/app/models/*.py

For each model verify:

• Has tenant_id column (multi-tenancy requirement)
• Has created_at and updated_at timestamps
• Has id as UUID primary key
• Foreign keys reference correct tables
• Relationship back_populates are bidirectional and consistent
• No orphaned models (defined but never referenced)
• Indexes on tenant_id and frequently-queried columns

4. API Consistency Check

Scan all API routes in backend/app/api/v1/:

ls backend/app/api/v1/*.py

Verify consistency:

• URL patterns: all use kebab-case or snake_case (not mixed)
• HTTP methods: GET for reads, POST for creates, PUT/PATCH for updates, DELETE for deletes
• Response format: all return consistent JSON structure {"data": ..., "message": ...}
• Error responses: use standard error schema with status code and detail
• Authentication: all non-public routes have Depends(get_current_user)
• Pagination: list endpoints support skip and limit parameters
• Tenant scoping: tenant_id extracted from token, not URL

5. Configuration & Environment

Review backend/app/config.py or equivalent:

• All secrets from environment variables
• Sensible defaults for development
• No production values hardcoded
• Settings class uses Pydantic BaseSettings
• Separate configs for test/dev/staging/prod

6. Worker & Task Architecture

Review Celery workers in backend/app/workers/:

ls backend/app/workers/*.py 2>/dev/null

Check:

• Tasks are idempotent (safe to retry)
• Long tasks have timeout configuration
• Tasks log their execution for debugging
• Error handling with proper retry strategy
• No database sessions held across await boundaries

7. Frontend-Backend Contract

Compare API routes with frontend API calls:

grep -rn "fetch\|axios\|api\." frontend/src/ --include="*.ts" --include="*.tsx" | grep -v node_modules | grep -v ".next"

Flag mismatches:

• Frontend calls endpoints that don't exist
• Request/response types don't match
• Missing error handling on frontend for known error responses

8. Integration Points

Review external integrations in backend/app/integrations/:

• WhatsApp adapter: retry logic, rate limiting, error handling
• Email service: template rendering, bounce handling
• Stripe: webhook verification, idempotency keys
• AI providers: fallback chain, timeout handling, cost tracking

9. Architecture Report

Produce a structured report:

Area	Status	Issues Found	Recommendation
Service Boundaries
Import Cycles
Model Integrity
API Consistency
Config Management
Worker Architecture
Frontend Contract
Integrations

Include:

• Top 5 highest-priority architectural improvements
• Technical debt inventory with estimated effort
• Recommended refactoring sequence