Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
139 lines (104 loc) · 6.61 KB

CONTRIBUTING.md

File metadata and controls

139 lines (104 loc) · 6.61 KB
Raw

🛠️ Contributing to marko1olo/stomchat

Engineering Mandate, Architectural Invariants & Contribution Standard
Maintained by the Жирняк & Адольф Петушков Engineering Syndicate
Technology Foundation: TypeScript / Node.js / WebSocket / Vector Embeddings / Fastify

📑 Table of Contents

  1. 🏛️ Architectural Overview & Data Flow
  2. 📐 Strict Domain Invariants
  3. 💻 Development Toolchain & Local Environment
  4. 🧪 Testing Strategy & Verification Pipeline
  5. 💎 Code Standards & Anti-Patterns
  6. 🚀 Pull Request Protocol & Review Workflow
  7. 👥 Syndicate Governance & Attribution

🏛️ 1. Architectural Overview & Data Flow

StomChat Omnichannel Clinical Knowledge & Telemedicine Triage is engineered for maximum performance, deterministic state transitions, and zero computational slop. All contributions must respect existing subsystem boundaries and data flows:

graph TD
    A[Patient Chat Client] -->|WebSocket Connection| B[Fastify WS Gateway]
    B -->|Symptom Extraction| C[Vector Embedding Engine]
    C -->|Cosine Search > 0.78| D[(Clinical Knowledge Base)]
    D -->|Verified Medical Context| E[Safety Guardrail Classifier]
    E -->|Doctor Escalation Signal| F[Doctor Dashboard]
    E -->|Triage Guidance Payload| A
Loading

1.1 Core Subsystems

  • Primary Compute / Domain Engine: Handles low-latency calculations, domain solvers, and state mutations.
  • Validation & Boundary Layer: Enforces strict typing, schema assertions, and input sanitization before payloads enter the internal core.
  • Presentation & Stream Sinks: Zero-allocation rendering, audio synthesis, or serialization buffers feeding client viewports.

📐 2. Strict Domain Invariants

Every pull request is automatically audited against these immutable project invariants. If any invariant is violated, the PR will be rejected:

1. Clinical Safety Gate

  • Formal Requirement: Symptom classifier must never provide definitive diagnoses; all triage outputs mandate professional doctor review.
  • Verification Protocol: Automated unit test assertion + mathematical boundary check.
  • Failure Mode: Immediate build rejection; PR cannot be approved without meeting this invariant.

2. WebSocket Heartbeat Protocol

  • Formal Requirement: Real-time channels must maintain 30s ping-pong keepalives with automated reconnect backoff.
  • Verification Protocol: Automated unit test assertion + mathematical boundary check.
  • Failure Mode: Immediate build rejection; PR cannot be approved without meeting this invariant.

3. Vector Similarity Threshold

  • Formal Requirement: RAG retrieval chunks below 0.78 cosine similarity must be rejected as unverified.
  • Verification Protocol: Automated unit test assertion + mathematical boundary check.
  • Failure Mode: Immediate build rejection; PR cannot be approved without meeting this invariant.

4. Doctor Takeover Priority

  • Formal Requirement: Human doctor intervention instantly revokes bot response privileges on the active session.
  • Verification Protocol: Automated unit test assertion + mathematical boundary check.
  • Failure Mode: Immediate build rejection; PR cannot be approved without meeting this invariant.

💻 3. Development Toolchain & Local Environment

3.1 Environment Prerequisites

  • Primary Runtime: TypeScript / Node.js / WebSocket / Vector Embeddings / Fastify
  • Git with configured GPG signing keys
  • Static Analysis & Linters matching project versions

3.2 Setup Procedure

# 1. Clone the repository
git clone https://github.com/marko1olo/stomchat.git
cd stomchat

# 2. Check out target working branch
git checkout main

# 3. Install dependencies & initialize toolchains
npm install || cargo check || dotnet restore || pip install -r requirements.txt || make preflight

# 4. Execute the complete test suite
npm test || pytest || dotnet test || make test

🧪 4. Testing Strategy & Verification Pipeline

Every non-trivial PR must contain empirical verification evidence. We do NOT accept "tested manually and looks fine":

  1. Unit & Invariant Tests: Must explicitly verify the mathematical or logical properties of the modified subsystem.
  2. Boundary & Edge-Case Sweeps: Test with zero-length inputs, extreme boundary coordinates, or adversarial configurations.
  3. Zero-Allocation Benchmarking: For render or audio frame loops, run the memory profiler to verify zero heap allocations per tick.

💎 5. Code Standards & Anti-Patterns

5.1 Exemplary vs. Forbidden Patterns

// ✅ CORRECT: Clinical Safety Score Verification
export function evaluateRAGContext(similarity: number, snippet: MedicalSnippet): VerifiedContext | null {
    if (similarity < 0.78) return null; // Reject low confidence chunks
    return { text: snippet.content, sourceId: snippet.id, doctorReviewRequired: true };
}

5.2 Anti-Patterns Blacklist

  • ❌ No AI Slop Comments: Avoid decorative fluff like // This function handles calculating the result. Comment why, never what.
  • ❌ No Type Bypasses: Never use any, unknown casts without runtime assertions, or unchecked pointer arithmetic.
  • ❌ No Unbounded Memory Growth: Always provide explicit upper bounds on caches, array allocations, and event queues.

🚀 6. Pull Request Protocol & Review Workflow

graph TD
    A[Fork Repository] --> B[Create Descriptive Branch /feat or /fix]
    B --> C[Implement Code & Satisfy Invariants]
    C --> D[Run Full Test Suite & Linters]
    D --> E[Submit PR with Benchmark Proof]
    E --> F[Syndicate Adversarial Code Review]
    F -->|Approved| G[Rebase & Fast-Forward Merge]
    F -->|Corrections Needed| C
Loading
  1. Branch Naming: feat/<subsystem>-<feature>, fix/<subsystem>-<bug>, perf/<subsystem>-<optimization>.
  2. Commit Standard: Conventional Commits format with lowercase scope (feat(core): implement SIMD acceleration).
  3. PR Description: Include root-cause analysis, benchmark numbers (before/after), and test commands executed.

👥 7. Syndicate Governance & Attribution

This project is authored and curated under the oversight of the Жирняк & Адольф Петушков Engineering Syndicate. All contributions merged into this repository will be credited to their authors while maintaining syndicate licensing integrity.