Overall Purpose
The Superheroes naming pattern is used for platform-level safety, observability, and communication layers that operate across many features.
- These components provide guardrails, diagnostics, or delivery guarantees used by multiple pages and APIs.
- They reduce repeated logic by centralizing risky or high-importance behavior.
- They are intentionally documented so users and developers can map feature behavior to concrete implementation points.
System Breakdown
| Superhero | Primary Role | Specific Use Case | Primary Implementation |
|---|---|---|---|
| ShadowTalon | Global PHP fault guardian | Converts uncaught runtime faults into safe JSON/HTML responses and writes dedicated rotating fault logs with correlation IDs. | html/src/Domain/ShadowTalon.php |
| Guardian | TrustedHTML DOM write guard | Sanitizes and safely inserts dynamic markup in frontend modules to reduce XSS risk and preserve CSP compatibility. | html/js/guardian.js |
| Phantom Wing | Client error collation daemon | Captures console errors/warnings and unhandled failures, then groups and exposes diagnostics for operator debugging. | html/js/phantomwing/index.php |
| Lens | Request-scoped diagnostics buffer | Collects DEV-only events, counters, and timers; supports debug panels and API payload diagnostics via ?lens=1. |
html/src/Observability/Lens.php |
| EmailGarum | Transactional mail orchestrator | Coordinates flow-specific email templates and delivery behavior for verification, recovery, and account-change workflows. | html/src/Domain/EmailGarum.php |
| Echo | ARIA cadence formatter | Echo mirrors content for assistive pathways, and her Cadence power adds strategic pauses and rhythm so narration lands clearly for screen readers, speech synthesis, braille displays, and human listeners. | html/src/Domain/AriaEcho.php |
| GoldMaster | Canonical reference examples for PayCal code, UI, tests, and architecture. | Guides humans and AI agents toward reviewed patterns before similar work starts. | golden_masters/, html/src/Domain/GoldMasterCatalog.php |
How They Work Together
- Runtime fault path: ShadowTalon catches unhandled failures and returns safe responses while preserving operator diagnostics in dedicated logs.
- Browser diagnostics path: Guardian protects DOM writes; Phantom Wing collates frontend failures; Lens provides request-level diagnostics in development surfaces.
- Account communication path: EmailGarum standardizes transactional mail composition and delegates protocol delivery to EmailTransport.
- Assistive narration path: Echo repeats semantics faithfully, while Cadence restores pacing with pauses and timing so accessibility output feels intelligible instead of rushed.
- Canonical reference path: GoldMaster records reviewed examples so future work starts from the correct PayCal pattern.
Perfect reflection. Perfect rhythm. No voice left behind.
Why This Naming Pattern Exists
Themed names are used to signal "cross-cutting system components" rather than feature-local logic.
- New contributors can quickly identify platform primitives versus page-level code.
- Operational incidents can be triaged by component area (faults, client telemetry, DOM safety, email delivery).
- Documentation can reference stable system names rather than shifting implementation details.
Verification Anchors
html/tests/Unit/ShadowTalonTest.phpverifies fault response safety and route-shape behavior.html/tests/Unit/EmailTemplateRenderTest.phpverifies transactional template rendering across email flows.html/tests/Unit/Domain/GoldMasterCatalogTest.phpverifies golden master metadata and read-only file preview behavior.- Phantom Wing and Lens behavior can be observed in DEV through dashboard diagnostics and request debug output.
Last updated: June 21, 2026.