Tech Spec / LLD

Low-level design. What an implementer needs that the HLD does not say.

Format.md
Length70 lines
Includesnone

The source

70 lines of Markdown, with nothing to install. Copy it, or open the template inside Gnomon and render it as it is.

# Tech Spec: <Component / Feature>

- **Author:** <name>
- **Reviewers:** <names>
- **Status:** Draft | Reviewed | Approved
- **Related:** [HLD](./hld.md), [RFC](./rfc.md)

## Summary

What we're building, in 2–3 sentences.

## Interfaces

### Public API
```
POST /v1/<resource>
  Request:  { … }
  Response: { … }
  Errors:   400, 401, 409, 5xx
```

### Internal contracts
- **Events emitted:** `<topic>` — schema, ordering, retention.
- **Events consumed:** `<topic>` — at-least-once / exactly-once?

## Data Model

```
<entity>
  id              UUID         PK
  created_at      TIMESTAMPTZ  not null
  …               …            …
  Indexes: …
  Constraints: …
```

Migration strategy: <online, backfill, dual-write, …>.

## Error Handling

| Failure mode             | Detection           | Response                  |
|--------------------------|---------------------|---------------------------|
| Downstream timeout       | Per-call deadline   | Retry with backoff (n=3)  |
| Validation failure       | At ingress          | 400 with error code       |
| Partial write            | Transaction abort   | Rollback + alert          |
| Poison message           | DLQ after 5 retries | Page on-call              |

## Observability

- **Logs:** structured JSON; `request_id`, `user_id`, `feature_flag` always present.
- **Metrics:**
  - `<service>_request_duration_seconds` (histogram, by route + status)
  - `<service>_errors_total` (counter, by code)
  - `<service>_queue_depth` (gauge)
- **Traces:** OpenTelemetry; one span per outbound call.
- **Alerts:** see [Runbook](./runbook.md).

## Rollout

- Feature flag: `<flag-name>`.
- Stages: internal → 1% → 10% → 50% → 100%.
- Rollback plan: …

## Testing

- Unit, integration, contract, load, chaos. Note any gaps.

## Open Questions

- [ ] …

Render this offline

This template ships in Gnomon and renders on your machine, with no account and no diagram uploads. The browser editor is free and needs no install.

Get Gnomon Open the browser editor

Others in Architecture document templates

ADR — Architecture Decision RecordContext, decision, consequences. The alternatives section is the valuable one.
RFC — Request for CommentsFor proposing a change and inviting disagreement before building.
HLD — High-Level DesignHigh-level design: the shape, the constraints, the risks.
NFR CatalogueThe requirements that get discovered late and expensively.
RunbookWhat to do at 3am. Written for someone tired and unfamiliar.
Discovery / Spike ReportFindings from a time-boxed investigation, including the dead ends.
Post-Mortem / Incident ReviewBlameless incident review. Timeline first, conclusions second.
Solution One-PagerA solution summary for people who will not read the HLD.