Skip to main content

Design Doc Template

Copy into docs/designs/<slug>-<cu-id>.md and fill in. The Design Doc is R&D's translation of the PRD into implementation. It's owned by Engineering; written after the PRD reaches ready-for-rd.

The Design Doc covers everything the PRD intentionally left open: API endpoints, schema, architecture, sequencing, task breakdown.

---
id: design-<slug>
title: "Design Doc: <Feature Name>"
description: "<one-sentence summary>"

# Lifecycle โ€” same flow as PRD
status: draft                # draft | in-review | approved | in-progress | shipped | deprecated
author: "@<eng-handle>"
created: <YYYY-MM-DD>
updated: <YYYY-MM-DD>

# Source of truth โ€” the PRD this implements
related_prd: docs/prds/<slug>-<cu-id>.md
clickup_parent: "CU-XXXXX"

# Affected repos (the codebases this design touches)
affected_repos: [backend, organization-dashboard, consumer]

# Cross-links
related_adrs: []             # ADRs that govern decisions here
related_designs: []          # peer or predecessor Design Docs

ai_assisted: false
tags: []
---

# Design Doc: <Feature Name>

<div style={{display:'flex',gap:'0.5rem',marginBottom:'1.5rem'}}>
  <span className="badge badge--primary">Draft</span>
  <span className="badge badge--secondary">Author: @handle</span>
  <span className="badge badge--secondary">PRD: <slug>-CU-XXXXX</span>
</div>

## TL;DR

Three to five sentences: **the chosen approach and why.** Note any PRD constraint that shaped it. A reader should know whether to keep reading.

## 1. Approach & Rationale

The chosen approach, stated plainly. Then the **why** โ€” what made it the right call given the PRD's constraints.

If alternatives were seriously considered, summarize each in one sentence and state why it was rejected. (Detailed alternatives go in ยง15 Risks.)

## 2. Affected Repos

List each repo this design touches, and what changes there:

| Repo | What changes |
|---|---|
| `backend-services` | New module `<name>`; integrates with <X> |
| `organization-dashboard` | New page `/admin/<โ€ฆ>`; uses existing `Table` component |
| `consumer` | <โ€ฆ> |

## 3. Architecture

High-level component interaction. Use a mermaid `flowchart` when there are 3+ components or any non-obvious flow.

```mermaid
flowchart TD
    Client[Client app] -->|action| BFF
    BFF --> Service[New service]
    Service --> DB[(Mongo)]
    Service --> External[3rd party]
```

Describe the choices visible above (why a new service vs extending an existing one, why this DB, etc.) in a short paragraph.

## 4. Data Model

**Skip this section if no new persistence is introduced.**

```mermaid
classDiagram
    class EntityA {
        ObjectId id
        String name
        Date createdAt
    }
    class EntityB {
        ObjectId id
        ObjectId entityAId
        String status
    }
    EntityA "1" --> "*" EntityB
```

| Collection / table | Fields | Indexes / constraints |
|---|---|---|
| `<name>` | `<id, โ€ฆ>` | `unique(name, hub_id)` |

Migrations / backfills required: <Y/N + script reference>.

## 5. API / Contracts

Endpoints introduced or changed. **Every business-logic action listed in PRD ยง8.2 (API-accessible capabilities) MUST appear here.**

| Method + Path | Purpose | Request | Response | Maps to PRD FR |
|---|---|---|---|---|
| `POST /api/v1/<โ€ฆ>` | Create <X> | `{ name, โ€ฆ }` | `{ id, โ€ฆ }` | FR-01 |
| `GET /api/v1/<โ€ฆ>/:id` | Fetch <X> | `params: id` | `{ โ€ฆ }` | FR-02 |

Auth scopes / roles per endpoint:

| Endpoint | Auth |
|---|---|
| `POST /api/v1/<โ€ฆ>` | bearer token, admin role |

## 6. Frontend & Components

Map each component in PRD ยง7.2 to its implementation. Anchor every row to `@bewith-dev/design-system`'s `COMPONENTS.md`.

| Component (from PRD ยง7.2) | Reuse / new | Source | States handled |
|---|---|---|---|
| `CategoryTable` | reuse | `Table` from `@bewith-dev/design-system` | default / loading / empty / error |
| `<NewSomething>` | **new** | `/add-component` task in design-system | (list states) |

Any **new** component request is a separate task (in design-system, via `/add-component`). It is a **blocker** on the consuming repo's task โ€” never inline a one-off.

## 7. Observability Instrumentation

Where the events from PRD ยง8.1 fire in the code. This is the followthrough on Law 2.

| Event (from PRD ยง8.1) | Where it fires | Payload schema |
|---|---|---|
| `event_registered` | `EventsService.register()` (backend) | `{ event_id, user_id, channel, paid_amount, ts }` |

Dashboard / Datadog notes: <which dashboard surfaces these; any new metrics derived>.

## 8. Integration Points & Dependencies

External systems and internal services this design touches. For non-trivial integration flows, include a mermaid `sequenceDiagram`.

```mermaid
sequenceDiagram
    participant App as Our Service
    participant Auth as 3rd-party Auth
    participant API as 3rd-party API
    App->>Auth: Authenticate
    Auth-->>App: Token
    App->>API: Request with token
    API-->>App: Response
```

