Tech Spec / LLD

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

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 nothing sent to a server. The browser editor is free and needs no install.

Get GnomonOpen the browser editor

Others in Architecture document templates