# Microservice Specification: [service-name]

> One-page-per-service canvas that records what a microservice is for,
> who owns it, what it exposes and consumes, which data it owns, how it
> runs, scales, is observed and secured, and how it is versioned. Based
> on common industry practice for service canvases and service catalogue
> entries. Replace every `[bracketed]` value and every row marked
> *Example*. Worked examples use an inventory reservation service.

<!--
Guidance: How to use this template
- Fill sections 1 to 4 before the service is built. If you cannot state the
  bounded context and the data it owns in two sentences, the service
  boundary is probably wrong.
- Keep this file in the service repository (for example `docs/SERVICE.md`)
  and link it from the service catalogue.
- Link to the detailed API, event and runbook documents rather than copying
  them here; this canvas is the index.
- Review the canvas when ownership, dependencies or SLOs change.
-->

| Field | Value |
|---|---|
| Service name | [inventory-reservation] |
| Document version | [0.1] |
| Status | [Proposed / In development / Production / Deprecated] |
| Owning team | [@team-inventory] |
| Technical owner | [@tech-lead] |
| On-call rotation | [inventory-oncall] |
| Repository | [git URL] |
| Service tier | [Tier 1 / Tier 2 / Tier 3] |
| Last updated | YYYY-MM-DD |

## 1. Purpose and bounded context

<!-- Guidance: What business capability the service provides, the domain language it owns and what it deliberately does not do. -->

### 1.1 Purpose

