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

text
Cargando sintaxis...
🔒 BitSentry_Terminal
Ln 10, Col 1UTF-8

Package Manager

  • pnpm 10.11.0 with workspaces
  • Node 20.19.3 (engines: >=20)
  • volta for runtime version locking
    • json
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 7, Col 1UTF-8

    Package Dependencies

    `@sentryqa/core`

    json
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 6, Col 1UTF-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:

    typescript
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 8, Col 1UTF-8

    `@sentryqa/runtime`

    json
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 5, Col 1UTF-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:

    typescript
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 12, Col 1UTF-8

    `@sentryqa/react`

    json
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 6, Col 1UTF-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:

    typescript
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 6, Col 1UTF-8

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

    `@sentryqa/vite`

    json
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 12, Col 1UTF-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:

    typescript
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 6, Col 1UTF-8

    Transform JSX (simplified):

    typescript
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 18, Col 1UTF-8

    `sentryqa` (CLI)

    json
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 12, Col 1UTF-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:

    typescript
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 8, Col 1UTF-8

    MCP stdio for Layout Mode:

    typescript
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 17, Col 1UTF-8

    End-to-End Data Flow

    Init → Development

    mermaid
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 10, Col 1UTF-8

    Issue Capture

    mermaid
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 10, Col 1UTF-8

    Layout Mode → MCP

    mermaid
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 8, Col 1UTF-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
    • typescript
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 7, Col 1UTF-8

    Zod for Deterministic Validation

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

    typescript
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 14, Col 1UTF-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:

    markdown
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 11, Col 1UTF-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
    • typescript
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 4, Col 1UTF-8

    Optional React Fiber Adapter

    The React adapter is decoupled from runtime:

    typescript
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 2, Col 1UTF-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)

    text
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 6, Col 1UTF-8
    bash
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 1, Col 1UTF-8

    Integration Tests

    text
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 3, Col 1UTF-8

    E2E Tests (Playwright)

    text
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 5, Col 1UTF-8
    bash
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 1, Col 1UTF-8

    Acceptance Suite

    bash
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 2, Col 1UTF-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

    json
    Cargando sintaxis...
    🔒 BitSentry_Terminal
    Ln 14, Col 1UTF-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.