Skip to main content

Service Design

Service Design Document

Project: {{PROJECT_NAME}} Service: {{SERVICE_NAME}} Version: {{VERSION}} Date: {{DATE}} Author: {{AUTHOR}} Status: Draft | In Review | Approved Reviewers: {{REVIEWERS}}

Document History

Version Date Author Changes
0.1 {{DATE}} {{AUTHOR}} Initial draft

1. Service Overview

Property Value
Service name {{service-name}}
Bounded context {{Domain / bounded context name}}
Repository {{https://github.com/org/service-name}}
Owner team {{Team Name}}
On-call {{PagerDuty rotation / team contact}}
Runbook {{https://wiki.domain.com/runbooks/service-name}}
Tech stack {{Node.js 20 + NestJS + PostgreSQL + Redis}}

Purpose:

TODO: 2-3 sentences. What does this service do? What business capability does it own? What is explicitly OUT of scope?

Bounded context: This service owns the {{DOMAIN}} domain. It is the single source of truth for {{entities owned}}. Other services must NOT directly access this service's database — they must call its API or subscribe to its events.

2. Service Responsibility & Ownership

This service IS responsible for:

  • {{Primary responsibility 1}}
  • {{Primary responsibility 2}}
  • {{Primary responsibility 3}}

This service is NOT responsible for:

  • {{Out-of-scope concern 1 — handled by service X}}
  • {{Out-of-scope concern 2}}

Data ownership:

  • Owns: {{users, user_profiles, user_preferences tables}}
  • Does NOT own: {{orders (belongs to order-service)}}

3. Interface Definition

3.1 REST API Endpoints

Method Path Description Auth
GET /{{service}}/health Health check None
GET /{{service}}/{{resource}} List {{resources}} Bearer JWT
GET /{{service}}/{{resource}}/:id Get by ID Bearer JWT
POST /{{service}}/{{resource}} Create Bearer JWT
PATCH /{{service}}/{{resource}}/:id Update Bearer JWT
DELETE /{{service}}/{{resource}}/:id Delete Bearer JWT

Internal endpoints (service-to-service only, no external access):

Method Path Description Auth
GET /internal/{{resource}}/:id Bulk lookup by IDs Service API key

Full API reference: See api-reference.md or {{OpenAPI URL}}

3.2 gRPC Service Definition (if applicable)

// proto/{{service_name}}.proto
syntax = "proto3";

package {{service_name}};

service {{ServiceName}}Service {
  rpc Get{{Resource}} (Get{{Resource}}Request) returns ({{Resource}});
  rpc List{{Resources}} (List{{Resources}}Request) returns (List{{Resources}}Response);
  rpc Create{{Resource}} (Create{{Resource}}Request) returns ({{Resource}});
}

message {{Resource}} {
  string id = 1;
  string name = 2;
  string created_at = 3;
}

message Get{{Resource}}Request {
  string id = 1;
}

TODO: Remove or populate gRPC section based on actual communication protocol.

3.3 Events Published

Event Type Trigger Topic / Queue Consumer(s)
{{domain}}.{{entity}}.created Entity created {{topic-name}} {{service-a, service-b}}
{{domain}}.{{entity}}.updated Entity updated {{topic-name}} {{service-a}}
{{domain}}.{{entity}}.deleted Soft delete {{topic-name}} {{service-b}}

Example published event:

{
  "specversion": "1.0",
  "type": "{{domain}}.{{entity}}.created",
  "source": "{{service-name}}",
  "id": "evt_01HX7...",
  "time": "2024-01-15T10:30:00Z",
  "datacontenttype": "application/json",
  "data": {
    "id": "{{UUID}}",
    "{{field}}": "{{value}}"
  }
}

Full event schemas: See event-schema-documentation.md

3.4 Events Consumed

Event Type Source Service Handler Action
{{domain}}.{{entity}}.created {{source-service}} {{Action this service takes}}
{{domain}}.{{entity}}.deleted {{source-service}} {{Action — e.g., cascade delete}}

Consumer group: {{service-name}}-consumer Idempotency: All handlers are idempotent (duplicate events produce same result).

4. Database

4.1 Technology & Rationale

Property Value
Database {{PostgreSQL 16}}
ORM {{Prisma 5}}
Rationale {{Why this DB was chosen}}
Hosting {{AWS RDS / Supabase / Self-hosted}}
Replication {{1 primary + 2 read replicas}}
Backup {{Daily snapshot + WAL archiving}}
Encryption At rest and in transit

4.2 Schema Overview

erDiagram
    USERS {
        uuid id PK
        string email UK
        string name
        string role
        string status
        timestamp created_at
        timestamp updated_at
        timestamp deleted_at
    }

    USER_PROFILES {
        uuid id PK
        uuid user_id FK
        string avatar_url
        string bio
        jsonb settings
        timestamp updated_at
    }

    USER_SESSIONS {
        uuid id PK
        uuid user_id FK
        string refresh_token_hash
        string ip_address
        timestamp expires_at
        timestamp created_at
    }

    USERS ||--o| USER_PROFILES : has
    USERS ||--o{ USER_SESSIONS : has

TODO: Update schema to reflect actual tables. Add missing tables.

4.3 Data Ownership Boundaries

  • Read access: Any service may query via this service's API
  • Write access: ONLY this service writes to its tables
  • Direct DB access: FORBIDDEN for all other services

Cross-service data pattern:

Service A needs user name:
  → GET /users/:id via HTTP (NOT direct DB query)
  → Or subscribe to user.updated events and cache locally

5. Dependencies

5.1 Upstream Services (Services This Depends On)

Service Purpose Criticality Fallback
{{auth-service}} JWT validation Critical Cache valid tokens 5 min
{{notification-service}} Send emails Non-critical Queue for retry
{{{{EXTERNAL_API}}}} {{Purpose}} {{Critical/Non-critical}} {{Fallback strategy}}

5.2 Downstream Services (Services That Depend On This)

Service How it uses this service Impact if this service is down
{{order-service}} Validate user exists before creating order Cannot create orders
{{notification-service}} Resolve user email for delivery Cannot send user notifications

5.3 External APIs & Third-Party

Service Purpose Rate Limit Credentials
{{SendGrid}} Transactional email 100 req/s Vault: sendgrid/api-key
{{Stripe}} Payment processing — Vault: stripe/secret-key

5.4 Dependency Diagram

graph LR
    ThisService["{{service-name}}"]

    subgraph "Upstream (depends on)"
        AuthService["auth-service"]
        ExternalAPI["external-api"]
    end

    subgraph "Downstream (depended on by)"
        OrderService["order-service"]
        NotifService["notification-service"]
    end

    AuthService --> ThisService
    ExternalAPI --> ThisService
    ThisService --> OrderService
    ThisService --> NotifService

6. Deployment Configuration

Property Dev Staging Production
Replicas 1 2 {{min: 3, max: 10}}
CPU request 100m 250m 500m
CPU limit 500m 1000m 2000m
Memory request 128Mi 256Mi 512Mi
Memory limit 512Mi 1Gi 2Gi
Port 4000 4000 4000

Kubernetes manifest location: {{k8s/{{service-name}}/}} Helm chart: {{charts/{{service-name}}/}} Docker image: {{registry.domain.com/service-name}}

7. Scaling Strategy

Dimension Strategy Trigger
Horizontal (replicas) HPA: CPU > 70% OR RPS > 1000 Automatic
Vertical (resources) VPA recommendations reviewed monthly Manual
Database Read replicas for SELECT queries Manual
Cache Redis Cluster when > 10GB RAM Manual

Stateless confirmation: This service stores NO session state in memory — safe to scale horizontally.

8. Health Check & Readiness Probes

livenessProbe:
  httpGet:
    path: /health/live
    port: 4000
  initialDelaySeconds: 30
  periodSeconds: 10
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /health/ready
    port: 4000
  initialDelaySeconds: 10
  periodSeconds: 5
  failureThreshold: 3

startupProbe:
  httpGet:
    path: /health/startup
    port: 4000
  failureThreshold: 30
  periodSeconds: 10

9. SLA Commitments

Metric Target Measurement Window
Availability 99.9% (8.7h downtime/year) Rolling 30 days
P50 response time < 50ms 1 hour
P95 response time < 200ms 1 hour
P99 response time < 500ms 1 hour
Error rate (5xx) < 0.1% 1 hour

SLA breach escalation: Alert → PagerDuty {{on-call rotation}} → Incident declared at SLA breach risk.

10. Monitoring & Alerting Rules

Metric Threshold Alert Severity Channel
Error rate (5xx) > 1% for 5 min P1 PagerDuty
P99 latency > 1s for 5 min P2 Slack #alerts
CPU utilization > 85% for 10 min P3 Slack #alerts
Memory utilization > 80% P3 Slack #alerts
DB connection pool > 80% P2 PagerDuty
Queue depth > 10,000 items P2 Slack #alerts

Dashboard: {{https://monitoring.domain.com/dashboards/service-name}}

11. Runbook Reference

Runbook location: {{https://wiki.domain.com/runbooks/{{service-name}}}}

Quick reference for common incidents:

Incident Initial Response
High error rate Check logs → identify error pattern → scale up if OOM
High latency Check DB slow query log → check Redis hit rate → check upstream dependency
Pod crash loop Check OOMKilled → check logs → check health probe thresholds
DB connection exhaustion Check pool config → check idle connections → force disconnect

Approval

Role Name Date Signature
Author
Service Owner
Architect
SRE Lead

No comments to display

Back to top