[One paragraph. Example: "Reserves stock for items in a checkout so that
two customers cannot buy the last unit, and releases reservations that
are not confirmed within 15 minutes."]

### 1.2 Bounded context

| Item | Value |
|---|---|
| Domain / subdomain | *Example:* Inventory / Availability (core subdomain) |
| Key domain terms | *Example:* Reservation, stock keeping unit (SKU), available-to-promise, hold expiry |
| Responsibilities | Create, confirm, release and expire reservations; publish availability changes |
| Not responsible for | Stock counts at warehouses (Warehouse service), prices (Pricing service), orders (Orders service) |
| Upstream contexts | Warehouse (stock levels), Catalogue (SKU validity) |
| Downstream contexts | Checkout, Orders, Storefront search |

## 2. Ownership and lifecycle

<!-- Guidance: Who to contact, who is woken at night and where the service is in its life. -->

| Role | Name / channel |
|---|---|
| Owning team | [@team-inventory] |
| Product owner | [@product-owner] |
| On-call escalation | [Paging service], then [@engineering-manager] |
| Support channel | [#inventory-help] |
| Lifecycle stage | [Production since YYYY-MM-DD] |
| Planned changes | [Example: Multi-warehouse reservations in Q2] |

## 3. Interfaces

<!-- Guidance: List every synchronous API the service exposes and calls. Each row links to its contract. Unlisted dependencies are the usual cause of surprise outages. -->

### 3.1 Exposed APIs

| API | Style | Contract | Consumers | Auth |
|---|---|---|---|---|
| `POST /v1/reservations` | REST | [openapi.yaml#createReservation] | Checkout | OAuth 2.0 client credentials, scope `inventory:reserve` |
| `POST /v1/reservations/{id}/confirm` | REST | [openapi.yaml] | Orders | Same, scope `inventory:confirm` |
| `DELETE /v1/reservations/{id}` | REST | [openapi.yaml] | Checkout | Same |
| `GET /v1/availability?sku=` | REST | [openapi.yaml] | Storefront, Search | Scope `inventory:read` |
| [API] | [REST / gRPC / GraphQL] | [Link] | [Consumers] | [Auth] |

### 3.2 Consumed APIs

| API | Provider | Purpose | Timeout | Fallback if unavailable |
|---|---|---|---|---|
| `GET /v2/skus/{sku}` | Catalogue service | Validate SKU on reservation | 300 ms | Use cached SKU list (refreshed every 5 min) |
| [API] | [Provider] | [Purpose] | [Timeout] | [Fallback] |

## 4. Events

<!-- Guidance: Events published and consumed, with channel, schema and delivery semantics. Link the event API specification for details. -->

### 4.1 Published events

| Event | Channel | Schema | Trigger | Key |
|---|---|---|---|---|
| ReservationCreated | `inventory.reservation.v1` | [registry subject] | Reservation stored | `sku` |
| ReservationExpired | `inventory.reservation.v1` | [subject] | Hold timer elapsed | `sku` |
| AvailabilityChanged | `inventory.availability.v1` | [subject] | Available quantity crosses a threshold | `sku` |
| [Event] | [Channel] | [Schema] | [Trigger] | [Key] |

### 4.2 Consumed events

| Event | Channel | Producer | Handling | Idempotency |
|---|---|---|---|---|
| StockAdjusted | `warehouse.stock.v1` | Warehouse service | Update on-hand quantity | Event ID stored for 7 days |
| OrderCancelled | `orders.order.v1` | Orders service | Release confirmed reservation | Reservation state check |
| [Event] | [Channel] | [Producer] | [Handling] | [Method] |

## 5. Data owned

<!-- Guidance: Data this service is the system of record for. No other service may write it. Name the store, the classification and the retention. -->

| Data | Store | Classification | Retention | Shared how |
|---|---|---|---|---|
| Reservations | *Example:* PostgreSQL `inventory_reservation` | Internal | 90 days after expiry or confirmation | API and events only |
| Available-to-promise per SKU | Redis (derived, rebuildable) | Internal | Live | `GET /availability` |
| [Data] | [Store] | [Class] | [Retention] | [Mechanism] |

No other service reads these stores directly. Reporting uses the
published events.

## 6. Dependencies

<!-- Guidance: Runtime dependencies, their criticality and what happens when each fails. -->

| Dependency | Type | Criticality | Failure behaviour |
|---|---|---|---|
| PostgreSQL | Data store | Hard | Reservations fail with 503; checkout shows "try again" |
| Redis | Cache | Soft | Availability served from database at higher latency |
| Message broker | Messaging | Soft | Events buffered in outbox up to [6 hours] |
| Catalogue service | API | Soft | Cached SKU list |
| [Dependency] | [Type] | [Hard / Soft] | [Behaviour] |

## 7. Service level objectives

<!-- Guidance: Few, user-centred SLOs with a measurement method. Derive alerts from error budget burn. -->

| SLI | SLO | Window | Measured at |
|---|---|---|---|
| Availability of `POST /reservations` | 99.95% non-5xx | 28 days rolling | Gateway |
| Latency of `POST /reservations` | 99% under 150 ms | 28 days rolling | Gateway |
| Expiry accuracy | 99.9% of holds released within 60 s of expiry | 28 days | Service metric |
| [SLI] | [SLO] | [Window] | [Point] |

Error budget for availability in a 28-day window:

$$
B = (1 - 0.9995) \times 28 \times 24 \times 60 \approx 20\ \text{minutes}
$$

## 8. Scaling and capacity

<!-- Guidance: Expected load, how the service scales and its known limits. -->

| Item | Value |
|---|---|
| Expected load | *Example:* 120 reservations/s average, 900/s at sale start |
| Scaling model | Horizontal; stateless pods; HPA on CPU 60% and request rate |
| Replicas | Min 3 (one per zone), max 30 |
| Known limit | Single hot SKU above 2 000 reservations/s contends on one row; mitigated with sharded counters |
| Load test | Last run YYYY-MM-DD at 1 500 reservations/s |

## 9. Configuration

<!-- Guidance: Every setting that changes behaviour, where it comes from and its default. Secrets are referenced, never shown. -->

| Key | Purpose | Default | Source |
|---|---|---|---|
| `HOLD_TTL_SECONDS` | Reservation hold time | `900` | Environment |
| `MAX_QTY_PER_RESERVATION` | Abuse limit per request | `20` | Feature flag service |
| `DB_URL` | Database connection | none | Secrets manager `inventory/db` |
| `CATALOGUE_BASE_URL` | Catalogue API | per environment | Environment |
| [KEY] | [Purpose] | [Default] | [Source] |

## 10. Deployment

<!-- Guidance: How code reaches production and how to undo it. -->

| Item | Value |
|---|---|
| Runtime | *Example:* Container on Kubernetes, namespace `inventory` |
| Pipeline | [CI system] build, test, scan, sign, deploy to staging, canary 10% for 15 min, full rollout |
| Environments | dev, staging, production (two regions) |
| Rollback | Automatic on canary error rate above 1%; manual via `[deploy tool] rollback` |
| Database migrations | Expand and contract; run as a pre-deploy job |
| Release frequency | Daily |

## 11. Observability

<!-- Guidance: Where to look when something is wrong. Name dashboards, key metrics, log fields and traces. -->

| Signal | Where | Key items |
|---|---|---|
| Metrics | [Dashboard link] | Request rate, error rate, p99 latency, active holds, expiry lag |
| Logs | [Log query link] | Structured JSON; fields `reservation_id`, `sku`, `trace_id` |
| Traces | [Tracing link] | Spans for database, cache, catalogue calls |
| Alerts | [Alert rules link] | SLO burn rate (fast and slow), expiry lag above 120 s, outbox age above 5 min |
| Runbook | [Runbook link] | One section per alert |

## 12. Security

<!-- Guidance: Identity, authorisation, data protection and abuse controls specific to this service. -->

| Topic | Control |
|---|---|
| Inbound authentication | OAuth 2.0 tokens validated at gateway and service; mTLS in mesh |
| Authorisation | Scope per endpoint (3.1); reservations can only be confirmed by Orders |
| Outbound identity | Workload identity; no static credentials |
| Data | No personal data stored; reservation references checkout session ID only |
| Abuse | Per-session limit of [5] active reservations; quantity cap |
| Dependencies | Image and dependency scanning in CI; critical fixes within [7] days |

## 13. Versioning and compatibility

<!-- Guidance: How the service changes its contracts without breaking consumers. -->

| Contract | Versioning | Compatibility promise | Deprecation notice |
|---|---|---|---|
| REST API | Major version in path (`/v1`) | Additive changes only within a major version | [6 months], `Deprecation` and `Sunset` headers |
| Events | Major version in channel name | Registry enforces backward-compatible schemas | [6 months] dual publishing |
| Service release | Semantic versioning of the build | n/a | Release notes in [link] |

## 14. Related documents

<!-- Guidance: Links to the detailed documents this canvas summarises. -->

| Document | Link |
|---|---|
| REST API specification | [link] |
| Event API specification | [link] |
| Architecture decision records | [link] |
| Runbook | [link] |
| Threat model | [link] |

## Standard and licence note

Based on common industry practice for microservice canvases and service
catalogue entries. Original text written for this collection; example
values are illustrative. Template licence: MIT.