Skip to main content

​
CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

​
Project Overview

This is the official Rhombus API documentation site built with Mintlify. It documents all API endpoints with auto-generated content from OpenAPI specifications that sync nightly from production. Live site: https://api-docs.rhombus.community/ API source: https://api2.rhombussystems.com/api/openapi/public.json The Rhombus API is currently unversioned — a single version ("version": "1.0") serves all consumers. See VERSIONING.md for the plan to introduce versioning when breaking changes occur.

​
Prerequisites

  • Node.js 19+
  • Mintlify CLI (npm i -g mint)
  • Python 3.11+ (for maintenance scripts)

​
Development Commands

All commands should be run from the root directory where docs.json lives.

​
Local Development

# Start Mintlify dev server
mint dev

# Start on custom port
mint dev --port 3333

# Validate all links
mint broken-links

# Update Mintlify CLI
mint update

​
Maintenance Scripts

# Update OpenAPI spec from Rhombus API
./scripts/update-openapi.sh

# Update AI context files (llms.txt, llms-full.txt)
python3 scripts/update-llms-files.py

# Generate endpoint documentation from OpenAPI spec
python3 scripts/generate-endpoint-docs.py

# Update docs.json navigation structure
python3 scripts/update-docs-navigation.py

# Build hierarchical API navigation from OpenAPI spec
python3 scripts/build-api-navigation.py

# Add tag descriptions to OpenAPI spec
python3 scripts/enrich-openapi-tags.py

# Add x-codeSamples to key endpoints
python3 scripts/add-code-samples.py

# Check content quality across docs
python3 scripts/check-content-quality.py

# Detect changes in OpenAPI spec
python3 scripts/detect_openapi_changes.py

# Generate and insert changelog entries
python3 scripts/generate_changelog_entry.py
python3 scripts/insert_changelog_entry.py

​
Automation (GitHub Actions)

The nightly OpenAPI sync (.github/workflows/sync-openapi.yml) runs at 9 AM UTC and follows this pipeline:
  1. Fetches latest spec from https://api2.rhombussystems.com/api/openapi/public.json
  2. detect_openapi_changes.py — compares old/new specs, produces a change report JSON
  3. Copies new spec to api-reference/openapi.json
  4. build-api-navigation.py — rebuilds API Reference navigation in docs.json
  5. generate_changelog_entry.py + insert_changelog_entry.py — adds changelog entry
  6. Creates a pull request (not a direct commit) on branch automated/openapi-sync
Can also be triggered manually via workflow_dispatch.

​
Repository Structure

/ (root - run mint dev from here)
├── docs.json              # Mintlify config (3 tabs: Guides, Integrations, API Reference)
├── *.mdx                  # Root-level pages (index, documentation-mcp, changelog, resources, webhooks)
├── api-reference/         # API documentation
│   └── openapi.json       # Full OpenAPI spec
├── implementations/       # Implementation guides (Cameras, Access Control, Audio, etc.)
├── low-code-no-code/     # No-code/low-code integration guides (Zapier, Make.com, N8N)
├── websocket/            # WebSocket documentation (markdown, not yet in Mintlify nav)
├── snippets/             # Reusable React components (changelog-author.jsx)
└── scripts/              # Maintenance scripts
Important: All MDX files live at the repo root — there is no docs/ subdirectory. The documentation uses a 3-tab navigation system configured in docs.json:
  1. Guides: Getting started (index, resources, webhooks, changelog) + implementation guides by topic (Cameras, Access Control, Alarm Monitoring, IoT Sensors, More)
  2. Integrations: Low code / no code platforms (Zapier, Make, n8n) + AI & LLMs (Documentation MCP)
  3. API Reference: Complete API endpoint documentation with live testing (auto-generated from OpenAPI spec)

​
Architecture

​
docs.json Structure

  • Format: JSON with nested navigation groups; 107KB+ — do not hand-edit the API Reference section
  • API endpoints: Referenced as "api-reference/openapi.json {method} {path}"
  • Modifying API nav: Always use python3 scripts/build-api-navigation.py to rebuild the API Reference navigation from the OpenAPI spec. Manual edits to that section will be overwritten by the nightly sync.

​
Content Types

  1. Hand-written MDX: Implementation guides, quickstart, MCP documentation
  2. Auto-generated API docs: All endpoint pages under API Reference tab (do not manually create these)
  3. AI context files: llms.txt and llms-full.txt for AI assistants

​
Key Files

  • docs.json — Main config; 107KB+ with 846+ endpoint references. Schema: https://mintlify.com/docs.json
  • api-reference/openapi.json — Full OpenAPI spec synced from production
  • api-reference/overview.mdx — Hand-written API reference landing page
  • custom.css — Custom styling overrides
  • VERSIONING.md — Plan for introducing API versioning when breaking changes occur

​
API-Specific Conventions

  • Base URL: https://api2.rhombussystems.com
  • Media URL: https://media.rhombussystems.com (for media/streaming endpoints)
  • Authentication headers: x-auth-scheme: api-token + x-auth-apikey: YOUR_API_KEY
  • Endpoint grouping: By service area (Access Control, Camera, Climate, etc.) with subgroups: Create & Add, Get & Find, Update & Modify, Delete & Remove, Other Operations

​
Working Relationship

  • Push back on ideas when it leads to better documentation - cite sources
  • ALWAYS ask for clarification rather than making assumptions
  • NEVER lie, guess, or make up anything
  • Search for existing content before adding new pages to avoid duplication
  • Start by making the smallest reasonable changes

​
Content Standards

​
Frontmatter Requirements

Every MDX file must have: 
---
title: "Clear, descriptive page title"
description: "Concise summary for SEO/navigation"
icon: "icon-name"  # Optional
---

​
Writing Standards

  • Second-person voice (“you”)
  • Active voice and present tense
  • Prerequisites at start of procedural content
  • Test all code examples before publishing
  • Match style and formatting of existing pages
  • Include both basic and advanced use cases
  • Language tags on all code blocks
  • Alt text on all images
  • Relative paths for internal links
  • Start page content with h2 headings (h1 is generated from frontmatter title)

​
Code Example Requirements

  • Complete, runnable examples users can copy
  • Proper error handling and edge cases
  • Realistic data, not placeholders
  • Include expected outputs
  • Never include real API keys or secrets
  • Always include authentication in code examples (x-auth-apikey header)

​
Component Selection

  • Steps: Sequential instructions and procedures
  • Tabs: Platform-specific content or alternatives
  • CodeGroup: Same concept in multiple languages
  • Accordions: Progressive disclosure
  • RequestExample/ResponseExample: API endpoint docs
  • ParamField: API parameters
  • ResponseField: API responses
  • Expandable: Nested properties
Available callouts: <Note>, <Tip>, <Warning>, <Info>, <Check>

​
Git Workflow

  • NEVER use --no-verify when committing
  • NEVER skip or disable pre-commit hooks
  • Ask how to handle uncommitted changes before starting
  • Create a new branch when no clear branch exists
  • Commit frequently throughout development

​
Critical Don’ts

  • Manually edit the API Reference navigation in docs.json — use build-api-navigation.py
  • Manually create endpoint pages under API Reference — Mintlify auto-generates these from the OpenAPI spec
  • Skip frontmatter on any MDX file
  • Use absolute URLs for internal links
  • Modify the GitHub Action workflow without understanding the full sync pipeline