brainy/dev/docs/PDF_GENERATION_GUIDE.md

Brainy Architecture PDF Generation Guide

This guide shows you how to generate a professional PDF from the Brainy architecture documentation with beautiful diagrams.

Quick Start

Option 1: Using the npm script (Recommended)

# Make sure you're in the brainy project directory
cd /path/to/brainy

# Install dependencies if not already installed
npm install

# Generate the PDF
npm run generate-pdf

Option 2: Direct script execution

# Make sure you're in the brainy project directory
cd /path/to/brainy

# Install Puppeteer if not already installed
npm install puppeteer

# Run the script directly
node dev/dev/scripts/generate-architecture-pdf.js

Installation Requirements

Prerequisites

• Node.js 18+
• npm or yarn

Dependencies

The script uses:

• Puppeteer: For PDF generation and browser automation
• Mermaid: For rendering diagrams (loaded via CDN)
• Google Fonts: For professional typography (loaded via CDN)

Install Dependencies

# If you don't have puppeteer installed globally or in the project
npm install puppeteer

# Or install as dev dependency
npm install --save-dev puppeteer

Output

The PDF will be generated at:

docs/Brainy_Architecture_Documentation.pdf

Features of the Generated PDF

Professional Styling

• Modern Typography: Uses Inter font family for clean, readable text
• Code Font: JetBrains Mono for code blocks and technical content
• Color Scheme: Professional blue theme with proper contrast
• Layout: A4 format with proper margins and spacing

Rich Diagrams

• Mermaid Diagrams: All diagrams are rendered as vector graphics
• Interactive Elements: Flowcharts, sequence diagrams, mindmaps, and more
• Consistent Styling: All diagrams follow the same color scheme
• High Quality: Vector-based rendering for crisp output

Document Structure

• Table of Contents: Linked navigation
• Page Headers/Footers: Professional branding and page numbers
• Section Breaks: Logical page breaks between major sections
• Code Highlighting: Syntax highlighting for JSON and code blocks

Customization

Modify Styling

Edit the professionalCSS variable in dev/scripts/generate-architecture-pdf.js:

const professionalCSS = `
  /* Your custom CSS here */
  h1 {
    color: #your-color;
    font-size: 24pt;
  }
  /* ... */
`

Change Output Location

Modify the config object:

const config = {
  inputFile: path.join(__dirname, '../docs/brainy_architecture_visual.md'),
  outputFile: path.join(__dirname, '../docs/YOUR_CUSTOM_NAME.pdf'),
  // ...
}

Adjust PDF Settings

Modify the page.pdf() options:

await page.pdf({
  path: config.outputFile,
  format: 'A4', // or 'Letter', 'Legal', etc.
  printBackground: true,
  margin: {
    top: '20mm',
    right: '15mm', 
    bottom: '20mm',
    left: '15mm'
  },
  // ... other options
})

Troubleshooting

Common Issues

1. "Puppeteer not found"

npm install puppeteer

2. "Chrome/Chromium not found"

# On Ubuntu/Debian
sudo apt-get install chromium-browser

# On macOS
brew install chromium

# Or let Puppeteer download Chromium
npm install puppeteer --unsafe-perm=true

3. "Permission denied"

chmod +x dev/scripts/generate-architecture-pdf.js

4. "Diagrams not rendering"

Check your internet connection - Mermaid is loaded from CDN. For offline use, you can download mermaid.min.js locally and update the path.

Advanced Configuration

Use Local Mermaid

Download mermaid.min.js and update the config:

const config = {
  // ...
  mermaidCDN: './path/to/mermaid.min.js'
}

Custom Fonts

Add additional fonts to the CSS:

@import url('https://fonts.googleapis.com/css2?family=YourFont:wght@400;500;600&display=swap');

body {
  font-family: 'YourFont', sans-serif;
}

Adding to package.json

Add this script to your package.json:

{
  "scripts": {
    "generate-pdf": "node dev/dev/scripts/generate-architecture-pdf.js",
    "docs:pdf": "npm run generate-pdf"
  },
  "devDependencies": {
    "puppeteer": "^22.5.0"
  }
}

Alternative PDF Generators

If you prefer other tools, you can also use:

1. Pandoc + LaTeX

# Install pandoc and latex
sudo apt-get install pandoc texlive-latex-recommended

# Convert (note: won't render Mermaid diagrams)
pandoc docs/brainy_architecture_visual.md -o docs/brainy_architecture.pdf

2. mdpdf

npm install -g mdpdf
mdpdf docs/brainy_architecture_visual.md --output=docs/brainy_architecture.pdf

3. markdown-pdf

npm install -g markdown-pdf
markdown-pdf docs/brainy_architecture_visual.md -o docs/brainy_architecture.pdf

Note: The custom Puppeteer script provides the best results with proper Mermaid diagram rendering and professional styling.

Sample Output

The generated PDF will include:

1. Cover Page with title and subtitle
2. Table of Contents with page links
3. System Overview with environment detection diagram
4. Core Architecture with layered architecture diagram
5. Data Model with noun/verb type hierarchies
6. Vector Search Engine with HNSW visualization
7. Storage Architecture with multi-tier caching diagrams
8. Augmentation Pipeline with flow diagrams
9. Performance Optimizations with threading models
10. Integration Patterns with network topology
11. Data Flow Examples with sequence diagrams

Total pages: ~25-30 pages with full diagrams and explanations.

---

For questions or issues with PDF generation, please check the troubleshooting section or create an issue in the repository.