Skip to content

Documentation Sync Process

This guide describes how to keep the Campaign Brain documentation hub synchronized with all projects.

Overview

The documentation site at docs.nominate.ai aggregates documentation from all cb* projects using symlinks. When new projects are added or existing project docs change, this process ensures everything stays in sync.

Quick Reference

# Check sync status
./scripts/check_docs_sync.sh

# Rebuild and deploy
./scripts/docs_deploy.sh

# Or just restart MkDocs service
sudo systemctl restart mkdocs

Project Inventory

Current Projects (as of 2025-12-27)

Project Description Has Docs Symlink In Nav
cbai AI/LLM integration Yes cbai-docs Yes
cbapp Campaign application Yes cbapp-docs Yes
cbdistricts Congressional districts Yes cbdistricts-docs Yes
cbdocs Executive publication Yes cbdocs-docs Yes
cbetl ETL pipelines Yes cbetl-docs Yes
cbfiles File storage & CDN Yes cbfiles-docs Yes
cbinfra Infrastructure Yes cbinfra-docs Yes
cbmesh API Mesh (WebSocket) Yes cbmesh-docs Yes
cbmodels Data analytics Yes cbmodels-docs Yes
cbpublic Public website Yes cbpublic-docs Yes
cbradio Radio advertising Yes cbradio-docs Yes
cbsurveys Survey platform Yes cbsurveys-docs Yes
cbtenant Tenant manager (this repo) Yes — Yes
cbworkflow Workflow engine Yes cbworkflow-docs Yes

All symlinks are in /home/bisenbek/projects/nominate/cbtenant/docs/:

cbai-docs -> ../../cbai/docs
cbapp-docs -> ../../cbapp/docs
cbdistricts-docs -> ../../cbdistricts/docs
cbdocs-docs -> ../../cbdocs/docs
cbetl-docs -> ../../cbetl/docs
cbfiles-docs -> ../../cbfiles/docs
cbinfra-docs -> ../../cbinfra/docs
cbmesh-docs -> ../../cbmesh/docs
cbmodels-docs -> ../../cbmodels/docs
cbpublic-docs -> ../../cbpublic/docs
cbradio-docs -> ../../cbradio/docs
cbsurveys-docs -> ../../cbsurveys/docs
cbworkflow-docs -> ../../cbworkflow/docs

Synchronization Checklist

Full Sync Procedure

When performing a complete documentation sync:

  • 1. Discover Projects 

    ls -la /home/bisenbek/projects/nominate/ | grep "^d" | grep "cb"

  • 2. Check for Missing Symlinks 

    for dir in /home/bisenbek/projects/nominate/cb*/; do
  name=$(basename "$dir")
  if [ "$name" != "cb" ] && [ -d "$dir/docs" ]; then
    if [ ! -L "docs/${name}-docs" ]; then
      echo "Missing symlink: $name"
    fi
  fi
done

  • 3. Create Missing Symlinks 

    cd /home/bisenbek/projects/nominate/cbtenant/docs
ln -s ../../{project}/docs {project}-docs

  • 4. Check Navigation Coverage 

    for link in docs/cb*-docs; do
  name=$(basename "$link")
  if ! grep -q "$name" mkdocs.yml; then
    echo "Not in nav: $name"
  fi
done

  • 5. Update mkdocs.yml Navigation

  • Add new sections for any missing projects

  • Ensure all doc files are referenced

  • 6. Update Landing Page (index.md)

  • Add to Platform Services table
  • Add to GitHub Repositories table

  • Update port reference if needed

  • 7. Update Overview Page (overview.md)

  • Update architecture diagram (mermaid)
  • Add to Platform Components table
  • Add Service Details section

  • Update Current Versions table

  • 8. Update Inventory (reference/inventory.md)

  • Add to Projects Overview table
  • Add domain/port information
  • Add systemd service info

  • Update GitHub Repositories table

  • 9. Validate Build 

    cd /home/bisenbek/projects/nominate/cbtenant
