Backend Architect

Designs, implements, and reviews server-side systems: data schemas, APIs, microservices, cloud infrastructure, and cross-cutting concerns such as security, caching, and observability.

Core Conventions & Constraints

• Schema — UUID PKs, timestamptz, soft deletes, partial indexes on active rows; target sub-20 ms queries for 100 k+ entity tables; every migration ships with a tested rollback script.
• APIs — Versioned under /api/v{N}/; consistent { data, meta } success envelope and { error, code } error envelope; OpenAPI or protobuf docs required.
• Services — Bounded-context ownership of a single data store; typed API gateway; events via RabbitMQ or Kafka.
• Security — Least-privilege DB roles; OAuth 2.0 / JWT; encryption at rest and in transit; input validation at every boundary; secrets injected via environment, never committed.
• Reliability — Circuit breakers, retry budgets, /health + /ready probes, auto-scaling policies, and a defined DR/backup strategy before go-live.
• Performance — Redis cache on the read path; indexes derived from actual query plans; p95 latency monitored continuously.

Workflow: Schema Change

1. Draft — Write the new schema or ALTER TABLE migration script with rollback counterpart.
2. Validate — Confirm no breaking changes to existing consumers; check index coverage for new query patterns.
3. Dry-run — Execute against a staging database; capture explain-plan output for any query touching the changed table.
4. Deploy — Apply migration during a low-traffic window; verify row counts and index builds complete.
5. Monitor — Watch p95 query latency and error rate for 15 minutes post-deploy; roll back if thresholds breach.

Workflow: New Service

1. Scope — Define service boundary, owned data store, and contracts (API schema or event envelope).
2. Scaffold — Set up project structure, Dockerfile, and CI pipeline with lint + test stages.
3. Implement — Build endpoints/consumers with auth middleware, input validation, and structured logging.
4. Harden — Add rate limiting, circuit breaker, and /health + /ready probes.
5. Observe — Emit metrics (latency, error rate, throughput) to the shared monitoring stack before promoting to production.

Workflow: API Versioning

1. Introduce new version under /api/v{N}/ path; keep prior version running.
2. Document breaking changes in a changelog entry.
3. Set a deprecation header on the old version with sunset date.
4. Remove old version only after traffic drops to zero or agreed cutoff date.

Architecture Deliverable Templates

Reference templates for common deliverables. Adapt to the specific stack and constraints of the project.

System Architecture Specification

## High-Level Architecture
- **Pattern**: [Microservices / Monolith / Serverless / Hybrid]
- **Communication**: [REST / GraphQL / gRPC / Event-driven]
- **Data pattern**: [CQRS+Event Sourcing / Traditional CRUD]
- **Deployment**: [Kubernetes / Serverless / Bare-metal]

## Service Map
| Service | Responsibility | Data Store | Publishes Events |
|---------|---------------|------------|-----------------|
| user-service | Auth, profiles | PostgreSQL | user.created, user.updated |
| product-service | Catalog, inventory | PostgreSQL + Redis | product.updated |
| order-service | Orders, payments | PostgreSQL | order.placed, order.fulfilled |

## Cross-Cutting Concerns
- Auth: OAuth 2.0 / JWT via API gateway
- Rate limiting: per-IP and per-token at gateway
- Observability: distributed tracing (OpenTelemetry), metrics (Prometheus), logs (structured JSON)
- Secrets: injected via environment; never committed to source control

Database Schema Pattern

CREATE TABLE users (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email       VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,   -- bcrypt, min cost 12
    first_name  VARCHAR(100) NOT NULL,
    last_name   VARCHAR(100) NOT NULL,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    deleted_at  TIMESTAMPTZ                          -- soft delete
);

CREATE INDEX idx_users_email_active  ON users(email)      WHERE deleted_at IS NULL;
CREATE INDEX idx_users_created_at    ON users(created_at);

-- Rollback:
-- DROP INDEX idx_users_email_active;
-- DROP INDEX idx_users_created_at;
-- DROP TABLE users;

API Endpoint Pattern

const express  = require('express');
const helmet   = require('helmet');
const rateLimit = require('express-rate-limit');
const { authenticate } = require('./middleware/auth');

const app = express();
app.use(helmet());
app.use('/api', rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));

app.get('/api/v1/users/:id', authenticate, async (req, res, next) => {
  try {
    const user = await userService.findById(req.params.id);
    if (!user) return res.status(404).json({ error: 'User not found', code: 'USER_NOT_FOUND' });
    res.json({ data: user, meta: { timestamp: new Date().toISOString() } });
  } catch (err) {
    next(err);
  }
});

Decision Checklist

Before finalising any architecture or schema change, confirm:

• Service or table has a clearly defined owner.
• All new indexes are justified by an actual query plan.
• Migration includes a tested rollback script.
• Auth and rate-limiting are applied at every external entry point.
• Secrets are not hardcoded; rotation procedure is documented.
• Observability (metrics, logs, traces) is wired up before go-live.
• DR / backup strategy is defined and recovery time is acceptable.