design-first

Design the shape before writing the code. The pass ends in a **design sketch** the user approves; implementation does not start until it does. Aim for **deep modules** placed at clean **seams** — so callers get leverage, maintainers get locality, and tests get a surface to push against. This is a design pass, not an implementation plan. Decide *what shape the code takes and why*; leave line-level rules to **code-guidelines** and test structure to **test-guidelines**. ## When to run Run for work where the shape is a real decision: - A new feature or a new integration - A change to the public barrel (`packages/core/src/js/index.ts`) or a public option in `options.ts` — it cascades to every downstream user and the API report - A change to a **codegen spec** (`src/js/NativeRNSentry.ts`, `*NativeComponent.ts`) or anything crossing the JS↔native bridge — the ABI must move in lockstep across JS/iOS/Android - Any moment you are choosing where a seam goes, or how a module is shaped to be testable Skip it — and say you are skipping it — for one-line fixes, localized bug fixes with obvious placement, and refactors that change no interface. ## Vocabulary Use these terms exactly in the sketch — consistent language is what makes the design legible across sessions. Don't substitute "component," "service," or "layer." - **Module** — anything with an interface and an implementation: a function, a factory, a class, a file. - **Interface** — everything a caller must know to use it correctly: the signature, plus invariants, ordering, error modes, required config. - **Deep module** — a lot of behavior behind a small interface. The goal. A **shallow** module has an interface nearly as complex as its implementation — avoid it. - **Seam** — the place where you can swap behavior without editing in that place. Where an interface lives, and where a test double crosses. In this SDK the biggest seam is the `NATIVE` wrapper (`src/js/wrapper.ts`) between JS and native. - **Adapter** — a concrete thing satisfying an interface at a seam. Two checks settle most design questions: - **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through — don't build it. If complexity reappears across N callers, it earns its keep. - **The interface is the test surface.** Callers and tests cross the same seam. If you need to test *past* the interface, the module is the wrong shape. ## The design pass ### 1. Frame the change State the behavior the change introduces, in the domain's own words. Name the surface(s) it lands in — JS, Android, iOS, bridge — and read the relevant `AGENTS.md` (root, `packages/core/`, `packages/core/android/`, `packages/core/ios/`). **Find the nearest well-shaped precedent and align to it.** The codebase has almost certainly solved something adjacent — locate its *best* current example and match it, or improve on it deliberately and say why. The TurboModule subsystem (`turbomodule/` + thin `integrations/turboModuleContext*.ts` wiring) is a strong precedent for a cohesive feature that touches JS, native, and the bridge; the integration factory in `integrations/nativelinkederrors.ts` is the precedent for a plain JS integration. ### 2. Shape the modules Decide the modules and where their seams go. Prefer fewer, deeper modules over many shallow ones. For each module, name its interface — not just the signature, but the invariants and error modes a caller must know. Run the deletion test on anything you suspect is a pass-through. Decide where the code lives as part of shaping it — a **locality** call: co-locate what changes together so one change stays directory-local. - A cohesive subsystem owns its model, lifecycle, and pipeline as one **concept** — group it in its own dir (like `turbomodule/`), and let the `integrations/` file be thin wiring. `integrations/` is a type-bucket, not a home for a subsystem's logic. - Native code belongs behind the bridge seam under `packages/core/android/` and `packages/core/ios/`; JS features *call* it via `NATIVE`, they don't embed native code. - **If you can't name the concern a piece serves, that's a smell** — it's doing two things, or belongs to a concept you haven't named. ### 3. Design for testability A seam exists so a test can cross it (test-guidelines builds the fakes there). Three rules make that possible: - **Accept dependencies, don't create them.** A module that reaches for `NativeModules.RNSentry` itself can't be faked; one that receives the bridge (or goes through the `NATIVE` seam a test can mock) can. - **Keep the platform/arch branch at the edge.** Push `Platform.OS` / `isTurboModuleEnabled()` decisions to a thin boundary so the core logic is arch-agnostic and unit-testable without simulating a device. - **Make the observable output the contract.** Tests assert on the produced event/envelope/resolved value, not on private state — so the design must route results through the interface. ### 4. Account for the bridge, up front If the change crosses the bridge, decide *now* (not during implementation): - What the payload shape is and whether it is **codegen-expressible** or must be an `Object` validated natively (see `code-guidelines/references/native-bridge.md`). - Whether it's an **ABI change** and how JS/iOS/Android land in lockstep while staying backward-compatible with older cached native binaries. - How it behaves when `enableNative` is false or the module isn't linked. - What crosses regarding **PII** and how it's gated. ### 5. Write the sketch and get sign-off Produce, in the conversation: the modules and their interfaces; where each lives and why (locality); the seams and what fakes cross them; the bridge/ABI decisions; and what you deliberately chose *not* to build (deletion-test casualties). Get the user's approval before implementing, then hand off to **code-guidelines** + **test-guidelines**.