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 846+ API endpoints with auto-generated content from OpenAPI specifications that sync nightly from production. Live site: https://docs.rhombus.com API source: https://api2.rhombussystems.com/api/openapi/public.json

​
Development Commands

All commands should be run from the root directory unless otherwise specified.

​
Local Development

# Start Mintlify dev server (must run from root directory where docs.json is)
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 (can run from root or docs/)
./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

​
Repository Structure

/ (root - where docs.json lives, run mint dev from here)
├── docs.json              # Mintlify config (4 product categories: General, Advanced, Low Code/No Code & AI, API Reference)
├── *.mdx                  # Documentation pages (root level: index.mdx, documentation-mcp.mdx, changelog.mdx)
├── api-reference/         # API documentation
│   ├── openapi.json       # Full OpenAPI spec (generated nightly)
│   └── openapi-split/     # Split specs by category for AI tools
├── implementations/       # Advanced implementation guides (organized by product: Cameras, Access Control, etc.)
├── low-code-no-code/     # No-code/low-code integration guides (Zapier, Make.com, N8N)
├── scripts/              # Automation scripts
└── .github/workflows/    # Automated update workflows
Important: All MDX files are in the root directory, not in a docs/ subdirectory. The mint dev command must be run from the root where docs.json is located. The documentation uses a 4-category navigation system:
  1. General: Getting started content (index.mdx)
  2. Advanced: Product-specific implementation guides organized by:
    • Alarm Monitoring (placeholder for future content)
    • Cameras (streaming, video player, advanced implementation)
    • IoT Sensors (placeholder for future content)
    • Access Control (QR code access control)
    • More (backup footage, webhook listener)
  3. Low Code / No Code & AI: Integration guides for Zapier, Make.com, N8N, and Documentation MCP
  4. API Reference: Complete API endpoint documentation with live testing (auto-generated from OpenAPI spec)

​
Architecture & Automation

​
OpenAPI Sync Workflow

  1. GitHub Action runs daily at 2:00 AM UTC
  2. Fetches latest spec from production API
  3. Updates api-reference/openapi.json
  4. Mintlify automatically regenerates endpoint pages
  5. Navigation is managed in the large docs.json file

​
docs.json Structure

  • Large file: 107KB+ with 846+ endpoint references
  • Format: JSON with nested navigation groups
  • API endpoints: Referenced as "api-reference/openapi.json {method} {path}"
  • Schema reference: https://mintlify.com/docs.json

​
Content Types

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

​
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”)
  • 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

​
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
  • Add explanatory comments for complex logic

​
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

  • Skip frontmatter on any MDX file
  • Use absolute URLs for internal links
  • Include untested code examples
  • Make assumptions - always ask for clarification
  • Create duplicate content without strategic reason
  • Modify automated workflows without understanding impact