| Dependency | Why | Failure mode handling |
|---|---|---|
| <3rd-party service> | <auth / payment / etc.> | <retry, fallback, alert> |
| <internal service> | <โ€ฆ> | <โ€ฆ> |

**Cross-repo coordination.** If 2+ repos change together, name the merge order and any version-gating:

1. <repo A> ships first (additive change, backwards-compatible).
2. <repo B> ships second (consumes the new endpoint).

## 9. Failure Modes & Error Handling

For each row in PRD ยง6 (Edge cases & error states), state the technical handling:

| Scenario (PRD ยง6) | Technical handling |
|---|---|
| <duplicate name> | DB unique index โ†’ 409 from API โ†’ frontend shows inline validation with PRD's exact text |
| <3rd-party API failure> | retry 3ร— exp-backoff โ†’ fallback to <X> โ†’ alert to <Y> channel |
| <webhook delivery fails> | <โ€ฆ> |

## 10. Breaking Changes

Anything that requires coordination beyond a normal deploy. Skip the section if there are none.

- <e.g. "New required field on `users` collection โ€” backfill script in step ยง13.">
- <e.g. "Adds new collection โ€” needs Mongo Prod creation by DevOps.">

## 11. Rollout

- **Feature flag:** <name, default state, who flips, what triggers the flip>
- **Migration / backfill:** <needed? script? data shape?>
- **Phased rollout:** <if any โ€” by tenant, by region, by user segment>
- **Rollback plan:** <how to disable without code deploy>

## 12. Testing Strategy

- **Unit:** <what โ€” list the load-bearing tests, not "we'll write tests">
- **Integration / E2E:** <mapped to PRD ยง9 Acceptance Criteria โ€” every Given/When/Then becomes an integration test>
- **Manual / QA:** <what needs human eyes โ€” RTL render, accessibility flows, etc.>
- **Data fidelity (when the feature reads existing data):** validate against **production-like sampled data** (a read-only sample of the real source), not only a local seed. A seed can mask the real shape โ€” clean codes vs noisy free-text, an inverted gross/net relationship, or a "source" field that is near-empty in production. State the source field/query, that it is populated/meaningful in real data, and the data-owner sign-off. <what real-data check, against which source>

## 13. Task Breakdown

Each task is small enough to estimate. Each becomes a **child GitHub Issue** linked to the ClickUp parent (`clickup_parent` in frontmatter) via `/breakdown` once approved.

| # | Task | Repo | Effort | Risk | Depends on | Child CU-id |
|---|---|---|---|---|---|---|
| 1 | Add `<entity>` schema + migration | `backend-services` | M | Low | โ€” | (filled by `/breakdown`) |
| 2 | Expose `POST /api/v1/<โ€ฆ>` endpoint | `backend-services` | S | Med | #1 | โ€ฆ |
| 3 | Add admin page to dashboard | `organization-dashboard` | M | Low | #2 | โ€ฆ |
| 4 | Wire analytics events | `backend-services` | XS | Low | #2 | โ€ฆ |

**Effort scale (rough):** XS = <1 day ยท S = 1-3 days ยท M = up to 1 week ยท L = 1-2 weeks ยท XL = up to 1 month.

**Risk:** Low / Medium / High. Anything High needs a mitigation noted in ยง15.

## 14. Risks & Alternatives Considered

- **Risk:** <โ€ฆ> โ†’ **Mitigation:** <โ€ฆ>
- **Risk:** <โ€ฆ> โ†’ **Mitigation:** <โ€ฆ>

- **Alternative considered:** <approach Y> โ†’ **Rejected because:** <โ€ฆ>
- **Alternative considered:** <approach Z> โ†’ **Rejected because:** <โ€ฆ>

## 15. Open Questions for the Build Stage

These are the unknowns that the build itself will resolve (NOT P0 blockers โ€” those went back to the PRD).

| # | Question | Owner | Resolution path |
|---|---|---|---|
| 1 | <โ€ฆ> | <eng> | <e.g. "spike during task #2"> |

## 16. Definition of Done

This is the **feature-level** DoD โ€” checked once across the whole feature. Each task/PR also carries its own engineering checklist; see [`definition-of-done.md`](/methodology/methodology-definition-of-done) (rendered into every GitHub Issue, enforced by [`process-guardian`](/agents/process-guardian)). The feature is Done only when every task is Done **and** every box below is checked.

- [ ] All **P0** acceptance criteria from PRD ยง9 pass.
- [ ] Code reviewed and merged on every affected repo.
- [ ] Automated tests written and passing (unit + integration per ยง12).
- [ ] Every added/changed HTTP endpoint is saved in the R&D Postman workspace with a sample request + saved response example (per-task DoD ยง4).
- [ ] UI matches the prototype across **all states** (default / loading / empty / error / success / disabled).
- [ ] Renders correctly in RTL and on mobile + desktop (where in scope).
- [ ] All analytics events from PRD ยง8.1 fire correctly, verified in the (vendor-neutral) observability stack.
- [ ] Feature flag wired; verified on and off.
- [ ] Accessibility: keyboard navigable, screen-reader labels present.
- [ ] No P0/P1 bugs open.
- [ ] PM sign-off against PRD acceptance criteria.
- [ ] Docs / changelog updated where relevant.