Skip to main content

Documentation Maintenance Guide

This guide establishes the protocols and update workflows required to keep hitech-docusaurus synchronized with future changes in veridex-hitech-web-application.

1. Absolute Repository Boundary Rule​

Always remember the cardinal repository separation boundary:

  • veridex-hitech-web-application: The production application.
  • hitech-docusaurus: The documentation repository.

When documenting new features or updates, never mutate or run modifying commands inside the source application. All documentation authoring, file additions, and edits must occur strictly within hitech-docusaurus.

2. Workflows for Common Changes​

1. Adding a New Mongoose Model​

When a new model is introduced into src/lib/db/models/:

  1. Open database/models-catalog.md.
  2. Locate the appropriate functional category (or create a new section if introducing a new domain).
  3. Document the model interface, Mongoose schema options, field types, required/optional flags, default values, compound/TTL indexes, and business purpose.
  4. Open database/entity-relationships.md and update the corresponding Mermaid ER diagram with foreign key relationships.

2. Registering a New API Endpoint​

When a new route handler is added to src/app/api/:

  1. Open api-reference/endpoints.md.
  2. Add a complete endpoint specification including:
    • Route path and HTTP method.
    • Purpose and business workflow.
    • Authentication scheme (Public, Session, HMAC, Webhook Signature, or Swagger Password).
    • Headers, query parameters, and Zod request body schema.
    • 200/201 success response payload.
    • Standardized 400/401/403/429/500 error envelopes.
    • Copy-pasteable curl testing snippet.
  3. If the endpoint introduces a new authentication or transmission concept, update api-reference/rest-api-overview.md.

3. Introducing a New Environment Variable​

When a new variable is added to src/lib/env.ts:

  1. Open architecture/environment-variables.md.
  2. Add a new row to the Environment Variable Reference Table with:
    • Variable name.
    • Scope (Server-Only vs. Public Browser-Exposed).
    • Type and Zod validation rules.
    • Default value or fallback.
    • Non-sensitive example value.
    • Code subsystems referencing the variable.

4. Adding a New Insurance Line​

When expanding the insurance catalog (e.g. adding Cyber Insurance or Pet Insurance):

  1. Open insurance-catalog/catalog-overview.md.
  2. Add the canonical slug, legacy aliases, and underwriting parameters to the appropriate product table (Personal, Commercial, or Specialized).
  3. Document questionnaire routing triggers.

3. Local Verification & Docusaurus Faster Build​

Before committing documentation updates, verify that Docusaurus builds cleanly with zero broken markdown links or anchor tag mismatches:

# Navigate to the documentation workspace
cd ../hitech-docusaurus

# Execute build with Docusaurus Faster (SWC minification + SSG worker threads)
cmd /c "npm run build"

[!TIP] On Windows systems, always invoke npm scripts via cmd /c "npm run build" to avoid PowerShell execution policy restrictions.

4. Documentation Writing Guidelines​

  • Technical Grounding: Ground every statement in verified source code. Never guess or hallucinate endpoints, schema types, or configuration keys.
  • Link Integrity: Always link related files using relative markdown paths (e.g. [Models Catalog](../database/models-catalog.md)).
  • Mermaid Diagrams: Validate Mermaid syntax. Use quotes around labels with parentheses, e.g. node["Label (Details)"].
  • LaTeX Math Escaping: In standard text, always escape literal dollar signs (\$) or wrap monetary values in backticks (`$100`) to prevent KaTeX math parser corruption.