Skip to content

Documentation Refresh Process

This guide documents the process for refreshing Campaign Brain documentation when platform modules are updated. It is designed for both AI assistants (Claude Code) and human operators.

Overview

The Campaign Brain platform consists of 18 modules (cb*), each with its own /docs directory. The central documentation hub (cbdocs) aggregates these via symlinks and publishes to docs.nominate.ai.

Key principle: Only refresh documentation for projects that have changed since the last refresh, tracked via git modification timestamps.

Quick Start

# Check which projects have changes
./scripts/docs-refresh.sh --check

# After reviewing and updating docs, mark as processed
./scripts/docs-refresh.sh --update

# Full refresh (ignore timestamps)
./scripts/docs-refresh.sh --full

Architecture

Directory Structure

~/projects/nominate/
├── cb/                      # Symlink directory
│   ├── cbapp -> ../cbapp
│   ├── cbauth -> ../cbauth
│   └── ...
├── cbdocs/                  # Documentation hub
│   ├── docs/
│   │   ├── .last-refresh.json    # Timestamp tracking
│   │   ├── cbapp-docs -> ../../cbapp/docs
│   │   ├── cbauth-docs -> ../../cbauth/docs
│   │   └── ...
│   ├── scripts/
│   │   ├── docs-refresh.sh       # Change detection
│   │   └── refresh_dev_status.sh # GitHub issues sync
│   └── mkdocs.yml                # Navigation config
└── {cb*}/                   # Individual modules
    └── docs/                # Source documentation

Timestamp Tracking

The system uses .git directory modification times to detect changes:

  • ~/projects/nominate/cb/recent-modifications.sh - Lists all project modification times
  • docs/.last-refresh.json - Stores last processed timestamps per project

Refresh Process Steps

Step 1: Detect Changes

./scripts/docs-refresh.sh --check

This will output: - Projects with changes since last refresh - Last git modification time - Last processed time - Number of docs files

Step 2: Review Changed Projects

For each changed project, review the docs directory:

# Example: cbapp changed
ls ~/projects/nominate/cbapp/docs/

# Look for new/updated files
find ~/projects/nominate/cbapp/docs -name "*.md" -newer ~/projects/nominate/cbdocs/docs/.last-refresh.json

Step 3: Update Documentation Hub

For each changed project, you may need to:

  1. Check symlinks exist 

    ls -la docs/ | grep cbapp-docs
# If missing: ln -s ../../cbapp/docs docs/cbapp-docs

  2. Update mkdocs.yml navigation

  3. Add new pages to appropriate sections
  4. Remove pages that no longer exist

  5. Reorganize if structure changed

  6. Update service tables (if service info changed)

  7. docs/index.md - Platform Services table
  8. docs/overview.md - Component descriptions
  9. docs/reference/inventory.md - Complete inventory
  10. docs/DOCS-META-INDEX.md - Module list

Step 4: Build and Verify

cd ~/projects/nominate/cbdocs
mkdocs build --clean

# Check for broken links in build output
# Restart if changes are ready
sudo systemctl restart mkdocs

Step 5: Mark as Processed

./scripts/docs-refresh.sh --update

This updates the timestamp file so these changes won't be flagged next run.

For AI Assistants (Claude Code)

When instructed to refresh documentation:

Initial Assessment

# Get current change status
./scripts/docs-refresh.sh --json

Per-Project Review Checklist

For each changed project:

  1. Read the project's docs directory 

    ls ~/projects/nominate/{project}/docs/

  2. Compare with mkdocs.yml navigation

  3. Are all docs files referenced?
  4. Are there new files not yet in navigation?

  5. Are there removed files still referenced?

  6. Check for new features/services

  7. New systemd services?
  8. New API endpoints?
  9. New ports?

  10. New domains?

  11. Update the four key files if needed

  12. docs/index.md
  13. docs/overview.md
  14. docs/reference/inventory.md
  15. mkdocs.yml

Common Updates

Change Type Files to Update
New project All 4 key files + create symlink
New docs page mkdocs.yml only
New port/domain index.md, inventory.md
Service description overview.md, index.md
Renamed docs mkdocs.yml

After Updates

# Build to verify
mkdocs build --clean

# Restart service
sudo systemctl restart mkdocs

# Update timestamps
./scripts/docs-refresh.sh --update

# Optionally commit
git add -A && git commit -m "Refresh docs for {projects}"

Automation (Cron)

To run automatically at 4am daily:

# Add to crontab
0 4 * * * /home/bisenbek/projects/nominate/cbdocs/scripts/docs-refresh.sh --json > /tmp/docs-changes.json 2>&1

The JSON output can be used by: - Monitoring systems (alert if changes detected) - AI assistants (provide as context for refresh) - CI/CD pipelines (trigger doc builds)

Project Reference

All 18 Modules

Project Nav Section Typical Docs
cbai AI Service index.md
cbapp Campaign App 30+ files, screenshots/, style-guide/
cbauth Authentication index.md, START-HERE.md, INFRA-GUIDE.md
cbdistricts Districts Service API docs, architecture
cbdocs N/A (this hub) Self-referential
cbetl ETL Pipeline index.md
cbfiles File Storage (CDN) index.md, DEVELOPERS.md
cbinfra Infrastructure Runbooks, guides
cbintel Intelligence Service api/, guides/, reference/
cbmesh API Mesh index.md, START-HERE.md
cbmodels Models & Analytics API architecture, integration
cbos Session Manager MVP, streaming, workflow
cbproject Executive Publication Screenshots, image index
cbpublic Public Website Website plan, partners/
cbradio Radio Advertising FCC integration, rate cards
cbsurveys Survey Platform index.md
cbtenant Tenant Manager Deployment guides
cbworkflow Workflow Engine API, engine analysis

Key Files Summary

File Purpose Update When
docs/.last-refresh.json Timestamp tracking Auto-updated by script
docs/DOCS-META-INDEX.md Index of doc locations New module added
docs/index.md Homepage with service tables Service changes
docs/overview.md Platform component details Architecture changes
docs/reference/inventory.md Complete inventory Any infrastructure change
mkdocs.yml Navigation structure Any docs structure change

Troubleshooting

# Create missing symlink
ln -s ../../{project}/docs docs/{project}-docs

Build Errors

# Check for broken references
mkdocs build --clean 2>&1 | grep -i "warning\|error"

Timestamp File Corrupt

# Regenerate with full refresh
./scripts/docs-refresh.sh --full --update

This guide is maintained in cbdocs/docs/guides/docs-refresh-process.md. Update when the refresh process changes.