Skip to content

07. The Diagnostic Protocol: A Medical Model for Software Health

"Codebases, like bodies, naturally drift toward entropy (disease). Only constant diagnostics (vital signs) can ensure longevity."

1. The Golden Architecture Philosophy

In the Singular Dream architecture, we reject the notion of "Stale Documentation." A system that cannot diagnose itself is a system that is dying.

We have adopted a Medical Model for software maintenance: * Anatomy: The Codebase Structure (Modules, Entities). * Physiology: The Runtime Behavior (Capabilities, Flows). * Immunology: The Security Layer (Guards, RBAC).

The "Living MRI" Standard

Instead of writing manual architecture docs that rot, we embed "Contrast Dye" (Tags) directly into the code. We then run an "MRI Scanner" (Indexer) to generate a real-time 3D map of the system's health.

2. The Toolchain (The Hospital)

Our scripts/diagnostics/ suite constitutes the hospital infrastructure.

💉 Phase 1: Contrast Injection (inject_dye.ts)

  • Analogy: "Prepping the patient."
  • Function: Scans the codebase for "Dark Matter" (code that is untagged and invisible).
  • Action: Injects standardized JSDoc tags (@cap, @entity) into Services and Schemas.
  • Industry Standard: Aligns with "Architecture as Code" principles (e.g., Swimm, ArchUnit), ensuring that Intent is co-located with Implementation.

🩻 Phase 2: The MRI Scanner (perform_mri.ts)

  • Analogy: "Taking the image."
  • Function: Parses the tags to generate the Domain Architecture Bible (06_DOMAIN_ARCHITECTURE.md).
  • Capabilities:
    • Anatomical Scan: Maps Domain > Module > Capability.
    • Security Scan: Detects @guard tags (RBAC/Auth).
    • Privacy Scan: Detects ⚠️ @pii data fields.
    • Self-Diagnosis: Indexes the toolchain itself.

🔬 Phase 3: Clinical Analysis (clinical_analysis/)

  • Analogy: "The Lab Results."
  • Function: Deterministic verification scripts (Unit/Integration tests).
  • Compliance: Ensures that the "Patient" (Code) matches the "Medical Record" (Architecture).

3. Compliance & Governance

Detection of "Tumors" (Architectural Drift)

Untagged code is a tumor—uncontrolled growth that the system doesn't know about. * Detection: The inject_dye tool reports "Candidates" (untagged files). * Policy: CI/CD pipelines fail if "Dark Matter" exceeds 5%.

Detection of "Infection" (Security Gaps)

  • Detection: The MRI Scanner highlights Capabilities without @guard tags.
  • Review: The "Radiologist" (Developer/Admin) reviews the report to ensure no Accounting capability is exposed without RBAC.

4. How to Use

For Developers (The General Practitioner)

  1. Write Code: Create a new Service method.
  2. Inject Dye: Run pnpm tsx scripts/diagnostics/inject_dye.ts --module=my-module --apply.
  3. Check Vitals: Run pnpm tsx scripts/diagnostics/perform_mri.ts.
  4. Verify: Check documentation/06_DOMAIN_ARCHITECTURE.md to see your new organ "light up."

For Architects (The Chief Surgeon)

monitor documentation/diagnostics/history/. Compare MRI-Jan01 vs MRI-Feb01 to track the health trajectory of the patient.