mkdocs build --strict 2>&1 | grep -E "WARNING|ERROR"

  • 10. Deploy 

    ./scripts/docs_deploy.sh

Adding a New Project

Step 1: Create Project Documentation

In the new project, create a docs/ directory with at least:

project/
├── docs/
│   └── index.md        # Required: Overview page
├── CLAUDE.md           # Recommended: AI coding guide
└── ...

cd /home/bisenbek/projects/nominate/cbtenant/docs
ln -s ../../{project}/docs {project}-docs

# Verify
ls -la | grep {project}
# Should show: {project}-docs -> ../../{project}/docs

Step 3: Update Navigation (mkdocs.yml)

Add entries to the nav: section in the appropriate category:

  - New Project:
    - Overview: {project}-docs/index.md
    - Feature Doc: {project}-docs/FEATURE.md

Step 4: Update Landing Page (index.md)

Add to the Platform Services table:

| New Service | [newservice.nominate.ai](https://newservice.nominate.ai) | [/docs](https://newservice.nominate.ai/docs) | Description |

Step 5: Update Overview Page (overview.md)

  1. Architecture Diagram: Add node to mermaid diagram
  2. Platform Components Table: Add row with repo, description, tech stack
  3. Service Details Section: Add new subsection with:
  4. Functions
  5. Ports
  6. Documentation links

Step 6: Update Inventory (reference/inventory.md)

  1. Add to Projects Overview table
  2. Add domain/port information
  3. Add systemd service info
  4. Update GitHub Repositories table

Step 7: Build and Test

# Strict build to catch errors
mkdocs build --strict

# Local preview
mkdocs serve

# Deploy
./scripts/docs_deploy.sh

Live Service URLs

Documentation Endpoints

Service Swagger/API Docs
Tenant Manager tenant.nominate.ai/docs
Workflow Engine workflow.nominate.ai/docs
Districts districts.nominate.ai/docs
Surveys surveys.nominate.ai/docs
Models models.nominate.ai/docs
Files files.nominate.ai/docs
Radio ruralamfm.nominate.ai/docs
Test Site API testsiteapi.nominate.ai/docs
KY04 API ky04api.nominate.ai/docs
MI20 API mi20api.nominate.ai/docs

Campaign Sites

Site Frontend API
Test Site testsite.nominate.ai testsiteapi.nominate.ai
KY-04 ky04.nominate.ai ky04api.nominate.ai
MI-20 mi20.nominate.ai mi20api.nominate.ai

Automation

GitHub Actions Workflow

The documentation auto-refreshes via GitHub Actions:

  • Workflow: .github/workflows/refresh-docs.yml
  • Trigger: Push to master, daily at 6 AM UTC, manual dispatch
  • Script: ./scripts/docs_deploy.sh

Manual Refresh

# Full rebuild and deploy
./scripts/docs_deploy.sh

# Quick restart (picks up symlinked changes)
sudo systemctl restart mkdocs

# Check service status
sudo systemctl status mkdocs

File Locations

File Purpose
mkdocs.yml Site configuration and navigation
docs/index.md Landing page with service links
docs/overview.md Platform architecture diagram
docs/reference/inventory.md Complete service inventory
docs/cb*-docs/ Symlinks to project docs
docs/guides/docs-sync.md This guide
.github/workflows/refresh-docs.yml Auto-refresh workflow
scripts/docs_deploy.sh Deployment script

Troubleshooting

# Check if target exists
ls -la ../../{project}/docs/

# Recreate symlink
rm {project}-docs
ln -s ../../{project}/docs {project}-docs

Build Warnings

Common warnings and fixes:

Warning Fix
"Page not found" Check file path in mkdocs.yml matches actual file
"Broken link" Fix internal link or add missing page
"Duplicate nav entry" Remove duplicate from mkdocs.yml nav

Service Not Reloading

# Check systemd status
sudo systemctl status mkdocs

# View logs
sudo journalctl -u mkdocs -f

# Force restart
sudo systemctl restart mkdocs

Last updated: 2025-12-28