Backend Architect Mentor

An agent that mentors developers on backend architecture decisions covering API design, service decomposition, data flow patterns, authentication strategies, and system design principles for building scalable server-side applications.

When to Use This Agent

Choose Backend Architect Mentor when:

• Designing API architectures (REST, GraphQL, gRPC)
• Planning service boundaries and communication patterns
• Selecting databases and caching strategies for backend systems
• Implementing authentication and authorization architectures
• Mentoring junior developers on backend design principles

Consider alternatives when:

• Writing specific backend code (use a backend development agent)
• Reviewing existing architecture for production readiness (use an architecture review agent)
• Designing frontend architecture (use a frontend architecture agent)

Quick Start

Copy
# .claude/agents/backend-architect-mentor.yml
name: Backend Architect Mentor
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
prompt: |
  You are a backend architecture mentor. Teach and guide developers
  on API design, service decomposition, data flow, and system
  design principles. Explain the "why" behind architectural
  decisions. Help developers build intuition for trade-offs
  rather than just following rules.

Example invocation:

Copy
claude --agent backend-architect-mentor "Help me design the
  backend architecture for a multi-tenant project management
  tool. Guide me through API design, data isolation, and
  authentication decisions with explanations of trade-offs."

Core Concepts

Backend Architecture Layers

Client Requests
    ↓
API Gateway (rate limiting, auth, routing)
    ↓
Application Layer (business logic, validation)
    ↓
Service Layer (domain services, orchestration)
    ↓
Data Access Layer (repositories, ORM, queries)
    ↓
Data Stores (databases, caches, queues)

API Design Decision Tree

Question	Options	When to Choose
API style?	REST / GraphQL / gRPC	REST=standard, GraphQL=flexible queries, gRPC=microservice internal
Auth method?	JWT / Session / OAuth2	JWT=stateless, Session=simple, OAuth2=third-party
Pagination?	Cursor / Offset	Cursor=real-time, Offset=simple
Versioning?	URL / Header / None	URL=explicit, Header=clean URLs
Rate limiting?	Fixed window / Sliding window / Token bucket	Token bucket=most flexible

Design Principles

1. Separation of Concerns → each layer has one job
2. Dependency Inversion → depend on abstractions, not implementations
3. Fail Fast → validate early, error explicitly
4. Idempotency → same request = same result
5. Least Privilege → minimum permissions required

Configuration

Parameter	Description	Default
api_style	Preferred API architecture	REST
language	Primary backend language	TypeScript/Node.js
framework	Backend framework	Express/Fastify
database	Primary data store	PostgreSQL
auth_method	Authentication approach	JWT
mentoring_level	Explanation depth	Intermediate
include_examples	Add code examples	true

Best Practices

1. Design APIs around resources and actions, not database tables. A POST /users/signup endpoint is more meaningful than POST /users with a type: signup body. The API should reflect business operations, not data model structure. This abstraction protects clients from internal changes and creates an API that's intuitive to consume.

2. Validate at the boundary, trust internally. Validate all external input (API requests, webhook payloads, file uploads) rigorously at the API layer. Once validated, internal services can trust the data without re-validating. This approach keeps validation logic concentrated and prevents defensive programming from cluttering business logic.

3. Choose your consistency model deliberately. Strong consistency (synchronous operations, transactions) is simpler but slower. Eventual consistency (async events, message queues) is faster but more complex. The choice depends on the business requirement: financial transactions need strong consistency; notification delivery can be eventually consistent. Document the consistency model for each data flow.

4. Design for observability from the start. Add structured logging, request tracing, and metrics to every service from day one. Include correlation IDs in all logs so you can trace a request across services. Use health check endpoints that verify actual functionality (database connectivity, upstream dependencies), not just that the process is running.

5. Make breaking changes impossible through contract-first design. Define API contracts (OpenAPI specs, protobuf schemas) before writing implementation code. Generate client SDKs and server stubs from contracts. Breaking changes require contract version bumps that are visible in code review. This discipline prevents accidental API breaks that downstream consumers discover in production.

Common Issues

API design changes frequently as frontend needs evolve. This indicates the API is too tightly coupled to a specific frontend. Design the API around business capabilities that serve multiple clients. If the mobile app needs different data shapes than the web app, use field selection or a BFF (Backend for Frontend) pattern rather than changing the core API for each client's needs.

Services grow into "mini-monoliths" with blurry boundaries. This happens when service boundaries follow technical layers (auth service, data service) rather than business domains (user service, order service). Refactor boundaries around business capabilities: each service owns a complete domain including its API, business logic, and data. If splitting a feature requires coordinating changes across three services, the boundaries are wrong.

Authentication and authorization logic is scattered throughout the codebase. Centralize auth in middleware/interceptors that run before business logic. Authentication (who are you?) should be a single middleware. Authorization (what can you do?) can use policy engines or RBAC middleware. Business logic should receive a validated user context and never check tokens directly. Centralized auth is easier to audit, test, and update.