AGENT SKILL
backend-architecture
Guides backend and API architecture — service layers, REST/GraphQL design, databases, caching, async jobs, and scalability trade-offs. Use when designing APIs, microservices vs monolith boundaries, data models, authentication flows, or infrastructure-facing code.
- License 许可
- MIT
- 最近更新
- 2026-09-15
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- backend-architecture
- paths
- [ "**/api/**", "**/services/**", "**/server/**", "**/*route*.ts", "**/*handler*.ts" ]
- description
- Guides backend and API architecture — service layers, REST/GraphQL design, databases, caching, async jobs, and scalability trade-offs. Use when designing APIs, microservices vs monolith boundaries, data models, authentication flows, or infrastructure-facing code.
02 资源文件 1
- 参考文档references/patterns.md1.2 KB
03 SKILL.md 正文
Backend Architecture
Apply before new services, API surfaces, database schemas, or auth/payment flows.
Decision checklist
- Topology — monolith module vs separate service vs serverless functions
- API style — REST, GraphQL, RPC, events
- Data store — relational, document, cache, queue
- Consistency — strong vs eventual; saga/outbox needs
- Auth model — session, JWT, OAuth, API keys; where authZ runs
- Failure model — timeouts, retries, idempotency, circuit breakers
Layer boundaries (non-negotiable default)
HTTP / transport → routes, controllers, handlers (thin)
Service layer → business rules, orchestration, authZ checks
Domain / models → entities, invariants, domain errors
Data access → repositories, queries (parameterized only)
Infrastructure → email, queues, third-party clients
Rules:
- Handlers validate input shape; services enforce business rules
- No SQL/ORM in route handlers
- AuthZ in service layer, not only at route edge
- External calls have timeouts and structured errors
API design defaults
| Concern | Default |
|---|---|
| Errors | { success, error: { code, message, details? } } + correct HTTP status |
| Lists | Cursor or offset pagination; never unbounded |
| Versioning | /v1/ prefix or header when public API |
| Idempotency | Idempotency-Key for payments/writes |
| Validation | Schema at boundary (Zod, Pydantic, etc.) |
Trade-offs to surface
| Decision | Options | Default for greenfield |
|---|---|---|
| Architecture | Modular monolith vs microservices | Modular monolith until team/scale forces split |
| DB | PostgreSQL vs MongoDB | PostgreSQL unless document model is dominant |
| Cache | None vs in-process vs Redis | None first; Redis when measured need |
| Async | Sync handler vs job queue | Queue when work >500ms or retries needed |
| Consistency | Strong vs eventual | Strong for money/auth; eventual for analytics |
Document chosen trade-offs in ADR or plan using trade-offs.mdc.
Scalability checklist
- [ ] Stateless app tier where possible
- [ ] Connection pooling for DB
- [ ] Indexes on hot query paths
- [ ] No N+1 queries
- [ ] Rate limits on auth and public endpoints
- [ ] Secrets from environment only
Anti-patterns to reject
- Anemic domain — all logic in controllers
- God service class
- String-interpolated SQL
- Swallowed exceptions
- Distributed monolith (microservices sharing one DB with tight coupling)
Output when architecting
Produce Backend Architecture Note:
- Topology and module boundaries
- API contract sketch (resources, auth)
- Data model overview
- Async/cache/retry strategy
- Security and observability hooks
- Phased rollout plan
Additional reference
04 同仓库更多 Skills
greet
A greeting skill for testing
★ 1
valid-skill
A valid skill for testing purposes.
★ 1
unknown-field
A skill with an unknown frontmatter field.
★ 1
no-frontmatter
暂无简介
★ 1
child-skill
A nested skill in a subdirectory.
★ 1
different-name
A skill with a name that doesn't match the directory.
★ 1