marketplaces/docs/Diagnostics.md

Marketplace Diagnostics & Health Engine - Sprint 14

Scope

Sprint 14 adds a development-only diagnostics feature for marketplace configuration and runtime health.

Constraints respected:

• No runtime behavior changes
• No business logic changes
• No authentication changes
• No payment changes

Architecture

src/app/features/diagnostics/
  components/
    diagnostics-page.component.*
  services/
    diagnostics-logger.service.ts
  models/
    diagnostics.model.ts
  validators/
    bootstrap-diagnostics.validator.ts
    runtime-diagnostics.validator.ts
    diagnostics-health-score.util.ts
  facade/
    diagnostics.facade.ts

Health Checks

Current checks cover:

• bootstrap loaded
• tenant resolved
• runtime initialized
• theme loaded
• widget manifest loaded
• section engine reachable
• configuration engine initialized
• translations available
• required assets health

Bootstrap Validation

Current validator detects:

• missing required properties
• unknown widget types
• duplicate page/section/widget ids
• unknown layout values
• invalid feature flags
• broken page definitions
• invalid navigation targets
• missing translations in navigation label keys
• missing branding media

Runtime Validation

Current validator detects:

• missing datasource declarations for widgets that support them
• widget rendering failures from runtime diagnostics stream
• broken route expectations
• configuration fallback usage in local development
• failed image loading where DOM can observe it
• missing optional data

Severity Model

Each entry includes:

• code
• severity
• title
• description
• affected component
• suggested resolution

Levels:

• info
• warning
• error
• critical

Health Score

Simple weighted score:

• critical: -15
• error: -8
• warning: -3
• info: 0

Minimum 0, maximum 100.

Developer Page

Development-only route:

• /__diagnostics

Page shows:

• summary
• health score
• passed checks
• warnings/errors/critical counts
• detailed diagnostics entries

Logging Abstraction

DiagnosticsLoggerService stores diagnostic entries in memory.

RuntimeDiagnosticsService now keeps unknown widget events in memory for diagnostics consumption only.

No external logging integration in this sprint.

Extension Points

Future additions can plug into:

• new validators under validators/
• new runtime event collectors
• remote diagnostics export service
• monitoring integrations (Sentry, Datadog, Grafana, OpenTelemetry)
• asset/network checks
• widget render timing checks

Performance

Production route excluded.

Diagnostics work runs only on diagnostics page access in development mode.