Skip to content
BitSentry

Command Palette

Search for a command to run...

Back to Projects

Technical Architecture

Note

This document was automatically translated from Spanish by AI and may contain errors. The original Spanish version is the authoritative source.

SentryQA is a TypeScript monorepo organized in 5 packages with clear roles and well-defined dependencies. The main flow is: CLI init → Vite plugin → Runtime in Shadow DOM → Core models → Markdown persisted.

Monorepo Structure

textCODE / BLOCK
Loading syntax...
10 LINES / PLAIN TEXT UTF-8

Package Manager

  • pnpm 10.11.0 with workspaces
  • Node 20.19.3 (engines: >=20)
  • volta for runtime version locking
    • jsonCODE / BLOCK
    Loading syntax...
    7 LINES / PLAIN TEXT UTF-8

    Package Dependencies

    `@sentryqa/core`

    jsonCODE / BLOCK
    Loading syntax...
    6 LINES / PLAIN TEXT UTF-8

    Responsibility: Deterministic schemas, Markdown codec, rectangle geometry, anchors (DOM locators), context formatting for AI.

    Key exports:

  • models.ts — All Zod schemas (Issue, Selection, Viewport, Target, etc.)
  • codec.ts — serializeIssueMarkdown() / parseIssueMarkdown()
  • geometry.ts — rectSchema, containment/overlap calculations
  • anchors.ts — Robust selector generation (id, class, structural)
  • formatter.ts — formatAiContext() for clipboard

    • Hardcoded limits in models.ts:

    typescriptCODE / BLOCK
    Loading syntax...
    8 LINES / PLAIN TEXT UTF-8

    `@sentryqa/runtime`

    jsonCODE / BLOCK
    Loading syntax...
    5 LINES / PLAIN TEXT UTF-8

    Responsibility: Framework-agnostic runtime in Shadow DOM, UI (toolbar, panel, markers), DOM capture, Layout/Wireframe mode.

    Key exports:

  • boot.ts (195KB) — Runtime bootstrapping, Shadow DOM mounting
  • capture.ts — Element/region capture with privacy sanitization
  • store.ts — Local state, issue filtering, revision management
  • layout-runtime.ts — Layout/Wireframe runtime with abstract blocks
  • overlay.ts / overlay-visual.ts — Overlay rendering in Shadow DOM
  • markers.ts — Visual markers (#1, #2...) re-anchoring on reload

    • Framework adapter pattern:

    typescriptCODE / BLOCK
    Loading syntax...
    12 LINES / PLAIN TEXT UTF-8

    `@sentryqa/react`

    jsonCODE / BLOCK
    Loading syntax...
    6 LINES / PLAIN TEXT UTF-8

    Responsibility: Optional React adapter using React Fiber to enrich metadata:

  • Component name
  • Component path in tree
  • Lexical fallback when Fiber is unavailable or version-gated

    • Main export:

    typescriptCODE / BLOCK
    Loading syntax...
    6 LINES / PLAIN TEXT UTF-8

    The adapter is version-gated: only activates when it detects compatible React. If it fails, it degrades to mode: 'lexical'.

    `@sentryqa/vite`

    jsonCODE / BLOCK
    Loading syntax...
    12 LINES / PLAIN TEXT UTF-8

    Responsibility: Dev-only Vite plugin that:

  • 1.Injects runtime in Shadow DOM
  • 2.Instruments JSX to add data-sentryqa-component
  • 3.Exposes bridge filesystem → runtime
  • 4.Security middleware (nonce, referer, traversal, size bounds)
  • 5.Filesystem watcher with event coalescing

    • Key exports:

  • plugin.ts — Main Vite plugin with sentryQa()
  • transform.ts — JSX transform injecting metadata
  • storage.ts — Filesystem bridge (read/write issues)
  • middleware.ts — Bridge request validation and bounds
  • git.ts — Reading branch, commit, dirty status
  • watcher.ts — Watching .sentryqa/ with coalescing

    • Plugin API:

    typescriptCODE / BLOCK
    Loading syntax...
    6 LINES / PLAIN TEXT UTF-8

    Transform JSX (simplified):

    typescriptCODE / BLOCK
    Loading syntax...
    18 LINES / PLAIN TEXT UTF-8

    `sentryqa` (CLI)

    jsonCODE / BLOCK
    Loading syntax...
    12 LINES / PLAIN TEXT UTF-8

    Responsibility:

  • 1.npx sentryqa init — Automatic stack detection, plugin injection
  • 2.sentryqa mcp — MCP stdio exposure for Layout Mode to agents
  • 3.Destinations and auth (GitHub, Jira Cloud, local)

    • Init command:

    typescriptCODE / BLOCK
    Loading syntax...
    8 LINES / PLAIN TEXT UTF-8

    MCP stdio for Layout Mode:

    typescriptCODE / BLOCK
    Loading syntax...
    17 LINES / PLAIN TEXT UTF-8

    End-to-End Data Flow

    Init → Development

    mermaidCODE / BLOCK
    Loading syntax...
    10 LINES / PLAIN TEXT UTF-8

    Issue Capture

    mermaidCODE / BLOCK
    Loading syntax...
    10 LINES / PLAIN TEXT UTF-8

    Layout Mode → MCP

    mermaidCODE / BLOCK
    Loading syntax...
    8 LINES / PLAIN TEXT UTF-8

    Architecture Decisions

    Shadow DOM for Isolation

    The runtime is mounted in a Shadow DOM host to:

  • 1.Isolate styles — Doesn't affect host CSS
  • 2.Avoid collisions — IDs, classes, event listeners
  • 3.Control lifecycle — Clean mount/unmount
  • 4.Zero in production — Vite build removes the plugin completely
    • typescriptCODE / BLOCK
    Loading syntax...
    7 LINES / PLAIN TEXT UTF-8

    Zod for Deterministic Validation

    All data crossing bridges (filesystem → runtime, MCP → layout-store) passes through strict Zod schemas:

    typescriptCODE / BLOCK
    Loading syntax...
    14 LINES / PLAIN TEXT UTF-8

    Benefits:

  • Fail fast — Invalid data on bridge is rejected
  • Living documentation — Schema IS the documentation
  • TypeScript inference — Issue type derived from schema
  • Bounds — max(), min(), regex() prevent DoS

    • Markdown as Source of Truth

    The persisted issue is Markdown YAML frontmatter:

    markdownCODE / BLOCK
    Loading syntax...
    11 LINES / PLAIN TEXT UTF-8

    Why Markdown:

  • 1.Human-readable — Git diff is readable
  • 2.Versionable — Git tracks changes
  • 3.Edit-friendly — Manual edit supported
  • 4.Portable — Any editor works
  • 5.Deterministic codec — parse() ↔ serialize() idempotent

    • Privacy-First Design

    Multiple layers of protection:

  • 1.Runtime sanitization — Inputs redacted, snippet truncated
  • 2.Middleware bounds — Size bounds, traversal checks, method validation
  • 3.Whitelisted styles — Only relevant styles (layout, flex, grid, typography)
  • 4.Control attributes — data-sentryqa-redact / data-sentryqa-ignore
  • 5.No network — Runtime doesn't make requests
  • 6.No screenshots — Doesn't capture bitmap
    • typescriptCODE / BLOCK
    Loading syntax...
    4 LINES / PLAIN TEXT UTF-8

    Optional React Fiber Adapter

    The React adapter is decoupled from runtime:

    typescriptCODE / BLOCK
    Loading syntax...
    2 LINES / PLAIN TEXT UTF-8

    This allows:

  • Framework-agnostic runtime — Future adapters for Vue, Svelte
  • Graceful degradation — If Fiber fails, fallback to lexical
  • No React dependency in core — Core remains framework-agnostic

    • Testing Strategy

    Unit Tests (Vitest)

    textCODE / BLOCK
    Loading syntax...
    6 LINES / PLAIN TEXT UTF-8
    bashCODE / BLOCK
    Loading syntax...
    1 LINES / PLAIN TEXT UTF-8

    Integration Tests

    textCODE / BLOCK
    Loading syntax...
    3 LINES / PLAIN TEXT UTF-8

    E2E Tests (Playwright)

    textCODE / BLOCK
    Loading syntax...
    5 LINES / PLAIN TEXT UTF-8
    bashCODE / BLOCK
    Loading syntax...
    1 LINES / PLAIN TEXT UTF-8

    Acceptance Suite

    bashCODE / BLOCK
    Loading syntax...
    2 LINES / PLAIN TEXT UTF-8

    Executes:

  • 1.Frozen offline install
  • 2.Chromium E2E tests (4 flows)
  • 3.Vitest suites (17 files / 64 tests)
  • 4.Typecheck across 6 packages
  • 5.Builds all packages
  • 6.Package tarball checks (5 packages)
  • 7.Production artifact/preview cleanliness
  • 8.Transient issue/report cleanup

    • Monorepo Scripts

    jsonCODE / BLOCK
    Loading syntax...
    14 LINES / PLAIN TEXT UTF-8

    Limits and Bounds

    Limits are in @sentryqa/core/models.ts and apply to all bridges:

    ConceptLimit
    Blocks in Layout32
    Prompt length4_000 chars
    Artifact bytes256 KiB
    Wireframe depth8 levels
    Wireframe children per block16
    Selector max length512 chars
    DOM path depth32 elements
    Styles whitelisted32 properties
    DOM snippet truncated400 chars
    Layout session assets32 items

    This prevents:

  • DoS from giant payloads
  • CPU abuse in geometry calculations
  • Memory leaks from infinite arrays
  • Rejection of invalid bridge requests

    • Technical Roadmap

    MVP (Current)

  • ✅ Core schemas + Markdown codec
  • ✅ Runtime Shadow DOM
  • ✅ React Fiber adapter
  • ✅ Dev-only Vite plugin
  • ✅ CLI init
  • ✅ MCP stdio for Layout Mode
  • ✅ Privacy bounds
  • ✅ E2E coverage
  • ✅ Acceptance suite passing

    • Future (post-MVP)

  • Vue / Svelte adapters
  • Improved source mapping (source maps)
  • Fuzzy selector matching for re-anchoring
  • Remote update/delete/sync in GitHub/Jira
  • More destinations (Linear, Azure DevOps)
  • Improved layout mode (grid, snap, constraints)

    • Conclusion

    SentryQA is a well-structured TypeScript monorepo with 5 packages with clear roles, minimal dependencies, explicit bounds, and solid testing coverage. The architecture prioritizes:

  • Isolation — Shadow DOM, framework-agnostic core
  • Determinism — Zod schemas everywhere
  • Privacy — Multi-layer bounds, no network
  • Portability — Markdown source of truth
  • Zero production footprint — Dev-only Vite plugin

    • For recruiters: this project demonstrates experience with TypeScript monorepos, Vite plugin development, Shadow DOM, React Fiber internals, testing automation, and design of bounded privacy-first APIs.