Documentation System Build Pipeline Analysis

Generated: 2025-08-26 14:00 UTC
Status: Complete
Purpose: Complete analysis of documentation system code flow from source to Docker deployment

Complete Build Pipeline Flow

File Locations Through Pipeline

1. Source Files (Development)

/Users/lindsaysmith/Documents/lambda1.nosync/sasha/
├── claudecodeui/
│   ├── html-static/
│   │   ├── index.html          # SPA shell (with docs-router.js)
│   │   ├── css/                # Styles
│   │   └── js/
│   │       └── docs-router.js  # Documentation router
│   ├── scripts/
│   │   └── generate-spa-html.js # HTML generation script
│   └── docker-entrypoint.sh    # Container startup script
└── deployed-md-files/
    └── docs/                    # Markdown documentation
        ├── home.md
        ├── CLAUDE-user.md
        └── ... (52 files total)

2. Docker Build Stage (Dockerfile.sliplane)

# Line 95-98: Copy markdown documentation
COPY --chown=nodejs:nodejs deployed-md-files/docs /app/deployed-md-files/docs

# Line 96-98: Copy SPA assets
COPY --chown=nodejs:nodejs claudecodeui/html-static/index.html /app/html-static/index.html
COPY --chown=nodejs:nodejs claudecodeui/html-static/css /app/html-static/css
COPY --chown=nodejs:nodejs claudecodeui/html-static/js /app/html-static/js

# Line 154: Copy entrypoint script
COPY --chown=nodejs:nodejs claudecodeui/docker-entrypoint.sh /docker-entrypoint.sh

3. Container Runtime (docker-entrypoint.sh)

# Lines 35-64: Documentation setup process
1. Copy docs from /app/deployed-md-files/docs → /home/nodejs/all-project-files/docs
2. Run generate-spa-html.js to create HTML files
3. Generate index.html and content/*.html files

4. Final Runtime Locations

/home/nodejs/all-project-files/
├── docs/                        # Markdown files (copied from container)
│   ├── home.md
│   └── ...
├── html-static/                 # Generated HTML (created by script)
│   ├── index.html              # SPA shell
│   ├── content/                # Generated HTML content
│   │   ├── home.html
│   │   └── ...
│   ├── css/                    # Styles
│   └── js/
│       └── docs-router.js      # Router

Key Components

1. docs-router.js

• Source: claudecodeui/html-static/js/docs-router.js
• Docker: /app/html-static/js/docs-router.js
• Runtime: /home/nodejs/all-project-files/html-static/js/docs-router.js
• Function: SPA router handling navigation, content loading, breadcrumbs
• Critical Fix Applied: Changed fetch URL from content/${path} to /api/docs-content/${path}

2. index.html (SPA Shell)

• Generated by: generate-spa-html.js line 220-361
• Location: /home/nodejs/all-project-files/html-static/index.html
• Key Elements:
  • #breadcrumb-trail - Breadcrumb navigation
  • #navigation-container - Dynamic navigation tree
  • #content-area - Content display area
  • Script loads docs-router.js and initializes it

3. generate-spa-html.js

• Executes: During container startup (docker-entrypoint.sh line 53)
• Functions:
  1. Scans /home/nodejs/all-project-files/docs for markdown
  2. Converts markdown to HTML with <article> wrapper
  3. Generates SPA shell (index.html)
  4. Creates content HTML files in content/ directory

4. Server Endpoints (server/index.js)

• Line 882: /api/navigation - Returns navigation tree JSON

  • Scans docs directory
  • Builds hierarchical structure
  • Returns to docs-router.js for rendering

• Line 751: /api/docs-content - Serves HTML content files

  • Static file server for generated HTML
  • Maps to /home/nodejs/all-project-files/html-static/content/

Complete Request Flow

1. User visits documentation:

   • Browser loads /home/nodejs/all-project-files/html-static/index.html
   • index.html loads docs-router.js

2. docs-router.js initializes:

   • Fetches navigation from /api/navigation
   • Server scans /home/nodejs/all-project-files/docs
   • Returns JSON tree structure

3. User clicks navigation item:

   • docs-router.js fetches from /api/docs-content/guides/example.html
   • Server serves from /home/nodejs/all-project-files/html-static/content/guides/example.html
   • Content displays in #content-area
   • Breadcrumbs update in #breadcrumb-trail

Critical Path Dependencies

1. Markdown → HTML Generation:

   • Depends on docker-entrypoint.sh executing generate-spa-html.js
   • Only runs if /home/nodejs/all-project-files/docs exists
   • Preserves existing content if already generated

2. Navigation Building:

   • Server dynamically scans markdown files
   • No static navigation in HTML
   • Real-time folder structure

3. Content Loading:

   • Requires <article> elements in generated HTML
   • docs-router.js extracts article content
   • Falls back to full HTML if no article found

Fixes Applied

1. docs-router.js (claudecodeui/html-static/js/docs-router.js):

   • Line ~140: Changed default from index.html to home.html
   • Line ~195: Fixed fetch URL to /api/docs-content/${path}
   • Line ~250: Added special case for home breadcrumb

2. index.html (via generate-spa-html.js):

   • Line 341: Loads docs-router.js instead of main.js
   • Line 353-357: Proper initialization code
   • Added all required DOM element IDs

3. generate-spa-html.js:

   • Fixed navigation tree building logic
   • Proper article wrapper generation
   • SPA-compatible HTML structure

Verification Points

To verify the system works:

1. Check Docker build copies files:

   docker exec [container] ls -la /app/html-static/js/docs-router.js
   docker exec [container] ls -la /app/deployed-md-files/docs/
   

2. Verify generation runs:

   docker exec [container] ls -la /home/nodejs/all-project-files/html-static/
   docker exec [container] ls -la /home/nodejs/all-project-files/html-static/content/
   

3. Test endpoints:

   curl http://localhost:3005/api/navigation
   curl http://localhost:3005/api/docs-content/home.html
   

Summary

The documentation system flows through multiple stages:

1. Source → Docker Build → Container → Runtime Generation → Server

Key insights:

• HTML generation happens at container startup, not build time
• docs-router.js and index.html must be properly configured in source
• Server provides dynamic navigation and static content serving
• All paths must align between generation script and server endpoints

The fixes ensure docs-router.js can properly load content by using the correct API endpoint and handling the home page breadcrumb correctly.