Skip to main content

HIGHFIELD — Onboarding Documentation

In one line: HIGHFIELD is an AI property-maintenance coordinator ("Alex Carter") that runs the whole repair lifecycle — tenant report → vendor → quote → approval → visit → completion → close — over email and chat, with Microsoft Business Central as its system of record.

This site is the complete, source-verified account of how HIGHFIELD works: every email path, every API and webhook, every header, every scheduled job, and every configuration knob. It is written for two readers at once — each page opens with a plain-language summary anyone can read, then drops into developer detail with file:line citations.

Everything here is traceable to the code. Where something could not be confirmed against source, it is marked ⚠️ Unverified rather than guessed.

If you're a PM / stakeholder​

Start here for what the system does and why, without the code:

  1. Overview — what HIGHFIELD is, who uses it, the value
  2. End-to-end flows — the journeys, as diagrams (the fastest way to understand the product)
  3. Communication & email — who gets contacted, when, and the safety rules
  4. Core concepts & glossary — the vocabulary
  5. Configuration — what can be turned on/off and tuned

If you're a developer​

Start here for how it's built and how to change it safely:

  1. Architecture — the agent pipeline and external systems
  2. APIs, webhooks & tools — every endpoint and every tool the LLM can call
  3. Data model — the ticket entity, lifecycle, and where data lives
  4. Auth, ownership & security — BC OAuth, approval tokens, tenancy gates
  5. Operations & runbook — deploy, rollback, failure modes
  6. Appendices — the full reference tables (headers, full inventory)

How this documentation is built​

One Markdown source (docs/) produces three outputs:

  • MkDocs Material site — mkdocs build
  • Docusaurus site — cd docusaurus && npm run build
  • Word documents — ./build-docx.sh (per-page .docx + one combined file)

See README.md in the onboarding-docs/ root for the exact commands. Edit any page in docs/, rebuild, and all three outputs update — that single-source property is the point.

Authors: keep to the portable-Markdown subset (see _authoring-cheatsheet.md) so every page renders in all three outputs. The raw discovery sweep and coverage ledger live in onboarding-docs/_inventory/.