**feat(docs): add comprehensive architecture documentation for Brainy**

- **Documentation Additions**: - Created `brainy_architecture_diagram.md` to detail Brainy's architecture using diagrams and structured descriptions: - Added overviews of the system, core architecture, and augmentation pipeline. - Defined data models, graph structures, storage architecture, and performance optimizations. - Explained vector search engine design, HNSW index structure, and usage flow examples. - Developed `brainy_architecture_visual.md` to complement the architecture with visual aids in Mermaid.js: - Provided detailed flowcharts, mind maps, and sequence diagrams for system components and data flow. - **Purpose**: - Provide in-depth technical insights into Brainy's architecture for developers and stakeholders. - Enhance understanding of the system's core design principles with easy-to-follow diagrams and examples.
2025-08-02 16:05:48 -07:00 · 2025-08-02 16:05:48 -07:00 · 5f9e807952
commit 5f9e807952
parent 672be32bea
10 changed files with 2842 additions and 2 deletions
--- a/dev/docs/PDF_GENERATION_GUIDE.md
+++ b/dev/docs/PDF_GENERATION_GUIDE.md
@ -0,0 +1,242 @@
+# 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)
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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`:
+
+```javascript
+const professionalCSS = `
+  /* Your custom CSS here */
+  h1 {
+    color: #your-color;
+    font-size: 24pt;
+  }
+  /* ... */
+`
+```
+
+### Change Output Location
+Modify the `config` object:
+
+```javascript
+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:
+
+```javascript
+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"
+```bash
+npm install puppeteer
+```
+
+#### 2. "Chrome/Chromium not found"
+```bash
+# 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"
+```bash
+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:
+
+```javascript
+const config = {
+  // ...
+  mermaidCDN: './path/to/mermaid.min.js'
+}
+```
+
+#### Custom Fonts
+Add additional fonts to the CSS:
+
+```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`:
+
+```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
+```bash
+# 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
+```bash
+npm install -g mdpdf
+mdpdf docs/brainy_architecture_visual.md --output=docs/brainy_architecture.pdf
+```
+
+### 3. markdown-pdf
+```bash
+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.*