Architecture and module boundaries#
SnagBadger is one versioned repository organized by product area and deep module. A module owns a useful public interface and keeps its implementation private. Consumer imports cross supported entries, not private folders.
Current responsibilities#
| Area | Owns |
|---|---|
sdk/reporting | Portable bug-report processing, reviewed bundles/providers and optional reporting UI |
sdk/capture | Portable evidence/interaction types; collector implementation remains future work |
sdk/embedding | Reserved integration surface, currently without a finished widget |
agent-testing/catalog | Resolved Markdown definition/section semantics and selection |
agent-testing/execution | Runtime coordination, hooks, retained progress and lifecycle |
agent-testing/reporting | Results/attempts/comments, promotion and optional HTML run viewer |
examples | Maintained host scenarios and sample test catalog |
tooling / testing | Repository quality, workflow helpers and cross-module/browser acceptance |
The foundation describes accepted ownership and intended expansion. Do not turn its future structure into claims of shipped capabilities; project status separates them.
Preserve loading boundaries#
Functions-only consumers must not eagerly load React, CSS, DOM globals, server libraries, or unrelated integrations. Optional bundle/rendering/UI entries remain separate. Use public-entry reference for supported imports.
Register new module ownership, entry/dependency direction and runtime environment in architecture policy with meaningful checks. Avoid empty packages created only to match a diagram. Architecture enforcement and built consumer checks explain the guardrails.
Decisions and vocabulary#
GitHub issues are canonical product decisions; repository architecture docs are linked assets. Use the glossary for domain terms, and relevant ADRs when present. A prototype's appearance or inferred behavior cannot resolve an open product decision.
Technology direction is strict TypeScript, Node LTS, pnpm, Vite, optional React UI, Vitest and real-browser checks. All versioned artifacts share one repository version. Quality checks apply to prototypes as well as production modules.