// Designs software architecture and selects appropriate patterns for projects. Use when designing systems, choosing architecture patterns, structuring projects, making technical decisions, or when asked about microservices, monoliths, or architectural approaches.
Convex backend development guidelines. Use when writing Convex functions, schemas, queries, mutations, actions, or any backend code in a Convex project. Triggers on tasks involving Convex database operations, real-time subscriptions, file storage, or serverless functions.
Implements error handling patterns, structured logging, retry strategies, circuit breakers, and graceful degradation. Use when designing error handling, setting up logging, implementing retries, adding error tracking, or when asked about error boundaries, log aggregation, alerting, or resilience patterns.
Implements authentication, authorization, encryption, secrets management, and security hardening patterns. Use when designing auth flows, managing secrets, configuring CORS, implementing rate limiting, or when asked about JWT, OAuth, password hashing, API keys, RBAC, or security best practices.
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
Analyzes codebases to understand structure, tech stack, patterns, and conventions. Use when onboarding to a new project, exploring unfamiliar code, or when asked "how does this work?" or "what's the architecture?"
Designs database schemas, indexing strategies, query optimization, and migration patterns for SQL and NoSQL databases. Use when designing tables, optimizing queries, fixing N+1 problems, planning migrations, or when asked about database performance, normalization, ORMs, or data modeling.
| name | designing-architecture |
| description | Designs software architecture and selects appropriate patterns for projects. Use when designing systems, choosing architecture patterns, structuring projects, making technical decisions, or when asked about microservices, monoliths, or architectural approaches. |
Copy this checklist and track progress:
Architecture Design Progress:
- [ ] Step 1: Understand requirements and constraints
- [ ] Step 2: Assess project size and team capabilities
- [ ] Step 3: Select architecture pattern
- [ ] Step 4: Define directory structure
- [ ] Step 5: Document trade-offs and decision
- [ ] Step 6: Validate against decision framework
| Size | Recommended Pattern |
|---|---|
| Small (<10K LOC) | Simple MVC/Layered |
| Medium (10K-100K) | Clean Architecture |
| Large (>100K) | Modular Monolith or Microservices |
| Team | Recommended |
|---|---|
| 1-3 devs | Monolith with clear modules |
| 4-10 devs | Modular Monolith |
| 10+ devs | Microservices (if justified) |
┌─────────────────────────────┐
│ Presentation │ ← UI, API Controllers
├─────────────────────────────┤
│ Application │ ← Use Cases, Services
├─────────────────────────────┤
│ Domain │ ← Business Logic, Entities
├─────────────────────────────┤
│ Infrastructure │ ← Database, External APIs
└─────────────────────────────┘
Use when: Simple CRUD apps, small teams, quick prototypes
┌─────────────────────────────────────┐
│ Frameworks & Drivers │
│ ┌─────────────────────────────┐ │
│ │ Interface Adapters │ │
│ │ ┌─────────────────────┐ │ │
│ │ │ Application │ │ │
│ │ │ ┌─────────────┐ │ │ │
│ │ │ │ Domain │ │ │ │
│ │ │ └─────────────┘ │ │ │
│ │ └─────────────────────┘ │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────────┘
Use when: Complex business logic, long-lived projects, testability is key
┌──────────┐
│ HTTP API │
└────┬─────┘
│ Port
┌────────▼────────┐
│ │
│ Application │
│ Core │
│ │
└────────┬────────┘
│ Port
┌────▼─────┐
│ Database │
└──────────┘
Use when: Need to swap external dependencies, multiple entry points
Producer → Event Bus → Consumer
│
├─→ Consumer
│
└─→ Consumer
Use when: Loose coupling needed, async processing, scalability
┌─────────────┐ ┌─────────────┐
│ Commands │ │ Queries │
│ (Write) │ │ (Read) │
└──────┬──────┘ └──────┬──────┘
│ │
▼ ▼
Write Model Read Model
│ │
└────────┬───────────┘
▼
Event Store
Use when: Different read/write scaling, complex domains, event sourcing
src/
├── features/
│ ├── users/
│ │ ├── api/
│ │ ├── components/
│ │ ├── hooks/
│ │ ├── services/
│ │ └── types/
│ └── orders/
│ ├── api/
│ ├── components/
│ └── ...
├── shared/
│ ├── components/
│ ├── hooks/
│ └── utils/
└── app/
└── ...
src/
├── controllers/
├── services/
├── models/
├── repositories/
└── utils/
When making architectural decisions, evaluate against these criteria:
Use this template to document architectural decisions:
## Decision: [What we're deciding]
### Context
[Why this decision is needed now]
### Options Considered
1. Option A: [Description]
2. Option B: [Description]
### Trade-offs
| Criteria | Option A | Option B |
| ---------------- | -------- | -------- |
| Complexity | Low | High |
| Scalability | Medium | High |
| Team familiarity | High | Low |
### Decision
We chose [Option] because [reasoning].
### Consequences
- [What this enables]
- [What this constrains]
After selecting an architecture, validate against:
Architecture Validation:
- [ ] Matches project size and complexity
- [ ] Aligns with team skills and experience
- [ ] Supports current requirements
- [ ] Allows for anticipated growth
- [ ] Dependencies flow inward (core has no external deps)
- [ ] Clear boundaries between modules/layers
- [ ] Testing strategy is feasible
- [ ] Trade-offs are documented
If validation fails, reconsider the pattern selection or adjust the implementation approach.