GeneralBots/botserver
2
1
Fork 0
Code Issues Pull requests Projects Releases 323 Packages Wiki Activity Actions

- Version of publish.

Browse source
This commit is contained in:
Rodrigo Rodriguez (Pragmatismo) 2025-11-25 16:10:50 -03:00
parent 1c173e76e5
commit 1dc9a652f5
28 changed files with 2016 additions and 1181 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
book.toml Normal file
View file

@ -0,0 +1,54 @@
[book]
title = "BotServer Documentation"
authors = ["BotServer Team"]
language = "en"
multilingual = false
src = "docs/src"
description = "Documentation for BotServer - A flexible bot framework"
[build]
build-dir = "docs/book"
[output.html]
smart-punctuation = true
mathjax-support = false
copy-fonts = true
no-section-label = false
additional-css = ["docs/src/custom.css"]
additional-js = ["docs/src/theme-sync.js"]
git-repository-url = "https://github.com/yourusername/botserver"
git-repository-icon = "fa-github"
edit-url-template = "https://github.com/yourusername/botserver/edit/main/{path}"
site-url = "/botserver/"
cname = ""
input-404 = ""
[output.html.print]
enable = true
[output.html.fold]
enable = false
level = 0
[output.html.playground]
editable = false
copyable = true
copy-js = true
line-numbers = false
runnable = false
[output.html.search]
enable = true
limit-results = 30
teaser-word-count = 30
use-boolean-and = true
boost-title = 2
boost-hierarchy = 1
boost-paragraph = 1
expand = true
heading-split-level = 3
copy-js = true
[preprocessor.index]
[preprocessor.links]

120
docs/MIGRATION_INTEGRATION_SUMMARY.md Normal file
View file

@ -0,0 +1,120 @@
# Migration Integration Summary
## Date: November 25, 2024
### Overview
Successfully integrated Chapter 14 (Migration Guide) into the General Bots documentation and reorganized the appendix numbering system to maintain consistency.
## Changes Implemented
### 1. Chapter 14: Migration Guide Integration
Added a comprehensive migration chapter with the following sections:
- **Migration Overview** - Understanding the paradigm shift from cloud to self-hosted
- **Common Concepts** - Shared patterns and tools across migrations
- **Knowledge Base Migration** - Converting SharePoint/Drive to .gbkb format
- **Google Workspace Integration** - Complete migration path from Google services
- **Microsoft 365 Integration** - Complete migration path from M365 services
- **Automation Migration** - BASIC scripts for automating migration tasks
- **Validation and Testing** - Post-migration verification procedures
### 2. Documentation Structure Updates
#### Before:
```
Part I-XII: Chapters 1-12
Part XIII: Community (Chapter 13)
Appendices: Appendix I (Database Model)
```
#### After:
```
Part I-XII: Chapters 1-12
Part XIII: Community (Chapter 13)
Part XIV: Migration (Chapter 14) ← NEW
Appendices: Appendix XV (Database Model) ← RENUMBERED
```
### 3. File System Changes
| Action | From | To |
|--------|------|-----|
| Renamed | `docs/src/appendix-i/` | `docs/src/appendix-15/` |
| Updated | `docs/src/SUMMARY.md` | Added Chapter 14 entries |
| Updated | `book.toml` | Fixed deprecated `curly-quotes` → `smart-punctuation` |
### 4. Migration Chapter Contents
The migration chapter provides:
- **Enterprise comparison matrix** showing equivalents between cloud services and General Bots components
- **Step-by-step migration guides** for both Microsoft 365 and Google Workspace
- **Automation scripts** in BASIC for common migration tasks
- **Knowledge base conversion** utilities and best practices
- **Validation checklists** to ensure successful migration
### 5. Key Concepts Introduced
#### The Mega-Prompt Problem
Explains how services like Microsoft Copilot and Google Gemini are essentially sophisticated prompt engines with limitations:
- Black box operations
- Cloud dependency
- Monolithic approach
- Subscription lock-in
#### The Component Solution
Demonstrates General Bots' approach with actual installable components:
- True modularity
- Self-hosted control
- Component composability
- No vendor lock-in
### 6. Migration Matrix
| Enterprise Service | General Bots Component | Package Type |
|-------------------|------------------------|--------------|
| OneDrive/Google Drive | MinIO | .gbdrive |
| Outlook/Gmail | Stalwart Mail | .gbmail |
| Entra ID/Google Directory | Zitadel | .gbdirectory |
| SharePoint/Sites | MinIO + Qdrant | .gbkb |
| Teams/Meet | LiveKit | .gbmeet |
| Copilot/Gemini | Local LLM + BASIC | .gbdialog |
## Build Verification
✅ **mdBook build**: Successful, no errors
✅ **Documentation structure**: All links resolve correctly
✅ **Chapter integration**: Chapter 14 fully accessible in navigation
✅ **Appendix renumbering**: Appendix XV properly referenced
✅ **Configuration updates**: No deprecation warnings
## Impact
This integration provides enterprise users with:
1. Clear migration paths from cloud services to self-hosted alternatives
2. Practical automation scripts to speed up migration
3. Validation procedures to ensure data integrity
4. Cost comparison insights between cloud subscriptions and self-hosted solutions
## Technical Notes
- SVG diagrams in migration chapter use CSS variables for theme compatibility
- All migration scripts are written in General Bots BASIC dialect
- Knowledge base conversion maintains semantic search capabilities
- Documentation follows existing mdBook conventions and styling
## Future Considerations
1. **Add migration metrics** - Time estimates for different organization sizes
2. **Expand automation library** - More BASIC scripts for specific scenarios
3. **Include case studies** - Real-world migration success stories
4. **Performance benchmarks** - Comparison data between cloud and self-hosted
## Files Affected
- `/docs/src/SUMMARY.md`
- `/docs/src/chapter-14-migration/*.md` (8 files)
- `/docs/src/appendix-15/*.md` (4 files, renamed from appendix-i)
- `/book.toml`
## Conclusion
The migration chapter successfully bridges the gap for enterprises looking to transition from cloud services to General Bots' self-hosted architecture. The documentation now provides a complete path from evaluation through implementation and validation.

19
docs/src/SUMMARY.md
View file

@ -176,12 +176,23 @@
- [Community Guidelines](./chapter-13-community/community.md)
- [IDEs](./chapter-13-community/ide-extensions.md)
# Part XIII - Migration
- [Chapter 14: Migration Guide](./chapter-14-migration/README.md)
- [Migration Overview](./chapter-14-migration/overview.md)
- [Common Concepts](./chapter-14-migration/common-concepts.md)
- [Knowledge Base Migration](./chapter-14-migration/kb-migration.md)
- [Google Workspace Integration](./chapter-14-migration/google-workspace.md)
- [Microsoft 365 Integration](./chapter-14-migration/microsoft-365.md)
- [Automation Migration](./chapter-14-migration/automation.md)
- [Validation and Testing](./chapter-14-migration/validation.md)
# Appendices
- [Appendix I: Database Model](./appendix-i/README.md)
- [Schema Overview](./appendix-i/schema.md)
- [Tables](./appendix-i/tables.md)
- [Relationships](./appendix-i/relationships.md)
- [Appendix XV: Database Model](./appendix-15/README.md)
- [Schema Overview](./appendix-15/schema.md)
- [Tables](./appendix-15/tables.md)
- [Relationships](./appendix-15/relationships.md)
[Glossary](./glossary.md)
[Contact](./contact/README.md)

0
docs/src/appendix-i/README.md → docs/src/appendix-15/README.md
View file

0
docs/src/appendix-i/relationships.md → docs/src/appendix-15/relationships.md
View file

0
docs/src/appendix-i/schema.md → docs/src/appendix-15/schema.md
View file

0
docs/src/appendix-i/tables.md → docs/src/appendix-15/tables.md
View file

96
docs/src/appendix-i/assets/kb-access.svg
View file

@ -1,96 +0,0 @@
<svg width="800" height="400" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#666"/>
</marker>
</defs>
<!-- Title -->
<text x="400" y="25" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="600" fill="#333">Knowledge Base Access</text>
<!-- user_sessions -->
<rect x="20" y="60" width="160" height="40" fill="none" stroke="#4A90E2" stroke-width="2" rx="5"/>
<text x="100" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">user_sessions</text>
<!-- user_kb_associations -->
<rect x="240" y="60" width="160" height="40" fill="none" stroke="#50E3C2" stroke-width="2" rx="5"/>
<text x="320" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">user_kb_associations</text>
<!-- kb_collections -->
<rect x="20" y="180" width="160" height="40" fill="none" stroke="#7ED321" stroke-width="2" rx="5"/>
<text x="100" y="205" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">kb_collections</text>
<!-- kb_documents -->
<rect x="240" y="180" width="160" height="40" fill="none" stroke="#F5A623" stroke-width="2" rx="5"/>
<text x="320" y="205" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">kb_documents</text>
<!-- Vector Storage -->
<rect x="460" y="180" width="160" height="40" fill="none" stroke="#BD10E0" stroke-width="2" rx="5"/>
<text x="540" y="205" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">Vector Storage</text>
<!-- Field details -->
<g font-family="Arial, sans-serif" font-size="11" fill="#666">
<!-- user_sessions fields -->
<text x="30" y="120">id, user_id</text>
<text x="30" y="135">bot_id, session_token</text>
<!-- user_kb_associations fields -->
<text x="250" y="120">id, session_id</text>
<text x="250" y="135">kb_id, created_at</text>
<!-- kb_collections fields -->
<text x="30" y="240">id, bot_id, name</text>
<text x="30" y="255">created_at, metadata</text>
<!-- kb_documents fields -->
<text x="250" y="240">id, collection_id</text>
<text x="250" y="255">content, embeddings</text>
<!-- Vector Storage info -->
<text x="470" y="240">Embeddings stored</text>
<text x="470" y="255">for semantic search</text>
</g>
<!-- Arrows -->
<g stroke="#666" stroke-width="2" fill="none">
<!-- user_sessions to user_kb_associations -->
<line x1="180" y1="80" x2="240" y2="80" marker-end="url(#arrow)"/>
<!-- user_kb_associations references kb_collections (dashed) -->
<path d="M320,100 Q320,140 100,140 Q100,160 100,180" stroke-dasharray="3,3" marker-end="url(#arrow)" opacity="0.6"/>
<!-- kb_collections to kb_documents -->
<line x1="180" y1="200" x2="240" y2="200" marker-end="url(#arrow)"/>
<!-- kb_documents to Vector Storage -->
<line x1="400" y1="200" x2="460" y2="200" marker-end="url(#arrow)"/>
</g>
<!-- Relationship labels -->
<text x="210" y="75" font-family="Arial, sans-serif" font-size="11" fill="#666">Has Access</text>
<text x="210" y="195" font-family="Arial, sans-serif" font-size="11" fill="#666">Contains</text>
<text x="210" y="210" font-family="Arial, sans-serif" font-size="11" fill="#666">1:N</text>
<text x="430" y="195" font-family="Arial, sans-serif" font-size="11" fill="#666">Indexes</text>
<text x="210" y="140" font-family="Arial, sans-serif" font-size="11" fill="#666">References</text>
<!-- Access Pattern Box -->
<g transform="translate(460, 60)">
<rect width="320" height="90" fill="none" stroke="#666" stroke-width="1" rx="5" opacity="0.3"/>
<text x="10" y="20" font-family="Arial, sans-serif" font-size="12" font-weight="600" fill="#333">Access Pattern:</text>
<text x="10" y="40" font-family="Arial, sans-serif" font-size="12" fill="#666">1. Session requests KB access</text>
<text x="10" y="55" font-family="Arial, sans-serif" font-size="12" fill="#666">2. Association created in user_kb_associations</text>
<text x="10" y="70" font-family="Arial, sans-serif" font-size="12" fill="#666">3. KB documents become available</text>
<text x="10" y="85" font-family="Arial, sans-serif" font-size="12" fill="#666">4. Vector search enabled on embeddings</text>
</g>
<!-- Description -->
<text x="400" y="320" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#666">
Sessions gain access to knowledge bases through associations, enabling vector search on document embeddings
</text>
<text x="400" y="340" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#666">
Each collection contains multiple documents with pre-computed embeddings for semantic search
</text>
<text x="400" y="360" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#666">
Access is controlled per session, allowing dynamic knowledge base selection during conversations
</text>
</svg>
Side by side

Before

Width:  |  Height:  |  Size: 5 KiB

128
docs/src/appendix-i/assets/kb-access.svg.backup
View file

@ -1,128 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<svg viewBox="0 0 880 480" xmlns="http://www.w3.org/2000/svg" style="max-width: 100%; height: auto;">
<defs>
<!-- Arrow markers -->
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#2563EB">
</marker>
<!-- Drop shadow for depth -->
<filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
<feGaussianBlur in="SourceAlpha" stdDeviation="2">
<feOffset dx="1" dy="1" result="offsetblur">
<feComponentTransfer>
<feFuncA type="linear" slope="0.2">
</feComponentTransfer>
<feMerge>
<feMergeNode/>
<feMergeNode in="SourceGraphic">
</feMerge>
</filter>
</defs>
<!-- Beautiful gradient definitions for depth -->
<!-- White background with subtle border -->
<rect x="0" y="0" width="880" height="480" fill="#F9FAFB" stroke="#9CA3AF" stroke-width="2" rx="8">
<!-- Content container with proper margins -->
<g transform="translate(40, 40)">
<!-- Title -->
<text x="400" y="30" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">Knowledge Base Access</text>
<!-- user_sessions -->
<rect x="50" y="80" width="200" height="120" fill="none" stroke="#2563EB" stroke-width="2" rx="8" filter="url(#shadow)"/>
<rect x="50" y="80" width="200" height="30" fill="none" stroke="#2563EB" stroke-width="2" rx="8 8 0 0" filter="url(#shadow)"/>
<text x="150" y="100" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">user_sessions</text>
<g font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563">
<text x="60" y="130" filter="url(#textShadow)">• id</text>
<text x="60" y="145" filter="url(#textShadow)">• user_id</text>
<text x="60" y="160" filter="url(#textShadow)">• bot_id</text>
<text x="60" y="175" filter="url(#textShadow)">• session_token</text>
</g>
<!-- Arrow to user_kb_associations -->
<line x1="250" y1="140" x2="320" y2="140" stroke="#6B7280" stroke-width="2" marker-end="url(#arrow)">
<text x="285" y="130" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Has Access</text>
<!-- user_kb_associations -->
<rect x="320" y="80" width="200" height="120" fill="none" stroke="#2563EB" stroke-width="2" rx="8" filter="url(#shadow)"/>
<rect x="320" y="80" width="200" height="30" fill="none" stroke="#2563EB" stroke-width="2" rx="8 8 0 0" filter="url(#shadow)"/>
<text x="420" y="100" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">user_kb_associations</text>
<g font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563">
<text x="330" y="130" filter="url(#textShadow)">• id</text>
<text x="330" y="145" filter="url(#textShadow)">• session_id</text>
<text x="330" y="160" filter="url(#textShadow)">• kb_id</text>
<text x="330" y="175" filter="url(#textShadow)">• created_at</text>
</g>
<!-- Reference arrow down -->
<line x1="420" y1="200" x2="420" y2="240" stroke="#999" stroke-width="2" stroke-dasharray="5,5" marker-end="url(#arrow-ref)">
<text x="435" y="220" text-anchor="start" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">References</text>
<!-- kb_collections -->
<rect x="50" y="240" width="200" height="140" fill="none" stroke="#059669" stroke-width="2" rx="8" filter="url(#shadow)"/>
<rect x="50" y="240" width="200" height="30" fill="none" stroke="#059669" stroke-width="2" rx="8 8 0 0" filter="url(#shadow)"/>
<text x="150" y="260" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">kb_collections</text>
<g font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563">
<text x="60" y="290" filter="url(#textShadow)">• id</text>
<text x="60" y="305" filter="url(#textShadow)">• bot_id</text>
<text x="60" y="320" filter="url(#textShadow)">• name</text>
<text x="60" y="335" filter="url(#textShadow)">• created_at</text>
<text x="60" y="350" filter="url(#textShadow)">• metadata</text>
</g>
<!-- Arrow to kb_documents -->
<line x1="250" y1="310" x2="320" y2="310" stroke="#6B7280" stroke-width="2" marker-end="url(#arrow)">
<text x="285" y="300" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Contains</text>
<text x="285" y="320" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N</text>
<!-- kb_documents -->
<rect x="320" y="240" width="200" height="140" fill="none" stroke="#059669" stroke-width="2" rx="8" filter="url(#shadow)"/>
<rect x="320" y="240" width="200" height="30" fill="none" stroke="#059669" stroke-width="2" rx="8 8 0 0" filter="url(#shadow)"/>
<text x="420" y="260" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">kb_documents</text>
<g font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563">
<text x="330" y="290" filter="url(#textShadow)">• id</text>
<text x="330" y="305" filter="url(#textShadow)">• collection_id</text>
<text x="330" y="320" filter="url(#textShadow)">• content</text>
<text x="330" y="335" filter="url(#textShadow)">• embeddings</text>
<text x="330" y="350" filter="url(#textShadow)">• metadata</text>
</g>
<!-- Vector indicator -->
<g id="vector-indicator" transform="translate(550, 280)">
<rect x="0" y="0" width="180" height="80" fill="none" stroke="#7C3AED" stroke-width="2" rx="5" stroke-dasharray="3,3" opacity="0.7" filter="url(#shadow)"/>
<text x="90" y="25" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">Vector Storage</text>
<text x="90" y="45" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Embeddings stored</text>
<text x="90" y="60" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">for semantic search</text>
</g>
<!-- Connection from kb_documents to vector indicator -->
<line x1="520" y1="335" x2="550" y2="320" stroke="#7C3AED" stroke-width="2" stroke-dasharray="3,3" opacity="0.7">
<!-- Access flow description -->
<g id="access-flow" transform="translate(550, 100)">
<rect x="0" y="0" width="200" height="100" fill="none" stroke="#2563EB" stroke-width="2" rx="5" stroke-dasharray="2,2" opacity="0.5" filter="url(#shadow)"/>
<text x="100" y="20" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">Access Pattern</text>
<g font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563">
<text x="10" y="40" filter="url(#textShadow)">1. Session requests KB</text>
<text x="10" y="55" filter="url(#textShadow)">2. Association created</text>
<text x="10" y="70" filter="url(#textShadow)">3. KB documents available</text>
<text x="10" y="85" filter="url(#textShadow)">4. Vector search enabled</text>
</g>
</g>
</g>
</svg>
Side by side

Before

Width:  |  Height:  |  Size: 7.7 KiB

128
docs/src/appendix-i/assets/schema-detailed.svg
View file

@ -1,128 +0,0 @@
<svg width="800" height="450" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#666"/>
</marker>
</defs>
<!-- Title -->
<text x="400" y="25" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="600" fill="#333">Database Entity Details</text>
<!-- Organizations -->
<rect x="20" y="60" width="120" height="40" fill="none" stroke="#4A90E2" stroke-width="2" rx="5"/>
<text x="80" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">organizations</text>
<!-- Bots -->
<rect x="200" y="60" width="100" height="40" fill="none" stroke="#7ED321" stroke-width="2" rx="5"/>
<text x="250" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">bots</text>
<!-- Users -->
<rect x="360" y="60" width="100" height="40" fill="none" stroke="#F5A623" stroke-width="2" rx="5"/>
<text x="410" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">users</text>
<!-- User Sessions -->
<rect x="520" y="60" width="120" height="40" fill="none" stroke="#BD10E0" stroke-width="2" rx="5"/>
<text x="580" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">user_sessions</text>
<!-- Bot Memories -->
<rect x="20" y="160" width="120" height="40" fill="none" stroke="#50E3C2" stroke-width="2" rx="5"/>
<text x="80" y="185" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">bot_memories</text>
<!-- Message History -->
<rect x="200" y="160" width="120" height="40" fill="none" stroke="#4A90E2" stroke-width="2" rx="5"/>
<text x="260" y="185" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">message_history</text>
<!-- KB Collections -->
<rect x="380" y="160" width="120" height="40" fill="none" stroke="#7ED321" stroke-width="2" rx="5"/>
<text x="440" y="185" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">kb_collections</text>
<!-- KB Documents -->
<rect x="560" y="160" width="120" height="40" fill="none" stroke="#F5A623" stroke-width="2" rx="5"/>
<text x="620" y="185" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">kb_documents</text>
<!-- Field Details -->
<g font-family="Arial, sans-serif" font-size="11" fill="#666">
<!-- organizations -->
<text x="30" y="115">id, name</text>
<text x="30" y="130">created_at</text>
<!-- bots -->
<text x="210" y="115">id, org_id</text>
<text x="210" y="130">name, config</text>
<!-- users -->
<text x="370" y="115">id, username</text>
<text x="370" y="130">email, active</text>
<!-- user_sessions -->
<text x="530" y="115">id, user_id, bot_id</text>
<text x="530" y="130">token, expires_at</text>
<!-- bot_memories -->
<text x="30" y="215">id, bot_id</text>
<text x="30" y="230">key, value</text>
<!-- message_history -->
<text x="210" y="215">id, session_id</text>
<text x="210" y="230">message, sender</text>
<!-- kb_collections -->
<text x="390" y="215">id, bot_id</text>
<text x="390" y="230">name, description</text>
<!-- kb_documents -->
<text x="570" y="215">id, collection_id</text>
<text x="570" y="230">content, embeddings</text>
</g>
<!-- Relationships -->
<g stroke="#666" stroke-width="2" fill="none">
<!-- organizations to bots -->
<line x1="140" y1="80" x2="200" y2="80" marker-end="url(#arrow)"/>
<!-- users to user_sessions -->
<line x1="460" y1="80" x2="520" y2="80" marker-end="url(#arrow)"/>
<!-- bots to user_sessions -->
<path d="M250,100 Q250,120 580,120 Q580,100 580,100" stroke-dasharray="3,3" marker-end="url(#arrow)" opacity="0.6"/>
<!-- bots to bot_memories -->
<path d="M250,100 Q250,130 80,130 Q80,150 80,160" marker-end="url(#arrow)" opacity="0.6"/>
<!-- user_sessions to message_history -->
<path d="M580,100 Q580,130 260,130 Q260,150 260,160" marker-end="url(#arrow)" opacity="0.6"/>
<!-- bots to kb_collections -->
<path d="M250,100 Q250,130 440,130 Q440,150 440,160" marker-end="url(#arrow)" opacity="0.6"/>
<!-- kb_collections to kb_documents -->
<line x1="500" y1="180" x2="560" y2="180" marker-end="url(#arrow)"/>
</g>
<!-- Relationship labels -->
<text x="170" y="75" font-family="Arial, sans-serif" font-size="11" fill="#666">1:N</text>
<text x="490" y="75" font-family="Arial, sans-serif" font-size="11" fill="#666">1:N</text>
<text x="530" y="175" font-family="Arial, sans-serif" font-size="11" fill="#666">1:N</text>
<text x="165" y="145" font-family="Arial, sans-serif" font-size="11" fill="#666">1:N</text>
<text x="350" y="145" font-family="Arial, sans-serif" font-size="11" fill="#666">1:N</text>
<text x="420" y="145" font-family="Arial, sans-serif" font-size="11" fill="#666">1:N</text>
<!-- Schema Info Box -->
<g transform="translate(20, 260)">
<rect width="760" height="140" fill="none" stroke="#666" stroke-width="1" rx="5" opacity="0.3"/>
<text x="10" y="20" font-family="Arial, sans-serif" font-size="12" font-weight="600" fill="#333">Key Relationships:</text>
<text x="10" y="40" font-family="Arial, sans-serif" font-size="12" fill="#666">• Organizations own multiple Bots</text>
<text x="10" y="55" font-family="Arial, sans-serif" font-size="12" fill="#666">• Users create multiple Sessions with Bots</text>
<text x="10" y="70" font-family="Arial, sans-serif" font-size="12" fill="#666">• Sessions generate Message History</text>
<text x="10" y="85" font-family="Arial, sans-serif" font-size="12" fill="#666">• Bots maintain Memories (key-value pairs)</text>
<text x="10" y="100" font-family="Arial, sans-serif" font-size="12" fill="#666">• Bots have Knowledge Collections containing Documents</text>
<text x="10" y="115" font-family="Arial, sans-serif" font-size="12" fill="#666">• Documents store embeddings for vector search</text>
<text x="10" y="130" font-family="Arial, sans-serif" font-size="12" fill="#666">• All entities use UUIDs as primary keys (except KB collections using TEXT)</text>
</g>
<!-- Description -->
<text x="400" y="430" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#666">
Core database schema supporting multi-tenant bot operations with session management and vector search capabilities
</text>
</svg>
Side by side

Before

Width:  |  Height:  |  Size: 6.4 KiB

217
docs/src/appendix-i/assets/schema-detailed.svg.backup
View file

@ -1,217 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<svg viewBox="0 0 1080 780" xmlns="http://www.w3.org/2000/svg" style="max-width: 100%; height: auto;">
<defs>
<!-- Arrow markers -->
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#2563EB">
</marker>
<!-- Drop shadow for depth -->
<filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
<feGaussianBlur in="SourceAlpha" stdDeviation="2">
<feOffset dx="1" dy="1" result="offsetblur">
<feComponentTransfer>
<feFuncA type="linear" slope="0.2">
</feComponentTransfer>
<feMerge>
<feMergeNode/>
<feMergeNode in="SourceGraphic">
</feMerge>
</filter>
</defs>
<!-- Beautiful gradient definitions for depth -->
<!-- White background with subtle border -->
<rect x="0" y="0" width="1080" height="780" fill="#F9FAFB" stroke="#9CA3AF" stroke-width="2" rx="8">
<!-- Content container with proper margins -->
<g transform="translate(40, 40)">
<!-- Title -->
<text x="500" y="30" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">Database Entity Details</text>
<!-- Organizations Table -->
<g id="organizations">
<rect x="50" y="60" width="400" height="150" fill="none" stroke="#2563EB" stroke-width="2" rx="5" filter="url(#shadow)"/>
<rect x="50" y="60" width="400" height="30" fill="none" stroke="#2563EB" stroke-width="2" rx="5 5 0 0" filter="url(#shadow)"/>
<text x="250" y="80" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">organizations</text>
<g font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563">
<text x="60" y="110" filter="url(#textShadow)">id: UUID (PK)</text>
<text x="60" y="130" filter="url(#textShadow)">name: VARCHAR(255)</text>
<text x="60" y="150" filter="url(#textShadow)">created_at: TIMESTAMPTZ</text>
<text x="60" y="170" filter="url(#textShadow)">updated_at: TIMESTAMPTZ</text>
</g>
</g>
<!-- Bots Table -->
<g id="bots">
<rect x="550" y="60" width="400" height="190" fill="none" stroke="#059669" stroke-width="2" rx="5" filter="url(#shadow)"/>
<rect x="550" y="60" width="400" height="30" fill="none" stroke="#059669" stroke-width="2" rx="5 5 0 0" filter="url(#shadow)"/>
<text x="750" y="80" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">bots</text>
<g font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563">
<text x="560" y="110" filter="url(#textShadow)">id: UUID (PK)</text>
<text x="560" y="130" filter="url(#textShadow)">organization_id: UUID (FK)</text>
<text x="560" y="150" filter="url(#textShadow)">name: VARCHAR(255)</text>
<text x="560" y="170" filter="url(#textShadow)">configuration: JSONB</text>
<text x="560" y="190" filter="url(#textShadow)">created_at: TIMESTAMPTZ</text>
<text x="560" y="210" filter="url(#textShadow)">updated_at: TIMESTAMPTZ</text>
</g>
</g>
<!-- Bot Memories Table -->
<g id="bot_memories">
<rect x="50" y="290" width="280" height="130" fill="none" stroke="#7C3AED" stroke-width="2" rx="5" filter="url(#shadow)"/>
<rect x="50" y="290" width="280" height="30" fill="none" stroke="#7C3AED" stroke-width="2" rx="5 5 0 0" filter="url(#shadow)"/>
<text x="190" y="310" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">bot_memories</text>
<g font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563">
<text x="60" y="340" filter="url(#textShadow)">id: UUID (PK)</text>
<text x="60" y="360" filter="url(#textShadow)">bot_id: UUID (FK)</text>
<text x="60" y="380" filter="url(#textShadow)">key: TEXT</text>
<text x="60" y="400" filter="url(#textShadow)">value: TEXT</text>
</g>
</g>
<!-- User Sessions Table -->
<g id="user_sessions">
<rect x="360" y="290" width="280" height="170" fill="none" stroke="#2563EB" stroke-width="2" rx="5" filter="url(#shadow)"/>
<rect x="360" y="290" width="280" height="30" fill="none" stroke="#2563EB" stroke-width="2" rx="5 5 0 0" filter="url(#shadow)"/>
<text x="500" y="310" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">user_sessions</text>
<g font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563">
<text x="370" y="340" filter="url(#textShadow)">id: UUID (PK)</text>
<text x="370" y="360" filter="url(#textShadow)">user_id: UUID (FK)</text>
<text x="370" y="380" filter="url(#textShadow)">bot_id: UUID (FK)</text>
<text x="370" y="400" filter="url(#textShadow)">session_token: TEXT</text>
<text x="370" y="420" filter="url(#textShadow)">created_at: TIMESTAMPTZ</text>
<text x="370" y="440" filter="url(#textShadow)">expires_at: TIMESTAMPTZ</text>
</g>
</g>
<!-- KB Collections Table -->
<g id="kb_collections">
<rect x="670" y="290" width="280" height="150" fill="none" stroke="#2563EB" stroke-width="2" rx="5" filter="url(#shadow)"/>
<rect x="670" y="290" width="280" height="30" fill="none" stroke="#2563EB" stroke-width="2" rx="5 5 0 0" filter="url(#shadow)"/>
<text x="810" y="310" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">kb_collections</text>
<g font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563">
<text x="680" y="340" filter="url(#textShadow)">id: TEXT (PK)</text>
<text x="680" y="360" filter="url(#textShadow)">bot_id: UUID (FK)</text>
<text x="680" y="380" filter="url(#textShadow)">name: TEXT</text>
<text x="680" y="400" filter="url(#textShadow)">description: TEXT</text>
<text x="680" y="420" filter="url(#textShadow)">created_at: TIMESTAMPTZ</text>
</g>
</g>
<!-- Users Table -->
<g id="users">
<rect x="50" y="480" width="280" height="170" fill="none" stroke="#DC2626" stroke-width="2" rx="5" filter="url(#shadow)"/>
<rect x="50" y="480" width="280" height="30" fill="none" stroke="#DC2626" stroke-width="2" rx="5 5 0 0" filter="url(#shadow)"/>
<text x="190" y="500" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">users</text>
<g font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563">
<text x="60" y="530" filter="url(#textShadow)">id: UUID (PK)</text>
<text x="60" y="550" filter="url(#textShadow)">username: TEXT</text>
<text x="60" y="570" filter="url(#textShadow)">email: TEXT</text>
<text x="60" y="590" filter="url(#textShadow)">password_hash: TEXT</text>
<text x="60" y="610" filter="url(#textShadow)">active: BOOLEAN</text>
<text x="60" y="630" filter="url(#textShadow)">created_at: TIMESTAMPTZ</text>
</g>
</g>
<!-- Message History Table -->
<g id="message_history">
<rect x="360" y="480" width="280" height="170" fill="none" stroke="#2563EB" stroke-width="2" rx="5" filter="url(#shadow)"/>
<rect x="360" y="480" width="280" height="30" fill="none" stroke="#2563EB" stroke-width="2" rx="5 5 0 0" filter="url(#shadow)"/>
<text x="500" y="500" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">message_history</text>
<g font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563">
<text x="370" y="530" filter="url(#textShadow)">id: UUID (PK)</text>
<text x="370" y="550" filter="url(#textShadow)">session_id: UUID (FK)</text>
<text x="370" y="570" filter="url(#textShadow)">user_id: UUID (FK)</text>
<text x="370" y="590" filter="url(#textShadow)">bot_id: UUID (FK)</text>
<text x="370" y="610" filter="url(#textShadow)">message: TEXT</text>
<text x="370" y="630" filter="url(#textShadow)">sender: TEXT</text>
</g>
</g>
<!-- KB Documents Table -->
<g id="kb_documents">
<rect x="670" y="480" width="280" height="170" fill="none" stroke="#2563EB" stroke-width="2" rx="5" filter="url(#shadow)"/>
<rect x="670" y="480" width="280" height="30" fill="none" stroke="#2563EB" stroke-width="2" rx="5 5 0 0" filter="url(#shadow)"/>
<text x="810" y="500" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">kb_documents</text>
<g font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563">
<text x="680" y="530" filter="url(#textShadow)">id: UUID (PK)</text>
<text x="680" y="550" filter="url(#textShadow)">collection_id: TEXT (FK)</text>
<text x="680" y="570" filter="url(#textShadow)">content: TEXT</text>
<text x="680" y="590" filter="url(#textShadow)">embeddings: VECTOR</text>
<text x="680" y="610" filter="url(#textShadow)">metadata: JSONB</text>
<text x="680" y="630" filter="url(#textShadow)">created_at: TIMESTAMPTZ</text>
</g>
</g>
<!-- Relationships -->
<g stroke="#6B7280" stroke-width="2" fill="none">
<!-- organizations to bots -->
<line x1="450" y1="135" x2="550" y2="135" marker-end="url(#arrow)">
<text x="500" y="130" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N</text>
<!-- bots to bot_memories -->
<line x1="750" y1="250" x2="190" y2="290" marker-end="url(#arrow)">
<text x="470" y="270" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N</text>
<!-- bots to user_sessions -->
<line x1="750" y1="250" x2="500" y2="290" marker-end="url(#arrow)">
<!-- bots to kb_collections -->
<line x1="750" y1="250" x2="810" y2="290" marker-end="url(#arrow)">
<text x="780" y="270" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N</text>
<!-- kb_collections to kb_documents -->
<line x1="810" y1="440" x2="810" y2="480" marker-end="url(#arrow)">
<text x="825" y="460" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N</text>
<!-- user_sessions to message_history -->
<line x1="500" y1="460" x2="500" y2="480" marker-end="url(#arrow)">
<text x="515" y="470" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N</text>
<!-- users to user_sessions (dotted) -->
<path d="M 330 565 L 360 390" stroke-dasharray="5,5" marker-end="url(#arrow)" opacity="0.6">
<text x="345" y="475" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N</text>
</g>
<!-- Legend -->
<g id="legend" transform="translate(50, 670)">
<text x="0" y="0" font-family="system-ui, -apple-system, sans-serif" font-size="14" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">Color Coding:</text>
<rect x="100" y="-10" width="20" height="10" fill="none" stroke="#2563EB" stroke-width="2" rx="8" filter="url(#shadow)"/>
<text x="125" y="0" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Organization</text>
<rect x="220" y="-10" width="20" height="10" fill="none" stroke="#059669" stroke-width="2" rx="8" filter="url(#shadow)"/>
<text x="245" y="0" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Bot Core</text>
<rect x="320" y="-10" width="20" height="10" fill="none" stroke="#2563EB" stroke-width="2" rx="8" filter="url(#shadow)"/>
<text x="345" y="0" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Sessions</text>
<rect x="420" y="-10" width="20" height="10" fill="none" stroke="#2563EB" stroke-width="2" rx="8" filter="url(#shadow)"/>
<text x="445" y="0" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Knowledge</text>
<rect x="530" y="-10" width="20" height="10" fill="none" stroke="#DC2626" stroke-width="2" rx="8" filter="url(#shadow)"/>
<text x="555" y="0" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Users</text>
<rect x="620" y="-10" width="20" height="10" fill="none" stroke="#2563EB" stroke-width="2" rx="8" filter="url(#shadow)"/>
<text x="645" y="0" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Messages</text>
</g>
</g>
</svg>
Side by side

Before

Width:  |  Height:  |  Size: 13 KiB

131
docs/src/appendix-i/assets/schema-overview.svg
View file

@ -1,131 +0,0 @@
<svg width="800" height="400" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#666"/>
</marker>
</defs>
<!-- Title -->
<text x="400" y="25" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="600" fill="#333">Database Schema Overview</text>
<!-- Top Level -->
<!-- Organizations -->
<rect x="20" y="60" width="120" height="40" fill="none" stroke="#4A90E2" stroke-width="2" rx="5"/>
<text x="80" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">organizations</text>
<!-- Bots -->
<rect x="200" y="60" width="100" height="40" fill="none" stroke="#7ED321" stroke-width="2" rx="5"/>
<text x="250" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">bots</text>
<!-- Bot Configuration -->
<rect x="360" y="60" width="120" height="40" fill="none" stroke="#F5A623" stroke-width="2" rx="5"/>
<text x="420" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">bot_configuration</text>
<!-- Users -->
<rect x="540" y="60" width="100" height="40" fill="none" stroke="#BD10E0" stroke-width="2" rx="5"/>
<text x="590" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">users</text>
<!-- Middle Layer -->
<!-- Bot Memories -->
<rect x="20" y="140" width="120" height="40" fill="none" stroke="#50E3C2" stroke-width="2" rx="5"/>
<text x="80" y="165" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">bot_memories</text>
<!-- KB Collections -->
<rect x="180" y="140" width="120" height="40" fill="none" stroke="#4A90E2" stroke-width="2" rx="5"/>
<text x="240" y="165" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">kb_collections</text>
<!-- User Sessions -->
<rect x="340" y="140" width="120" height="40" fill="none" stroke="#F5A623" stroke-width="2" rx="5"/>
<text x="400" y="165" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">user_sessions</text>
<!-- Basic Tools -->
<rect x="500" y="140" width="100" height="40" fill="none" stroke="#7ED321" stroke-width="2" rx="5"/>
<text x="550" y="165" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">basic_tools</text>
<!-- Message History -->
<rect x="640" y="140" width="120" height="40" fill="none" stroke="#BD10E0" stroke-width="2" rx="5"/>
<text x="700" y="165" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">message_history</text>
<!-- Bottom Layer -->
<!-- KB Documents -->
<rect x="20" y="220" width="120" height="40" fill="none" stroke="#50E3C2" stroke-width="2" rx="5"/>
<text x="80" y="245" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">kb_documents</text>
<!-- User Login Tokens -->
<rect x="180" y="220" width="140" height="40" fill="none" stroke="#4A90E2" stroke-width="2" rx="5"/>
<text x="250" y="245" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">user_login_tokens</text>
<!-- User KB Associations -->
<rect x="360" y="220" width="160" height="40" fill="none" stroke="#F5A623" stroke-width="2" rx="5"/>
<text x="440" y="245" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">user_kb_associations</text>
<!-- Session Tool Associations -->
<rect x="560" y="220" width="180" height="40" fill="none" stroke="#7ED321" stroke-width="2" rx="5"/>
<text x="650" y="245" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">session_tool_associations</text>
<!-- Arrows -->
<g stroke="#666" stroke-width="2" fill="none">
<!-- organizations to bots -->
<line x1="140" y1="80" x2="200" y2="80" marker-end="url(#arrow)"/>
<!-- bots to bot_configuration -->
<line x1="300" y1="80" x2="360" y2="80" marker-end="url(#arrow)"/>
<!-- bots to bot_memories -->
<path d="M250,100 Q250,120 80,120 Q80,130 80,140" marker-end="url(#arrow)" opacity="0.6"/>
<!-- bots to kb_collections -->
<path d="M250,100 Q250,120 240,120 Q240,130 240,140" marker-end="url(#arrow)" opacity="0.6"/>
<!-- users to user_sessions -->
<path d="M590,100 Q590,120 400,120 Q400,130 400,140" marker-end="url(#arrow)" opacity="0.6"/>
<!-- user_sessions to message_history -->
<path d="M460,160 Q530,160 640,160" marker-end="url(#arrow)" opacity="0.6"/>
<!-- kb_collections to kb_documents -->
<path d="M240,180 Q240,200 80,200 Q80,210 80,220" marker-end="url(#arrow)" opacity="0.6"/>
<!-- users to user_login_tokens -->
<path d="M590,100 Q590,200 250,200 Q250,210 250,220" stroke-dasharray="3,3" marker-end="url(#arrow)" opacity="0.4"/>
<!-- user_sessions to user_kb_associations -->
<path d="M400,180 Q400,200 440,200 Q440,210 440,220" marker-end="url(#arrow)" opacity="0.6"/>
<!-- user_sessions to session_tool_associations -->
<path d="M460,160 Q550,190 650,220" marker-end="url(#arrow)" opacity="0.6"/>
<!-- session_tool_associations refs basic_tools -->
<path d="M650,220 Q650,200 550,200 Q550,190 550,180" stroke-dasharray="3,3" marker-end="url(#arrow)" opacity="0.4"/>
<!-- user_kb_associations refs kb_collections -->
<path d="M440,220 Q440,200 240,200 Q240,190 240,180" stroke-dasharray="3,3" marker-end="url(#arrow)" opacity="0.4"/>
</g>
<!-- Relationship Labels -->
<text x="170" y="75" font-family="Arial, sans-serif" font-size="11" fill="#666">1:N</text>
<text x="330" y="75" font-family="Arial, sans-serif" font-size="11" fill="#666">1:N</text>
<text x="165" y="135" font-family="Arial, sans-serif" font-size="11" fill="#666">1:N</text>
<text x="245" y="135" font-family="Arial, sans-serif" font-size="11" fill="#666">1:N</text>
<text x="495" y="135" font-family="Arial, sans-serif" font-size="11" fill="#666">1:N</text>
<text x="550" y="155" font-family="Arial, sans-serif" font-size="11" fill="#666">1:N</text>
<text x="160" y="210" font-family="Arial, sans-serif" font-size="11" fill="#666">1:N</text>
<text x="420" y="210" font-family="Arial, sans-serif" font-size="11" fill="#666">1:N</text>
<text x="550" y="210" font-family="Arial, sans-serif" font-size="11" fill="#666">1:N</text>
<text x="340" y="210" font-family="Arial, sans-serif" font-size="11" fill="#666">ref</text>
<text x="600" y="210" font-family="Arial, sans-serif" font-size="11" fill="#666">ref</text>
<!-- Info Box -->
<g transform="translate(20, 290)">
<rect width="760" height="80" fill="none" stroke="#666" stroke-width="1" rx="5" opacity="0.3"/>
<text x="10" y="20" font-family="Arial, sans-serif" font-size="12" font-weight="600" fill="#333">Entity Categories:</text>
<text x="10" y="40" font-family="Arial, sans-serif" font-size="12" fill="#666">Core: organizations, bots, users • State: bot_memories, user_sessions, message_history</text>
<text x="10" y="55" font-family="Arial, sans-serif" font-size="12" fill="#666">Knowledge: kb_collections, kb_documents • Tools: basic_tools • Auth: user_login_tokens</text>
<text x="10" y="70" font-family="Arial, sans-serif" font-size="12" fill="#666">Associations: user_kb_associations, session_tool_associations, bot_configuration</text>
</g>
<!-- Description -->
<text x="400" y="390" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#666">
Multi-tenant database schema supporting organizations with multiple bots, user sessions, knowledge bases, and tools
</text>
</svg>
Side by side

Before

Width:  |  Height:  |  Size: 7.5 KiB

170
docs/src/appendix-i/assets/schema-overview.svg.backup
View file

@ -1,170 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<svg viewBox="0 0 980 680" xmlns="http://www.w3.org/2000/svg" style="max-width: 100%; height: auto;">
<defs>
<!-- Arrow markers -->
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#2563EB">
</marker>
<!-- Drop shadow for depth -->
<filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
<feGaussianBlur in="SourceAlpha" stdDeviation="2">
<feOffset dx="1" dy="1" result="offsetblur">
<feComponentTransfer>
<feFuncA type="linear" slope="0.2">
</feComponentTransfer>
<feMerge>
<feMergeNode/>
<feMergeNode in="SourceGraphic">
</feMerge>
</filter>
</defs>
<!-- Beautiful gradient definitions for depth -->
<!-- White background with subtle border -->
<rect x="0" y="0" width="980" height="680" fill="#F9FAFB" stroke="#9CA3AF" stroke-width="2" rx="8">
<!-- Content container with proper margins -->
<g transform="translate(40, 40)">
<!-- Title -->
<text x="450" y="30" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">Database Schema Overview</text>
<!-- Organizations -->
<rect x="50" y="60" width="180" height="60" fill="none" stroke="#2563EB" stroke-width="2" rx="5" filter="url(#shadow)"/>
<text x="140" y="85" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">organizations</text>
<text x="140" y="105" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Top Level Entity</text>
<!-- Bots -->
<rect x="320" y="60" width="180" height="60" fill="none" stroke="#059669" stroke-width="2" rx="5" filter="url(#shadow)"/>
<text x="410" y="85" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">bots</text>
<text x="410" y="105" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Bot Instances</text>
<!-- Bot Configuration -->
<rect x="590" y="60" width="180" height="60" fill="none" stroke="#EA580C" stroke-width="2" rx="5" filter="url(#shadow)"/>
<text x="680" y="85" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">bot_configuration</text>
<text x="680" y="105" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Settings</text>
<!-- Bot Memories -->
<rect x="220" y="180" width="180" height="60" fill="none" stroke="#7C3AED" stroke-width="2" rx="5" filter="url(#shadow)"/>
<text x="310" y="205" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">bot_memories</text>
<text x="310" y="225" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">State Storage</text>
<!-- KB Collections -->
<rect x="420" y="180" width="180" height="60" fill="none" stroke="#2563EB" stroke-width="2" rx="5" filter="url(#shadow)"/>
<text x="510" y="205" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">kb_collections</text>
<text x="510" y="225" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Knowledge Base</text>
<!-- KB Documents -->
<rect x="420" y="280" width="180" height="60" fill="none" stroke="#2563EB" stroke-width="2" rx="5" filter="url(#shadow)"/>
<text x="510" y="305" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">kb_documents</text>
<text x="510" y="325" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Documents</text>
<!-- Users -->
<rect x="50" y="380" width="180" height="60" fill="none" stroke="#DC2626" stroke-width="2" rx="5" filter="url(#shadow)"/>
<text x="140" y="405" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">users</text>
<text x="140" y="425" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">User Accounts</text>
<!-- User Sessions -->
<rect x="320" y="380" width="180" height="60" fill="none" stroke="#2563EB" stroke-width="2" rx="5" filter="url(#shadow)"/>
<text x="410" y="405" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">user_sessions</text>
<text x="410" y="425" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Active Sessions</text>
<!-- Message History -->
<rect x="590" y="380" width="180" height="60" fill="none" stroke="#2563EB" stroke-width="2" rx="5" filter="url(#shadow)"/>
<text x="680" y="405" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">message_history</text>
<text x="680" y="425" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#1F2937" filter="url(#textShadow)">Chat Messages</text>
<!-- User Login Tokens -->
<rect x="50" y="480" width="180" height="60" fill="none" stroke="#2563EB" stroke-width="2" rx="5" filter="url(#shadow)"/>
<text x="140" y="505" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">user_login_tokens</text>
<text x="140" y="525" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Auth Tokens</text>
<!-- User KB Associations -->
<rect x="320" y="480" width="180" height="60" fill="none" stroke="#2563EB" stroke-width="2" rx="5" filter="url(#shadow)"/>
<text x="410" y="505" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">user_kb_associations</text>
<text x="410" y="525" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">KB Access</text>
<!-- Session Tool Associations -->
<rect x="590" y="480" width="180" height="60" fill="none" stroke="#2563EB" stroke-width="2" rx="5" filter="url(#shadow)"/>
<text x="680" y="505" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">session_tool_associations</text>
<text x="680" y="525" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Tool Access</text>
<!-- Basic Tools -->
<rect x="650" y="280" width="180" height="60" fill="none" stroke="#2563EB" stroke-width="2" rx="5" filter="url(#shadow)"/>
<text x="740" y="305" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">basic_tools</text>
<text x="740" y="325" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">BASIC Scripts</text>
<!-- Relationships -->
<g stroke="#6B7280" stroke-width="2" fill="none">
<!-- organizations to bots -->
<line x1="230" y1="90" x2="320" y2="90" marker-end="url(#arrow)">
<text x="275" y="85" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N</text>
<!-- bots to bot_configuration -->
<line x1="500" y1="90" x2="590" y2="90" marker-end="url(#arrow)">
<text x="545" y="85" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N</text>
<!-- bots to bot_memories -->
<line x1="360" y1="120" x2="310" y2="180" marker-end="url(#arrow)">
<text x="330" y="150" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N</text>
<!-- bots to kb_collections -->
<line x1="460" y1="120" x2="510" y2="180" marker-end="url(#arrow)">
<text x="485" y="150" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N</text>
<!-- kb_collections to kb_documents -->
<line x1="510" y1="240" x2="510" y2="280" marker-end="url(#arrow)">
<text x="525" y="260" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N</text>
<!-- users to user_sessions -->
<line x1="230" y1="410" x2="320" y2="410" marker-end="url(#arrow)">
<text x="275" y="405" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N</text>
<!-- user_sessions to message_history -->
<line x1="500" y1="410" x2="590" y2="410" marker-end="url(#arrow)">
<text x="545" y="405" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N</text>
<!-- users to user_login_tokens -->
<line x1="140" y1="440" x2="140" y2="480" marker-end="url(#arrow)">
<text x="155" y="460" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N</text>
<!-- user_sessions to user_kb_associations -->
<line x1="410" y1="440" x2="410" y2="480" marker-end="url(#arrow)">
<text x="425" y="460" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N</text>
<!-- user_sessions to session_tool_associations -->
<line x1="480" y1="440" x2="620" y2="480" marker-end="url(#arrow)">
<text x="550" y="460" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N</text>
<!-- user_kb_associations to kb_collections (reference) -->
<path d="M 410 480 Q 410 360 510 240" stroke-dasharray="5,5" marker-end="url(#arrow)" opacity="0.6">
<text x="450" y="360" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">ref</text>
<!-- session_tool_associations to basic_tools (reference) -->
<path d="M 680 480 Q 740 400 740 340" stroke-dasharray="5,5" marker-end="url(#arrow)" opacity="0.6">
<text x="710" y="410" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">ref</text>
<!-- bots to user_sessions (cross reference) -->
<path d="M 410 120 Q 410 250 410 380" stroke-dasharray="3,3" opacity="0.4">
</g>
<!-- Legend -->
<g id="legend" transform="translate(50, 550)">
<text x="0" y="0" font-family="system-ui, -apple-system, sans-serif" font-size="14" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">Legend:</text>
<line x1="80" y1="-5" x2="120" y2="-5" stroke="#6B7280" stroke-width="2" marker-end="url(#arrow)">
<text x="125" y="0" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">1:N Relationship</text>
<line x1="250" y1="-5" x2="290" y2="-5" stroke="#6B7280" stroke-width="2" stroke-dasharray="5,5" marker-end="url(#arrow)" opacity="0.6">
<text x="295" y="0" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Reference</text>
</g>
</g>
</svg>
Side by side

Before

Width:  |  Height:  |  Size: 12 KiB

126
docs/src/appendix-i/assets/session-flow.svg
View file

@ -1,126 +0,0 @@
<svg width="800" height="320" xmlns="http://www.w3.org/2000/svg">
<defs>
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#666"/>
</marker>
</defs>
<!-- Title -->
<text x="400" y="25" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="600" fill="#333">Session Flow Diagram</text>
<!-- User Login -->
<rect x="20" y="60" width="100" height="40" fill="none" stroke="#4A90E2" stroke-width="2" rx="5"/>
<text x="70" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">User Login</text>
<!-- users table -->
<rect x="180" y="60" width="100" height="40" fill="none" stroke="#F5A623" stroke-width="2" rx="5"/>
<text x="230" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">users</text>
<!-- user_sessions table -->
<rect x="340" y="60" width="120" height="40" fill="none" stroke="#BD10E0" stroke-width="2" rx="5"/>
<text x="400" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">user_sessions</text>
<!-- message_history table -->
<rect x="520" y="60" width="120" height="40" fill="none" stroke="#7ED321" stroke-width="2" rx="5"/>
<text x="580" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">message_history</text>
<!-- Session Token -->
<rect x="700" y="60" width="80" height="40" fill="none" stroke="#50E3C2" stroke-width="2" rx="5"/>
<text x="740" y="85" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">Token</text>
<!-- Additional Tables -->
<rect x="180" y="160" width="140" height="40" fill="none" stroke="#4A90E2" stroke-width="2" rx="5"/>
<text x="250" y="185" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">user_login_tokens</text>
<rect x="360" y="160" width="160" height="40" fill="none" stroke="#F5A623" stroke-width="2" rx="5"/>
<text x="440" y="185" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">user_kb_associations</text>
<rect x="560" y="160" width="180" height="40" fill="none" stroke="#7ED321" stroke-width="2" rx="5"/>
<text x="650" y="185" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" fill="#333">session_tool_associations</text>
<!-- Field Details -->
<g font-family="Arial, sans-serif" font-size="11" fill="#666">
<!-- users fields -->
<text x="190" y="115">id, email</text>
<text x="190" y="130">zitadel_id</text>
<!-- user_sessions fields -->
<text x="350" y="115">id, user_id, bot_id</text>
<text x="350" y="130">token, expires_at</text>
<!-- message_history fields -->
<text x="530" y="115">id, session_id</text>
<text x="530" y="130">role, content</text>
<!-- Token info -->
<text x="710" y="115">JWT/UUID</text>
<text x="710" y="130">Auth</text>
<!-- user_login_tokens fields -->
<text x="190" y="215">id, user_id, token</text>
<text x="190" y="230">expires_at</text>
<!-- user_kb_associations fields -->
<text x="370" y="215">id, session_id</text>
<text x="370" y="230">kb_id, created_at</text>
<!-- session_tool_associations fields -->
<text x="570" y="215">id, session_id</text>
<text x="570" y="230">tool_name, added_at</text>
</g>
<!-- Flow Arrows -->
<g stroke="#666" stroke-width="2" fill="none">
<!-- Main flow -->
<line x1="120" y1="80" x2="180" y2="80" marker-end="url(#arrow)"/>
<line x1="280" y1="80" x2="340" y2="80" marker-end="url(#arrow)"/>
<line x1="460" y1="80" x2="520" y2="80" marker-end="url(#arrow)"/>
<line x1="640" y1="80" x2="700" y2="80" marker-end="url(#arrow)"/>
<!-- users to user_login_tokens -->
<path d="M230,100 Q230,130 250,130 Q250,150 250,160" marker-end="url(#arrow)" opacity="0.6"/>
<!-- user_sessions to associations -->
<path d="M400,100 Q400,130 440,130 Q440,150 440,160" marker-end="url(#arrow)" opacity="0.6"/>
<path d="M460,80 Q550,130 650,160" marker-end="url(#arrow)" opacity="0.6"/>
</g>
<!-- Labels -->
<text x="150" y="75" font-family="Arial, sans-serif" font-size="11" fill="#666">Creates</text>
<text x="310" y="75" font-family="Arial, sans-serif" font-size="11" fill="#666">Establishes</text>
<text x="490" y="75" font-family="Arial, sans-serif" font-size="11" fill="#666">Logs</text>
<text x="670" y="75" font-family="Arial, sans-serif" font-size="11" fill="#666">Returns</text>
<text x="240" y="145" font-family="Arial, sans-serif" font-size="11" fill="#666">Stores</text>
<text x="420" y="145" font-family="Arial, sans-serif" font-size="11" fill="#666">Links KB</text>
<text x="550" y="145" font-family="Arial, sans-serif" font-size="11" fill="#666">Links Tools</text>
<!-- Process Steps -->
<g font-family="Arial, sans-serif" font-size="12" fill="#333">
<circle cx="70" cy="60" r="12" fill="none" stroke="#666" stroke-width="1"/>
<text x="70" y="65" text-anchor="middle">1</text>
<circle cx="230" cy="60" r="12" fill="none" stroke="#666" stroke-width="1"/>
<text x="230" y="65" text-anchor="middle">2</text>
<circle cx="400" cy="60" r="12" fill="none" stroke="#666" stroke-width="1"/>
<text x="400" y="65" text-anchor="middle">3</text>
<circle cx="580" cy="60" r="12" fill="none" stroke="#666" stroke-width="1"/>
<text x="580" y="65" text-anchor="middle">4</text>
<circle cx="740" cy="60" r="12" fill="none" stroke="#666" stroke-width="1"/>
<text x="740" y="65" text-anchor="middle">5</text>
</g>
<!-- Process Description Box -->
<g transform="translate(20, 250)">
<rect width="760" height="50" fill="none" stroke="#666" stroke-width="1" rx="5" opacity="0.3"/>
<text x="10" y="20" font-family="Arial, sans-serif" font-size="12" font-weight="600" fill="#333">Process Flow:</text>
<text x="10" y="40" font-family="Arial, sans-serif" font-size="12" fill="#666">1. User authenticates → 2. User record created/updated → 3. Session established → 4. Messages logged → 5. Token returned</text>
</g>
<!-- Description -->
<text x="400" y="45" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#666">
Authentication flow from login through session establishment and message tracking
</text>
</svg>
Side by side

Before

Width:  |  Height:  |  Size: 6.3 KiB

126
docs/src/appendix-i/assets/session-flow.svg.backup
View file

@ -1,126 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<svg viewBox="0 0 780 580" xmlns="http://www.w3.org/2000/svg" style="max-width: 100%; height: auto;">
<defs>
<!-- Arrow markers -->
<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
<path d="M0,0 L0,6 L9,3 z" fill="#2563EB">
</marker>
<!-- Drop shadow for depth -->
<filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
<feGaussianBlur in="SourceAlpha" stdDeviation="2">
<feOffset dx="1" dy="1" result="offsetblur">
<feComponentTransfer>
<feFuncA type="linear" slope="0.2">
</feComponentTransfer>
<feMerge>
<feMergeNode/>
<feMergeNode in="SourceGraphic">
</feMerge>
</filter>
</defs>
<!-- Beautiful gradient definitions for depth -->
<!-- White background with subtle border -->
<rect x="0" y="0" width="780" height="580" fill="#F9FAFB" stroke="#9CA3AF" stroke-width="2" rx="8">
<!-- Content container with proper margins -->
<g transform="translate(40, 40)">
<!-- Title -->
<text x="350" y="30" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">Session Flow Diagram</text>
<!-- User Login -->
<rect x="50" y="70" width="180" height="80" fill="none" stroke="#2563EB" stroke-width="2" rx="8" filter="url(#shadow)"/>
<text x="140" y="100" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">User Login</text>
<text x="140" y="120" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Authentication</text>
<text x="140" y="135" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Entry Point</text>
<!-- Arrow -->
<line x1="230" y1="110" x2="280" y2="110" stroke="#6B7280" stroke-width="2" marker-end="url(#arrow)">
<text x="255" y="100" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Creates</text>
<!-- users table -->
<rect x="280" y="70" width="180" height="130" fill="none" stroke="#DC2626" stroke-width="2" rx="8" filter="url(#shadow)"/>
<rect x="280" y="70" width="180" height="30" fill="none" stroke="#DC2626" stroke-width="2" rx="8 8 0 0" filter="url(#shadow)"/>
<text x="370" y="90" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">users</text>
<g font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563">
<text x="290" y="120" filter="url(#textShadow)">• id</text>
<text x="290" y="135" filter="url(#textShadow)">• email</text>
<text x="290" y="150" filter="url(#textShadow)">• zitadel_id</text>
<text x="290" y="165" filter="url(#textShadow)">• created_at</text>
<text x="290" y="180" filter="url(#textShadow)">• updated_at</text>
</g>
<!-- Arrow down -->
<line x1="370" y1="200" x2="370" y2="240" stroke="#6B7280" stroke-width="2" marker-end="url(#arrow)">
<text x="385" y="220" text-anchor="start" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Creates</text>
<!-- user_sessions table -->
<rect x="280" y="240" width="180" height="150" fill="none" stroke="#2563EB" stroke-width="2" rx="8" filter="url(#shadow)"/>
<rect x="280" y="240" width="180" height="30" fill="none" stroke="#2563EB" stroke-width="2" rx="8 8 0 0" filter="url(#shadow)"/>
<text x="370" y="260" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">user_sessions</text>
<g font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563">
<text x="290" y="290" filter="url(#textShadow)">• id</text>
<text x="290" y="305" filter="url(#textShadow)">• user_id</text>
<text x="290" y="320" filter="url(#textShadow)">• bot_id</text>
<text x="290" y="335" filter="url(#textShadow)">• token</text>
<text x="290" y="350" filter="url(#textShadow)">• created_at</text>
<text x="290" y="365" filter="url(#textShadow)">• expires_at</text>
</g>
<!-- Arrow to message_history -->
<line x1="460" y1="315" x2="510" y2="315" stroke="#6B7280" stroke-width="2" marker-end="url(#arrow)">
<text x="485" y="305" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Generates</text>
<text x="485" y="325" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563" filter="url(#textShadow)">Messages</text>
<!-- message_history table -->
<rect x="510" y="240" width="180" height="150" fill="none" stroke="#7C3AED" stroke-width="2" rx="8" filter="url(#shadow)"/>
<rect x="510" y="240" width="180" height="30" fill="none" stroke="#7C3AED" stroke-width="2" rx="8 8 0 0" filter="url(#shadow)"/>
<text x="600" y="260" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">message_history</text>
<g font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563">
<text x="520" y="290" filter="url(#textShadow)">• id</text>
<text x="520" y="305" filter="url(#textShadow)">• session_id</text>
<text x="520" y="320" filter="url(#textShadow)">• role</text>
<text x="520" y="335" filter="url(#textShadow)">• content</text>
<text x="520" y="350" filter="url(#textShadow)">• timestamp</text>
<text x="520" y="365" filter="url(#textShadow)">• metadata</text>
</g>
<!-- Flow indicators -->
<g id="flow-numbers" font-family="system-ui, -apple-system, sans-serif" font-size="14" font-weight="bold" fill="#4B5563">
<circle cx="140" cy="70" r="15" fill="none" stroke="#2563EB" stroke-width="2">
<text x="140" y="75" text-anchor="middle" filter="url(#textShadow)">1</text>
<circle cx="370" cy="70" r="15" fill="none" stroke="#2563EB" stroke-width="2">
<text x="370" y="75" text-anchor="middle" filter="url(#textShadow)">2</text>
<circle cx="370" cy="240" r="15" fill="none" stroke="#2563EB" stroke-width="2">
<text x="370" y="245" text-anchor="middle" filter="url(#textShadow)">3</text>
<circle cx="600" cy="240" r="15" fill="none" stroke="#2563EB" stroke-width="2">
<text x="600" y="245" text-anchor="middle" filter="url(#textShadow)">4</text>
</g>
<!-- Process description -->
<g id="process-description" transform="translate(50, 420)">
<rect x="0" y="0" width="600" height="60" fill="none" stroke="#2563EB" stroke-width="2" rx="5" stroke-dasharray="2,2" opacity="0.5" filter="url(#shadow)"/>
<text x="300" y="20" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="14" font-weight="bold" fill="#4B5563" filter="url(#textShadow)">Process Flow</text>
<g font-family="system-ui, -apple-system, sans-serif" font-size="14" fill="#4B5563">
<text x="20" y="45" filter="url(#textShadow)">1. User authenticates → 2. User record created/updated → 3. Session established → 4. Messages logged</text>
</g>
</g>
</g>
</svg>
Side by side

Before

Width:  |  Height:  |  Size: 7.3 KiB

366
docs/src/assets/migration-architecture.svg Normal file
View file

@ -0,0 +1,366 @@
<svg viewBox="0 0 1400 900" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
<style>
/* Ensure transparent background */
svg {
background: transparent !important;
}
/* CSS Custom Properties for theme switching */
:root {
/* Light theme defaults */
--main-text-color: #1a1a1a;
--secondary-text-color: #666;
--arrow-color: #666;
/* Neon colors for light theme */
--neon-blue: #4A90E2;
--neon-orange: #F5A623;
--neon-purple: #BD10E0;
--neon-green: #7ED321;
--neon-cyan: #50E3C2;
--neon-red: #E24A4A;
--neon-stroke-width: 2.6;
}
/* Dark theme override */
@media (prefers-color-scheme: dark) {
:root {
--main-text-color: #FFFFFF;
--secondary-text-color: #B0B0B0;
--arrow-color: #B0B0B0;
/* Neon colors for dark theme */
--neon-blue: #00D4FF;
--neon-orange: #FF9500;
--neon-purple: #E040FB;
--neon-green: #00FF88;
--neon-cyan: #00E5EA;
--neon-red: #FF4A4A;
--neon-stroke-width: 2.8;
}
}
/* Classes using CSS custom properties */
.neon-blue {
stroke: var(--neon-blue);
stroke-width: var(--neon-stroke-width);
fill: none;
}
.neon-orange {
stroke: var(--neon-orange);
stroke-width: var(--neon-stroke-width);
fill: none;
}
.neon-purple {
stroke: var(--neon-purple);
stroke-width: var(--neon-stroke-width);
fill: none;
}
.neon-green {
stroke: var(--neon-green);
stroke-width: var(--neon-stroke-width);
fill: none;
}
.neon-cyan {
stroke: var(--neon-cyan);
stroke-width: var(--neon-stroke-width);
fill: none;
}
.neon-red {
stroke: var(--neon-red);
stroke-width: var(--neon-stroke-width);
fill: none;
}
.main-text {
fill: var(--main-text-color);
}
.secondary-text {
fill: var(--secondary-text-color);
}
.arrow-line {
stroke: var(--arrow-color);
fill: none;
}
.arrow-head {
fill: var(--arrow-color);
stroke: none;
}
/* Dark theme glow effects */
@media (prefers-color-scheme: dark) {
.neon-blue {
filter: drop-shadow(0 0 4px #00D4FF) drop-shadow(0 0 8px #00A0FF);
}
.neon-orange {
filter: drop-shadow(0 0 4px #FF9500) drop-shadow(0 0 8px #FF7700);
}
.neon-purple {
filter: drop-shadow(0 0 4px #E040FB) drop-shadow(0 0 8px #D500F9);
}
.neon-green {
filter: drop-shadow(0 0 4px #00FF88) drop-shadow(0 0 8px #00E676);
}
.neon-cyan {
filter: drop-shadow(0 0 4px #00E5EA) drop-shadow(0 0 8px #00BCD4);
}
.neon-red {
filter: drop-shadow(0 0 4px #FF4A4A) drop-shadow(0 0 8px #FF0000);
}
}
</style>
<defs>
<marker id="arrowhead" markerWidth="10" markerHeight="7" refX="10" refY="3.5" orient="auto">
<polygon points="0 0, 10 3.5, 0 7" class="arrow-head"/>
</marker>
<linearGradient id="migrationGradient" x1="0%" y1="0%" x2="100%" y2="0%">
<stop offset="0%" style="stop-color:#E24A4A;stop-opacity:0.3" />
<stop offset="50%" style="stop-color:#F5A623;stop-opacity:0.3" />
<stop offset="100%" style="stop-color:#7ED321;stop-opacity:0.3" />
</linearGradient>
</defs>
<!-- Title -->
<text x="700" y="45" text-anchor="middle" font-family="Arial, sans-serif" font-size="32" font-weight="600" class="main-text">Enterprise Migration Architecture</text>
<!-- Section Labels -->
<text x="250" y="95" text-anchor="middle" font-family="Arial, sans-serif" font-size="21" font-weight="500" class="secondary-text">Current State</text>
<text x="700" y="95" text-anchor="middle" font-family="Arial, sans-serif" font-size="21" font-weight="500" class="secondary-text">Migration Process</text>
<text x="1150" y="95" text-anchor="middle" font-family="Arial, sans-serif" font-size="21" font-weight="500" class="secondary-text">Target State</text>
<!-- Current State - Cloud Services -->
<g id="current-state">
<!-- Big Tech Cloud -->
<rect x="100" y="130" width="300" height="350" class="neon-red" rx="6.5" stroke-dasharray="5,5" opacity="0.5"/>
<text x="250" y="160" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" font-weight="500" class="main-text">Big Tech Cloud</text>
<!-- Microsoft 365 / Google Workspace -->
<rect x="120" y="190" width="120" height="60" class="neon-red" rx="6.5"/>
<text x="180" y="225" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" class="main-text">M365/Google</text>
<!-- Individual Services -->
<rect x="260" y="190" width="120" height="60" class="neon-orange" rx="6.5"/>
<text x="320" y="220" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">OneDrive/</text>
<text x="320" y="238" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">Google Drive</text>
<rect x="120" y="270" width="120" height="60" class="neon-purple" rx="6.5"/>
<text x="180" y="300" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">Outlook/</text>
<text x="180" y="318" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">Gmail</text>
<rect x="260" y="270" width="120" height="60" class="neon-blue" rx="6.5"/>
<text x="320" y="300" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">Teams/</text>
<text x="320" y="318" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">Meet</text>
<rect x="120" y="350" width="120" height="60" class="neon-cyan" rx="6.5"/>
<text x="180" y="380" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">SharePoint/</text>
<text x="180" y="398" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">Sites</text>
<rect x="260" y="350" width="120" height="60" class="neon-green" rx="6.5"/>
<text x="320" y="380" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">Copilot/</text>
<text x="320" y="398" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">Gemini</text>
<!-- Issues -->
<text x="250" y="440" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" class="secondary-text">• Vendor Lock-in</text>
<text x="250" y="460" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" class="secondary-text">• Monthly Costs</text>
</g>
<!-- Migration Process -->
<g id="migration">
<!-- Migration Box -->
<rect x="500" y="130" width="400" height="350" rx="6.5" fill="none" stroke="url(#migrationGradient)" stroke-width="3" opacity="0.8"/>
<text x="700" y="160" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" font-weight="500" class="main-text">Migration Tools</text>
<!-- Tools -->
<rect x="520" y="190" width="160" height="50" class="neon-orange" rx="6.5"/>
<text x="600" y="220" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">rclone</text>
<rect x="720" y="190" width="160" height="50" class="neon-purple" rx="6.5"/>
<text x="800" y="220" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">imapsync</text>
<rect x="520" y="260" width="160" height="50" class="neon-blue" rx="6.5"/>
<text x="600" y="290" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">BASIC Scripts</text>
<rect x="720" y="260" width="160" height="50" class="neon-cyan" rx="6.5"/>
<text x="800" y="290" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">API Migration</text>
<rect x="520" y="330" width="160" height="50" class="neon-green" rx="6.5"/>
<text x="600" y="360" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">KB Converter</text>
<rect x="720" y="330" width="160" height="50" class="neon-red" rx="6.5"/>
<text x="800" y="360" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">User Import</text>
<!-- Steps -->
<text x="700" y="410" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" class="secondary-text">1. Export Data</text>
<text x="700" y="430" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" class="secondary-text">2. Transform Format</text>
<text x="700" y="450" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" class="secondary-text">3. Import to GB</text>
<text x="700" y="470" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" class="secondary-text">4. Validate</text>
</g>
<!-- Target State - General Bots -->
<g id="target-state">
<!-- Self-Hosted -->
<rect x="1000" y="130" width="300" height="350" class="neon-green" rx="6.5" stroke-dasharray="5,5" opacity="0.5"/>
<text x="1150" y="160" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" font-weight="500" class="main-text">Self-Hosted Stack</text>
<!-- General Bots Core -->
<rect x="1020" y="190" width="260" height="60" class="neon-green" rx="6.5"/>
<text x="1150" y="225" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" class="main-text">General Bots Core</text>
<!-- Components -->
<rect x="1020" y="270" width="120" height="50" class="neon-orange" rx="6.5"/>
<text x="1080" y="300" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">MinIO</text>
<rect x="1160" y="270" width="120" height="50" class="neon-purple" rx="6.5"/>
<text x="1220" y="300" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">Stalwart</text>
<rect x="1020" y="330" width="120" height="50" class="neon-blue" rx="6.5"/>
<text x="1080" y="360" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">LiveKit</text>
<rect x="1160" y="330" width="120" height="50" class="neon-cyan" rx="6.5"/>
<text x="1220" y="360" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">Qdrant</text>
<rect x="1020" y="390" width="120" height="50" class="neon-red" rx="6.5"/>
<text x="1080" y="420" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">Local LLM</text>
<rect x="1160" y="390" width="120" height="50" class="neon-green" rx="6.5"/>
<text x="1220" y="420" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="main-text">Zitadel</text>
<!-- Benefits -->
<text x="1150" y="460" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" class="secondary-text">✓ Full Control</text>
<text x="1150" y="480" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" class="secondary-text">✓ No Vendor Lock-in</text>
</g>
<!-- Arrows -->
<g id="arrows" stroke-width="3">
<!-- From Cloud to Migration -->
<line x1="400" y1="305" x2="500" y2="305" class="arrow-line" marker-end="url(#arrowhead)" opacity="0.7"/>
<!-- From Migration to Self-Hosted -->
<line x1="900" y1="305" x2="1000" y2="305" class="arrow-line" marker-end="url(#arrowhead)" opacity="0.7"/>
</g>
<!-- Cost Comparison -->
<g id="cost-comparison">
<rect x="100" y="520" width="1200" height="120" rx="10" fill="none" stroke="var(--secondary-text-color)" stroke-width="1" opacity="0.3"/>
<text x="700" y="550" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="500" class="main-text">Cost Comparison</text>
<!-- Cloud Costs -->
<text x="250" y="580" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="secondary-text">Enterprise Cloud</text>
<text x="250" y="605" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" font-weight="600" class="main-text">$50-200/user/month</text>
<text x="250" y="625" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" class="secondary-text">Forever</text>
<!-- Migration -->
<text x="700" y="580" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="secondary-text">Migration Cost</text>
<text x="700" y="605" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" font-weight="600" class="main-text">One-time effort</text>
<text x="700" y="625" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" class="secondary-text">1-4 weeks</text>
<!-- Self-Hosted -->
<text x="1150" y="580" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="secondary-text">Self-Hosted</text>
<text x="1150" y="605" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" font-weight="600" class="main-text">Infrastructure only</text>
<text x="1150" y="625" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" class="secondary-text">~$500/month total</text>
</g>
<!-- Timeline -->
<g id="timeline">
<text x="700" y="680" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="500" class="main-text">Typical Migration Timeline</text>
<!-- Timeline bar -->
<rect x="200" y="710" width="1000" height="10" rx="5" fill="url(#migrationGradient)" opacity="0.5"/>
<!-- Milestones -->
<circle cx="200" cy="715" r="8" class="neon-red"/>
<text x="200" y="745" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" class="secondary-text">Start</text>
<text x="200" y="765" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" class="secondary-text">Assessment</text>
<circle cx="450" cy="715" r="8" class="neon-orange"/>
<text x="450" y="745" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" class="secondary-text">Week 1</text>
<text x="450" y="765" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" class="secondary-text">Infrastructure</text>
<circle cx="700" cy="715" r="8" class="neon-purple"/>
<text x="700" y="745" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" class="secondary-text">Week 2</text>
<text x="700" y="765" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" class="secondary-text">Data Migration</text>
<circle cx="950" cy="715" r="8" class="neon-blue"/>
<text x="950" y="745" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" class="secondary-text">Week 3</text>
<text x="950" y="765" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" class="secondary-text">Testing</text>
<circle cx="1200" cy="715" r="8" class="neon-green"/>
<text x="1200" y="745" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" class="secondary-text">Week 4</text>
<text x="1200" y="765" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" class="secondary-text">Go Live</text>
</g>
<!-- Footer -->
<text x="700" y="850" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="secondary-text">
Transform from mega-prompt dependency to true component architecture
</text>
<text x="700" y="875" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" class="secondary-text">
Your data, your infrastructure, your control
</text>
<!-- JavaScript to handle theme switching from parent document -->
<script type="text/javascript">
<![CDATA[
// Function to update CSS variables based on parent theme
function updateTheme() {
try {
// Check if we're in an iframe/object context
const parentDoc = window.parent?.document || window.top?.document;
if (!parentDoc) return;
const rootElement = document.documentElement;
const htmlElement = parentDoc.documentElement;
const bodyElement = parentDoc.body;
// Check for various theme indicators
const isRust = htmlElement.classList.contains('rust') || bodyElement.classList.contains('rust');
const isLight = htmlElement.classList.contains('light') || bodyElement.classList.contains('light');
const isDark = htmlElement.classList.contains('dark') ||
htmlElement.classList.contains('ayu') ||
htmlElement.classList.contains('navy') ||
htmlElement.classList.contains('coal') ||
bodyElement.classList.contains('theme--dark');
// Apply theme-specific CSS variables
if (isRust || isLight) {
// Force black text for Rust/Light themes
rootElement.style.setProperty('--main-text-color', '#1a1a1a');
rootElement.style.setProperty('--secondary-text-color', '#666');
rootElement.style.setProperty('--arrow-color', '#666');
} else if (isDark) {
// White text for dark themes
rootElement.style.setProperty('--main-text-color', '#ffffff');
rootElement.style.setProperty('--secondary-text-color', '#b0b0b0');
rootElement.style.setProperty('--arrow-color', '#b0b0b0');
}
} catch (e) {
// Silent fail if we can't access parent document (cross-origin)
}
}
// Update theme on load
updateTheme();
// Listen for theme changes if possible
try {
if (window.parent && window.parent !== window) {
// Try to observe parent document changes
const observer = new MutationObserver(updateTheme);
observer.observe(window.parent.document.documentElement, {
attributes: true,
attributeFilter: ['class']
});
observer.observe(window.parent.document.body, {
attributes: true,
attributeFilter: ['class']
});
}
} catch (e) {
// Silent fail if cross-origin
}
]]>
</script>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 18 KiB

146
docs/src/assets/technical-specs.svg Normal file
View file

@ -0,0 +1,146 @@
<svg viewBox="0 0 900 450" xmlns="http://www.w3.org/2000/svg" style="background: transparent;">
<style>
/* Ensure transparent background */
svg {
background: transparent !important;
}
/* CSS Custom Properties for theme switching */
:root {
/* Light theme defaults */
--main-text-color: #1a1a1a;
--secondary-text-color: #666;
--border-color: #666;
}
/* Dark theme override */
@media (prefers-color-scheme: dark) {
:root {
--main-text-color: #ffffff;
--secondary-text-color: #b0b0b0;
--border-color: #b0b0b0;
}
}
.main-text { fill: var(--main-text-color); }
.secondary-text { fill: var(--secondary-text-color); }
.border-stroke { stroke: var(--border-color); }
</style>
<!-- Title -->
<text x="450" y="25" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" class="main-text">System Technical Specifications</text>
<!-- Main container -->
<rect x="50" y="50" width="800" height="380" fill="none" class="border-stroke" stroke-width="2" rx="5"/>
<!-- Embedding Section -->
<g transform="translate(70, 80)">
<rect x="0" y="0" width="350" height="150" fill="none" class="border-stroke" stroke-width="1" stroke-dasharray="3,2" opacity="0.8"/>
<text x="175" y="20" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" class="main-text">Embedding Configuration</text>
<text x="10" y="45" font-family="Arial, sans-serif" font-size="11" class="main-text">Model: bge-small-en-v1.5-f32.gguf</text>
<text x="10" y="65" font-family="Arial, sans-serif" font-size="11" class="secondary-text">• Dimensions: 384</text>
<text x="10" y="85" font-family="Arial, sans-serif" font-size="11" class="secondary-text">• Format: GGUF (quantized)</text>
<text x="10" y="105" font-family="Arial, sans-serif" font-size="11" class="secondary-text">• Server: localhost:8082</text>
<text x="10" y="125" font-family="Arial, sans-serif" font-size="11" class="secondary-text">• Memory: ~200MB loaded</text>
</g>
<!-- LLM Section -->
<g transform="translate(450, 80)">
<rect x="0" y="0" width="350" height="150" fill="none" class="border-stroke" stroke-width="1" stroke-dasharray="3,2" opacity="0.8"/>
<text x="175" y="20" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" class="main-text">LLM Configuration</text>
<text x="10" y="45" font-family="Arial, sans-serif" font-size="11" class="main-text">Model: DeepSeek-R1-Distill-Qwen-1.5B</text>
<text x="10" y="65" font-family="Arial, sans-serif" font-size="11" class="secondary-text">• Context Size: 4096 tokens</text>
<text x="10" y="85" font-family="Arial, sans-serif" font-size="11" class="secondary-text">• Max Predict: 1024 tokens</text>
<text x="10" y="105" font-family="Arial, sans-serif" font-size="11" class="secondary-text">• Parallel Requests: 6</text>
<text x="10" y="125" font-family="Arial, sans-serif" font-size="11" class="secondary-text">• Quantization: Q3_K_M</text>
</g>
<!-- Performance Section -->
<g transform="translate(70, 250)">
<rect x="0" y="0" width="730" height="150" fill="none" class="border-stroke" stroke-width="1" stroke-dasharray="3,2" opacity="0.8"/>
<text x="365" y="20" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" class="main-text">Performance Characteristics</text>
<!-- Left column -->
<text x="10" y="45" font-family="Arial, sans-serif" font-size="11" class="main-text">Vector Index: HNSW Algorithm</text>
<text x="10" y="65" font-family="Arial, sans-serif" font-size="11" class="secondary-text">• M=16, ef_construction=200</text>
<text x="10" y="85" font-family="Arial, sans-serif" font-size="11" class="secondary-text">• Distance: Cosine Similarity</text>
<text x="10" y="105" font-family="Arial, sans-serif" font-size="11" class="secondary-text">• Build: ~1000 docs/minute</text>
<!-- Middle column -->
<text x="250" y="45" font-family="Arial, sans-serif" font-size="11" class="main-text">Chunking Strategy</text>
<text x="250" y="65" font-family="Arial, sans-serif" font-size="11" class="secondary-text">• Chunk Size: 512 tokens</text>
<text x="250" y="85" font-family="Arial, sans-serif" font-size="11" class="secondary-text">• Overlap: 50 tokens</text>
<text x="250" y="105" font-family="Arial, sans-serif" font-size="11" class="secondary-text">• Prompt Compact: Level 4</text>
<!-- Right column -->
<text x="490" y="45" font-family="Arial, sans-serif" font-size="11" class="main-text">Runtime Metrics</text>
<text x="490" y="65" font-family="Arial, sans-serif" font-size="11" class="secondary-text">• Query Latency: &lt;50ms p99</text>
<text x="490" y="85" font-family="Arial, sans-serif" font-size="11" class="secondary-text">• Memory: ~1GB/million chunks</text>
<text x="490" y="105" font-family="Arial, sans-serif" font-size="11" class="secondary-text">• Cache TTL: 3600 seconds</text>
</g>
<!-- JavaScript to handle theme switching from parent document -->
<script type="text/javascript">
<![CDATA[
// Function to update CSS variables based on parent theme
function updateTheme() {
try {
// Check if we're in an iframe/object context
const parentDoc = window.parent?.document || window.top?.document;
if (!parentDoc) return;
const rootElement = document.documentElement;
const htmlElement = parentDoc.documentElement;
const bodyElement = parentDoc.body;
// Check for various theme indicators
const isRust = htmlElement.classList.contains('rust') || bodyElement.classList.contains('rust');
const isLight = htmlElement.classList.contains('light') || bodyElement.classList.contains('light');
const isDark = htmlElement.classList.contains('dark') ||
htmlElement.classList.contains('ayu') ||
htmlElement.classList.contains('navy') ||
htmlElement.classList.contains('coal') ||
bodyElement.classList.contains('theme--dark');
// Apply theme-specific CSS variables
if (isRust || isLight) {
// Force black text for Rust/Light themes
rootElement.style.setProperty('--main-text-color', '#1a1a1a');
rootElement.style.setProperty('--secondary-text-color', '#666');
rootElement.style.setProperty('--border-color', '#666');
} else if (isDark) {
// White text for dark themes
rootElement.style.setProperty('--main-text-color', '#ffffff');
rootElement.style.setProperty('--secondary-text-color', '#b0b0b0');
rootElement.style.setProperty('--border-color', '#b0b0b0');
}
} catch (e) {
// Silent fail if we can't access parent document (cross-origin)
}
}
// Update theme on load
updateTheme();
// Listen for theme changes if possible
try {
if (window.parent && window.parent !== window) {
// Try to observe parent document changes
const observer = new MutationObserver(updateTheme);
observer.observe(window.parent.document.documentElement, {
attributes: true,
attributeFilter: ['class']
});
observer.observe(window.parent.document.body, {
attributes: true,
attributeFilter: ['class']
});
}
} catch (e) {
// Silent fail if cross-origin
}
]]>
</script>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 7.5 KiB

58
docs/src/chapter-03/README.md
View file

@ -16,61 +16,9 @@ The knowledge base architecture implements a multi-stage pipeline for document p
### Technical Specifications
<img src="./assets/technical-specs.svg" alt="Technical Specifications" style="max-height: 450px; width: 100%; object-fit: contain;">
<!-- Title -->
<text x="450" y="25" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="currentColor">System Technical Specifications</text>
<!-- Main container -->
<rect x="50" y="50" width="800" height="380" fill="none" stroke="currentColor" stroke-width="2" rx="5"/>
<!-- Embedding Section -->
<g transform="translate(70, 80)">
<rect x="0" y="0" width="350" height="150" fill="none" stroke="currentColor" stroke-width="1" stroke-dasharray="3,2" opacity="0.8"/>
<text x="175" y="20" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="currentColor">Embedding Configuration</text>
<text x="10" y="45" font-family="Arial, sans-serif" font-size="11" fill="currentColor">Model: bge-small-en-v1.5-f32.gguf</text>
<text x="10" y="65" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.8">• Dimensions: 384</text>
<text x="10" y="85" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.8">• Format: GGUF (quantized)</text>
<text x="10" y="105" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.8">• Server: localhost:8082</text>
<text x="10" y="125" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.8">• Memory: ~200MB loaded</text>
</g>
<!-- LLM Section -->
<g transform="translate(450, 80)">
<rect x="0" y="0" width="350" height="150" fill="none" stroke="currentColor" stroke-width="1" stroke-dasharray="3,2" opacity="0.8"/>
<text x="175" y="20" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="currentColor">LLM Configuration</text>
<text x="10" y="45" font-family="Arial, sans-serif" font-size="11" fill="currentColor">Model: DeepSeek-R1-Distill-Qwen-1.5B</text>
<text x="10" y="65" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.8">• Context Size: 4096 tokens</text>
<text x="10" y="85" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.8">• Max Predict: 1024 tokens</text>
<text x="10" y="105" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.8">• Parallel Requests: 6</text>
<text x="10" y="125" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.8">• Quantization: Q3_K_M</text>
</g>
<!-- Performance Section -->
<g transform="translate(70, 250)">
<rect x="0" y="0" width="730" height="150" fill="none" stroke="currentColor" stroke-width="1" stroke-dasharray="3,2" opacity="0.8"/>
<text x="365" y="20" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="currentColor">Performance Characteristics</text>
<!-- Left column -->
<text x="10" y="45" font-family="Arial, sans-serif" font-size="11" fill="currentColor">Vector Index: HNSW Algorithm</text>
<text x="10" y="65" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.8">• M=16, ef_construction=200</text>
<text x="10" y="85" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.8">• Distance: Cosine Similarity</text>
<text x="10" y="105" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.8">• Build: ~1000 docs/minute</text>
<!-- Middle column -->
<text x="250" y="45" font-family="Arial, sans-serif" font-size="11" fill="currentColor">Chunking Strategy</text>
<text x="250" y="65" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.8">• Chunk Size: 512 tokens</text>
<text x="250" y="85" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.8">• Overlap: 50 tokens</text>
<text x="250" y="105" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.8">• Prompt Compact: Level 4</text>
<!-- Right column -->
<text x="490" y="45" font-family="Arial, sans-serif" font-size="11" fill="currentColor">Runtime Metrics</text>
<text x="490" y="65" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.8">• Query Latency: &lt;50ms p99</text>
<text x="490" y="85" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.8">• Memory: ~1GB/million chunks</text>
<text x="490" y="105" font-family="Arial, sans-serif" font-size="11" fill="currentColor" opacity="0.8">• Cache TTL: 3600 seconds</text>
</g>
</svg>
<object data="../assets/technical-specs.svg" type="image/svg+xml" style="max-height: 450px; width: 100%; display: block; background: transparent;">
<img src="../assets/technical-specs.svg" alt="Technical Specifications" style="max-height: 450px; width: 100%; object-fit: contain; background: transparent;">
</object>
## Document Processing Pipeline

164
docs/src/chapter-14-migration/README.md Normal file
View file

@ -0,0 +1,164 @@
# Chapter 14: Migration Concepts
This chapter explores the conceptual framework for migrating from cloud-based enterprise services to self-hosted alternatives. We examine the philosophical and architectural differences between centralized cloud platforms and distributed, component-based systems.
## Understanding Migration Paradigms
### The Centralization Model
Modern enterprise platforms operate on a centralization principle where all services flow through a single vendor's ecosystem. This creates:
- **Unified Control Points**: Single authentication, single data store, single processing pipeline
- **Vendor-Managed Complexity**: The provider handles all infrastructure decisions
- **Abstraction Layers**: Users interact with simplified interfaces hiding underlying complexity
- **Subscription Economics**: Ongoing revenue model with usage-based scaling
### The Decentralization Alternative
Self-hosted solutions represent a return to distributed computing principles:
- **Service Isolation**: Each function operates as an independent component
- **Explicit Architecture**: Clear understanding of data flow and processing
- **Ownership Model**: Complete control over infrastructure and data
- **Capital Investment**: One-time deployment with predictable operational costs
## Migration Philosophy
### Data Sovereignty
The fundamental question in any migration is data ownership. Cloud services create a custodial relationship where:
- Data physically resides on vendor infrastructure
- Processing occurs in vendor-controlled environments
- Access depends on continued vendor relationship
- Portability requires vendor cooperation
Self-hosting inverts this relationship, establishing true ownership through physical and logical control.
### Component Architecture vs Monolithic Services
Enterprise clouds present as unified platforms but internally consist of hundreds of microservices. The difference lies in exposure:
- **Cloud Platforms**: Hide complexity behind unified APIs
- **Component Systems**: Expose individual services as installable modules
- **Integration Points**: Cloud uses proprietary protocols; components use standards
### The Automation Spectrum
Cloud platforms offer automation through:
- AI-driven suggestions
- Pre-built workflows
- Natural language interfaces
- Black-box processing
Component systems provide automation via:
- Scriptable interfaces
- Transparent logic flows
- Deterministic behaviors
- Auditable processes
## Conceptual Migration Framework
### Assessment Phase
Understanding current usage patterns involves:
- **Service Inventory**: What cloud features are actually used
- **Data Classification**: Types and volumes of information
- **Workflow Analysis**: How services interconnect
- **Dependency Mapping**: Critical integration points
### Architecture Translation
Converting cloud services to components requires:
- **Service Decomposition**: Breaking monolithic features into discrete functions
- **Protocol Mapping**: Translating proprietary APIs to standard protocols
- **State Management**: Handling distributed data consistency
- **Security Boundaries**: Redefining trust zones
### Knowledge Transformation
Enterprise search and AI features translate to:
- **Vector Databases**: Semantic search replacing keyword matching
- **Local Language Models**: On-premise AI instead of cloud APIs
- **Structured Knowledge**: Explicit schemas rather than implicit understanding
- **Retrieval Systems**: Direct access patterns vs mediated queries
## Migration Patterns
### Lift and Shift
The simplest migration moves data without transformation:
- Direct file copying
- Database exports and imports
- Configuration replication
- Minimal service disruption
### Progressive Migration
Gradual transition maintains dual operations:
- Parallel running of old and new systems
- Phased user migration
- Incremental data synchronization
- Rollback capabilities
### Transformation Migration
Reimagining workflows for new architecture:
- Process redesign for component model
- Workflow optimization
- Legacy feature elimination
- New capability introduction
## Post-Migration Considerations
### Operational Changes
Self-hosting shifts responsibilities:
- **Maintenance**: From vendor to organization
- **Updates**: From automatic to managed
- **Scaling**: From elastic to planned
- **Support**: From vendor to internal/community
### Cost Models
Financial implications include:
- **Capital vs Operating**: Hardware investment vs subscription fees
- **Expertise Requirements**: Internal capabilities vs vendor services
- **Risk Distribution**: Concentrated vs distributed failure points
- **Innovation Pace**: Vendor-driven vs self-determined
### Compliance and Governance
Regulatory considerations:
- **Data Residency**: Guaranteed geographic location
- **Audit Trails**: Complete system visibility
- **Access Controls**: Granular permission management
- **Retention Policies**: Direct enforcement capability
## Success Metrics
### Technical Indicators
- Service availability and reliability
- Performance benchmarks
- Integration completeness
- Feature parity achievement
### Business Indicators
- Cost reduction targets
- Productivity maintenance
- User satisfaction scores
- Risk mitigation effectiveness
## Conclusion
Migration from cloud to self-hosted systems represents more than technical change—it's a philosophical shift in how organizations relate to their digital infrastructure. Success requires understanding not just the technical mechanisms but the underlying principles that differentiate centralized cloud services from distributed component architectures.
The journey from managed services to self-sovereignty demands careful planning, clear understanding of trade-offs, and commitment to operational excellence. While challenging, it offers organizations complete control over their digital destiny.

58
docs/src/chapter-14-migration/automation.md Normal file
View file

@ -0,0 +1,58 @@
# Automation Scripts
High-level approaches to automate migration from cloud services to self-hosted infrastructure.
## Overview
Migration automation focuses on using existing tools and scripts to move data from cloud providers to your self-hosted stack.
## Common Tools
### File Transfer
- **rclone**: Universal cloud storage migration tool
- **rsync**: Traditional file synchronization
- **wget/curl**: API-based downloads
### Email Migration
- **imapsync**: IMAP to IMAP migration
- **offlineimap**: Email backup and sync
- **getmail**: POP3/IMAP retrieval
### Directory Services
- **ldapsearch/ldapadd**: LDAP export/import
- **csvde**: Active Directory CSV export
- **PowerShell**: AD automation scripts
## Migration Approach
### 1. Assessment
- List what needs migration
- Estimate data volumes
- Identify dependencies
### 2. Tool Selection
- Match tools to data types
- Consider API availability
- Evaluate bandwidth needs
### 3. Execution
- Start with test data
- Run in batches
- Monitor progress
### 4. Validation
- Compare source and destination
- Check data integrity
- Test functionality
## General Principles
- Start small, scale up
- Keep source data intact
- Document the process
- Have a rollback plan
## Next Steps
- [Common Concepts](./common-concepts.md) - Shared migration patterns
- [Validation](./validation.md) - Testing migrated systems

81
docs/src/chapter-14-migration/common-concepts.md Normal file
View file

@ -0,0 +1,81 @@
# Common Migration Concepts
Core concepts for migrating from cloud services to self-hosted infrastructure.
## The Fundamental Shift
### From Cloud Services
- Data on vendor servers
- Monthly subscription costs
- Limited control over updates
- Vendor-specific APIs
### To Self-Hosted
- Data on your infrastructure
- One-time setup costs
- Full control over versions
- Standard protocols
## Component Mapping
| Cloud Service | Self-Hosted Alternative | Protocol |
|---------------|------------------------|----------|
| Cloud Storage | MinIO | S3 API |
| Email Service | Various mail servers | SMTP/IMAP |
| Identity Provider | Various auth servers | OIDC/SAML |
## Migration Stages
1. **Assessment** - What do you have?
2. **Planning** - How will you move it?
3. **Testing** - Does it work?
4. **Execution** - Do the migration
5. **Validation** - Verify everything works
## Common Challenges
### Data Volume
- Large datasets take time
- Bandwidth limitations
- Storage requirements
### Authentication
- Passwords can't be exported
- Need password reset strategy
- Federation options
### Dependencies
- Integrated services
- API changes
- Custom workflows
## Tools Categories
### File Migration
- Cloud storage sync tools
- API-based transfers
- Bulk download utilities
### Email Migration
- IMAP synchronization tools
- Export/import utilities
- Archive formats
### User Migration
- Directory export tools
- CSV/LDIF formats
- API-based extraction
## Risk Mitigation
- Always backup first
- Test with small datasets
- Keep source data intact
- Document everything
- Have rollback plan
## Next Steps
- [Microsoft 365 Migration](./microsoft-365.md) - M365 specific guidance
- [Google Workspace Migration](./google-workspace.md) - Google specific guidance
- [Knowledge Base Migration](./kb-migration.md) - Document migration

204
docs/src/chapter-14-migration/google-workspace.md Normal file
View file

@ -0,0 +1,204 @@
# Google Workspace Migration Guide
Migrating from Google Workspace to self-hosted infrastructure.
## Overview
Google Workspace (formerly G Suite) provides integrated cloud services that need to be migrated to various self-hosted alternatives.
## Service Mapping
| Google Workspace Service | Self-Hosted Alternative | Migration Tool |
|-------------------------|------------------------|----------------|
| Gmail | Mail server (Stalwart, etc.) | imapsync, Got Your Back |
| Google Drive | MinIO or Nextcloud | rclone |
| Google Docs/Sheets/Slides | LibreOffice, OnlyOffice | Export to Office formats |
| Google Calendar | CalDAV server | ical export/import |
| Google Meet | Jitsi, LiveKit | No migration (ephemeral) |
| Google Chat | General Bots | API export |
## Migration Steps
### 1. Email Migration (Gmail)
**Prerequisites:**
- IMAP enabled in Google Admin
- App-specific passwords or OAuth
- Target mail server ready
**Process:**
- Use imapsync or Got Your Back (GYB)
- Migrate labels as folders
- Preserve read/unread status
**Considerations:**
- Gmail labels don't map perfectly to folders
- Some users may have 15+ years of email
- Attachments can consume significant space
### 2. File Migration (Google Drive)
**Prerequisites:**
- Google Drive API access
- Service account or OAuth credentials
- Storage capacity planning
**Process:**
- Use rclone with Google Drive backend
- Export Google Docs to portable formats
- Maintain folder structure
**Considerations:**
- Google Docs need format conversion
- Shared drives require separate handling
- Comments and suggestions are lost
### 3. User Migration (Google Directory)
**Prerequisites:**
- Google Admin SDK access
- Target identity provider configured
**Process:**
- Export via Admin SDK or GAM tool
- Transform to target format
- Import to new system
**Considerations:**
- No password export possible
- 2FA needs reconfiguration
- Groups and OUs need mapping
## Google-Specific Challenges
### Format Conversion
Google's proprietary formats require conversion:
- Google Docs → .docx or .odt
- Google Sheets → .xlsx or .ods
- Google Slides → .pptx or .odp
- Google Drawings → .svg or .png
### API Quotas
Google enforces strict quotas:
- Drive API: 1,000 queries per 100 seconds
- Gmail API: 250 quota units per user per second
- Admin SDK: Various limits per API
### Data Takeout
Google Takeout option:
- User-initiated bulk export
- Includes most Google services
- ZIP files can be huge (100GB+)
- Not suitable for organization-wide migration
## Tools and Utilities
### Google Admin Tools
- GAM (Google Apps Manager) - Command-line tool
- GAMADV-XTD - Enhanced GAM version
- Google Admin console for manual exports
### Got Your Back (GYB)
- Python-based Gmail backup tool
- Supports full mailbox export
- Can restore to different account
### rclone Configuration
- Supports team drives
- Handles Google Photos separately
- Can preserve modification times
## Common Issues
### Large Attachments
- Gmail allows 25MB attachments
- Some mail servers have lower limits
- May need to store separately
### Shared Resources
- Shared drives need owner reassignment
- Calendar sharing needs recreation
- Document collaboration links break
### Google Photos
- Not part of standard Google Drive
- Needs separate migration approach
- Original quality vs compressed
## Migration Strategy
### Phased Approach
1. Start with pilot group
2. Migrate inactive users first
3. Schedule department by department
4. Keep Google active during transition
### Hybrid Period
- MX records can split email delivery
- Users can access both systems
- Gradual cutover reduces risk
### Data Validation
- Compare file counts
- Verify email folders
- Check user access
## Post-Migration
### User Training
Key differences to document:
- No real-time collaboration like Google Docs
- Different UI/UX in alternatives
- Changed sharing workflows
### Feature Gaps
Features that may be lost:
- Smart Compose in Gmail
- Google Assistant integration
- Automatic photo organization
- Version history in Docs
### Maintaining Archive Access
Options for historical data:
- Keep reduced Google license for archive
- Export everything to static storage
- Convert to standard formats
## Cost Factors
### Google Workspace Pricing
- Business Starter: $6/user/month
- Business Standard: $12/user/month
- Business Plus: $18/user/month
- Need to maintain during migration
### Data Export Costs
- No direct egress fees
- But API quotas may extend timeline
- Consider bandwidth costs
## Timeline Estimates
Migration duration depends on:
- Number of users
- Data volume per user
- Available bandwidth
- Conversion requirements
Typical timelines:
- Small org (<50 users): 2-3 weeks
- Medium org (50-500 users): 1-3 months
- Large org (500+ users): 3-6 months
## Best Practices
1. **Inventory First**: Document what you have before starting
2. **Test Thoroughly**: Pilot with IT team first
3. **Communicate Often**: Keep users informed
4. **Plan Rollback**: Have contingency plans
5. **Archive Everything**: Keep backups of original data
## Next Steps
- [Common Concepts](./common-concepts.md) - General migration principles
- [Validation](./validation.md) - Testing procedures

78
docs/src/chapter-14-migration/kb-migration.md Normal file
View file

@ -0,0 +1,78 @@
# Knowledge Base Migration
Converting documents from cloud storage to General Bots knowledge bases.
## Overview
Knowledge base migration involves moving documents from various sources into `.gbkb` packages where they become searchable through General Bots.
## Source Systems
Common document sources:
- SharePoint document libraries
- Google Drive folders
- OneDrive/Dropbox
- Confluence spaces
- File servers
## Document Types
Supported formats:
- PDF files
- Office documents (Word, Excel, PowerPoint)
- Text files
- Markdown files
- HTML pages
## Migration Process
### 1. Export
- Download documents from source
- Preserve folder structure
- Maintain metadata where possible
### 2. Organize
- Group related documents
- Create logical collections
- Remove duplicates
### 3. Import
- Place in `.gbkb` folders
- General Bots indexes automatically
- Documents become searchable
## Considerations
### Volume
- Large document sets take time to index
- Consider staged migration
- Monitor disk space
### Quality
- Clean up outdated content first
- Remove duplicate documents
- Fix broken files
### Structure
- Maintain logical organization
- Use meaningful folder names
- Group by topic or department
## Format Conversion
Some formats may need conversion:
- Web pages → PDF or Markdown
- Databases → CSV exports
- Proprietary formats → Standard formats
## Testing
After migration:
- Verify search works
- Check document access
- Test with sample queries
## Next Steps
- [Overview](./overview.md) - Migration concepts
- [Validation](./validation.md) - Testing procedures

150
docs/src/chapter-14-migration/microsoft-365.md Normal file
View file

@ -0,0 +1,150 @@
# Microsoft 365 Migration Guide
Migrating from Microsoft 365 to self-hosted infrastructure.
## Overview
Microsoft 365 (formerly Office 365) includes multiple services that need to be migrated to different self-hosted components.
## Service Mapping
| Microsoft 365 Service | Self-Hosted Alternative | Migration Tool |
|----------------------|------------------------|----------------|
| Exchange Online | Mail server (Stalwart, etc.) | imapsync |
| OneDrive | MinIO or Nextcloud | rclone |
| SharePoint | MinIO + Wiki/CMS | rclone + export tools |
| Teams | Mattermost, General Bots, etc. | Export/Import APIs |
| Azure AD | Keycloak, Authentik, Zitadel | LDAP export |
## Migration Steps
### 1. Email Migration (Exchange Online)
**Prerequisites:**
- IMAP access enabled in Exchange Online
- Target mail server configured
- User credentials or app passwords
**Process:**
- Use imapsync for mailbox migration
- Migrate in batches to avoid throttling
- Preserve folder structure and flags
**Considerations:**
- Exchange uses proprietary features (categories, etc.) that may not transfer
- Calendar and contacts need separate migration (CalDAV/CardDAV)
- Shared mailboxes require special handling
### 2. File Migration (OneDrive/SharePoint)
**Prerequisites:**
- OneDrive sync client or API access
- Sufficient storage on target
- Network bandwidth for transfer
**Process:**
- Use rclone with OneDrive backend
- Maintain folder structure
- Preserve timestamps where possible
**Considerations:**
- SharePoint metadata won't transfer automatically
- Version history is typically lost
- Permissions need to be recreated
### 3. User Migration (Azure AD)
**Prerequisites:**
- Azure AD Connect or API access
- Target identity provider ready
**Process:**
- Export users via PowerShell or Graph API
- Transform to target format (LDIF, JSON)
- Import to new identity provider
**Considerations:**
- Passwords cannot be exported
- MFA settings need reconfiguration
- Group memberships need mapping
## Common Challenges
### API Throttling
Microsoft throttles API calls:
- Plan for slow, steady migration
- Use batch operations where possible
- Consider running migrations off-peak
### Data Volume
Large organizations may have:
- Terabytes of OneDrive/SharePoint data
- Years of email history
- Thousands of users
### Feature Parity
Some M365 features have no direct equivalent:
- Power Automate workflows
- SharePoint lists and forms
- Teams channel history
## Tools and Utilities
### PowerShell for Export
- Azure AD PowerShell module for user export
- Exchange Online PowerShell for mailbox info
- SharePoint Online PowerShell for site inventory
### Graph API
- Programmatic access to most M365 services
- Useful for custom migration scripts
- Requires app registration and permissions
### Third-Party Tools
- BitTitan MigrationWiz (commercial)
- Sharegate (commercial)
- Various open-source scripts on GitHub
## Post-Migration
### DNS Changes
- Update MX records for email
- Update autodiscover records
- Consider keeping hybrid setup temporarily
### User Communication
- Provide new login credentials
- Document changed procedures
- Offer training on new tools
### Validation
- Verify email delivery
- Test file access
- Confirm authentication works
## Cost Considerations
### Subscription Overlap
- May need to maintain M365 during migration
- Consider read-only licenses for archive access
### Data Transfer Costs
- Egress charges from Microsoft
- Bandwidth costs for large transfers
## Timeline Estimates
- Small org (<50 users): 1-2 weeks
- Medium org (50-500 users): 1-2 months
- Large org (500+ users): 2-6 months
Factors affecting timeline:
- Data volume
- Network speed
- Complexity of setup
- User training needs
## Next Steps
- [Common Concepts](./common-concepts.md) - General migration principles
- [Validation](./validation.md) - Testing procedures

166
docs/src/chapter-14-migration/overview.md Normal file
View file

@ -0,0 +1,166 @@
# Migration Overview
Understanding the fundamental shift from cloud services to self-hosted components is crucial for successful enterprise migration to General Bots.
## The Architecture Paradigm Shift
<object data="../assets/migration-architecture.svg" type="image/svg+xml" style="max-height: 600px; width: 100%; display: block; background: transparent;">
<img src="../assets/migration-architecture.svg" alt="Enterprise Migration Architecture" style="max-height: 600px; width: 100%; object-fit: contain; background: transparent;">
</object>
## Core Migration Principles
### 1. Component-Based Architecture
Unlike monolithic cloud services, General Bots uses discrete, installable components:
```bash
# Install individual components as needed
./botserver package install mail # Email service
./botserver package install drive # File storage
./botserver package install directory # User management
./botserver package install meet # Video conferencing
```
### 2. Data Sovereignty
Your data stays under your control:
- **On-premises**: Physical servers in your data center
- **Private cloud**: Your own cloud infrastructure
- **Hybrid**: Mix of local and controlled cloud resources
### 3. Standard Protocols
All components use industry-standard protocols:
- **Storage**: S3 API (MinIO)
- **Email**: SMTP/IMAP/JMAP (Stalwart)
- **Auth**: OIDC/SAML/LDAP (Zitadel)
- **Video**: WebRTC (LiveKit)
### 4. Knowledge Base Integration
Transform static documents into searchable knowledge:
```basic
' Convert SharePoint documents to searchable KB
USE KB "company_docs"
ADD WEBSITE "https://sharepoint.company.com/docs"
' Now accessible via natural language
answer = HEAR "What's our vacation policy?"
' System automatically searches KB and responds
```
## Migration Phases
### Phase 1: Assessment (Week 1-2)
- Inventory current services and usage
- Identify dependencies and integrations
- Size infrastructure requirements
- Create migration timeline
### Phase 2: Infrastructure Setup (Week 2-3)
- Deploy General Bots instance
- Install required components
- Configure authentication (Zitadel)
- Setup storage (MinIO)
### Phase 3: Data Migration (Week 3-6)
- User accounts and permissions
- Email and calendars
- Files and documents
- Knowledge base content
### Phase 4: Process Migration (Week 6-8)
- Convert workflows to .gbdialog scripts
- Setup automation rules
- Configure integrations
- Train AI models on your data
### Phase 5: Validation & Training (Week 8-10)
- Test all migrated services
- User acceptance testing
- Training sessions
- Documentation update
### Phase 6: Cutover (Week 10-12)
- Gradual user migration
- Monitor and support
- Decommission old services
- Post-migration optimization
## Cost Comparison
### Enterprise Cloud Services
```
Microsoft 365 E3: $36/user/month
Google Workspace: $12/user/month
+ API costs
+ Storage overages
+ Add-on features
= $40-60/user/month typical
```
### General Bots Self-Hosted
```
Infrastructure: ~$500/month (100 users)
Maintenance: ~$200/month
= $7/user/month
Savings: 85%+
```
## Key Differentiators
### Mega-Prompts vs Components
| Copilot/Gemini (Mega-Prompts) | General Bots (Components) |
|-------------------------------|---------------------------|
| Black box AI responses | Transparent, traceable logic |
| Cloud processing required | Local or hybrid processing |
| Fixed capabilities | Extensible via .gbdialog |
| Subscription model | One-time deployment |
| Vendor-controlled updates | You control updates |
### Data Control
| Cloud Services | General Bots |
|---------------|--------------|
| Data on vendor servers | Data on your servers |
| Vendor terms apply | Your policies only |
| Potential AI training use | No external AI training |
| Compliance uncertainty | Full compliance control |
## Success Metrics
Monitor these KPIs during and after migration:
- **Performance**: Response times, system availability
- **Adoption**: User login frequency, feature usage
- **Cost**: Total cost of ownership reduction
- **Security**: Incident reduction, audit compliance
- **Productivity**: Task completion times
## Prerequisites Checklist
Before starting migration:
- [ ] Executive sponsorship secured
- [ ] Migration team assembled
- [ ] Infrastructure provisioned
- [ ] Backup strategy defined
- [ ] Rollback plan documented
- [ ] User communication plan ready
- [ ] Training materials prepared
## Next Steps
1. Review [Common Migration Concepts](./common-concepts.md) for shared tools and patterns
2. Choose your migration path:
- [Microsoft 365 Migration](./microsoft-365.md)
- [Google Workspace Migration](./google-workspace.md)
3. Explore [Automation Scripts](./automation.md) for streamlined migration
4. Plan [Knowledge Base Migration](./kb-migration.md) for document conversion
The journey from cloud dependency to self-hosted freedom starts with understanding these core concepts. General Bots provides not just an alternative, but a fundamentally better approach to enterprise computing.

81
docs/src/chapter-14-migration/validation.md Normal file
View file

@ -0,0 +1,81 @@
# Validation
Post-migration testing and verification procedures.
## Overview
Validation ensures that migrated systems and data are functioning correctly in the new self-hosted environment.
## Key Areas to Validate
### 1. User Access
- Can users log in?
- Are permissions correct?
- Does SSO work if configured?
### 2. Data Integrity
- Are all files present?
- Do file sizes match?
- Are timestamps preserved?
### 3. Email Functionality
- Can users send/receive email?
- Are folders and messages intact?
- Do aliases work?
### 4. Document Search
- Does search return results?
- Are documents accessible?
- Is indexing complete?
## Testing Approach
### Smoke Testing
Quick tests to verify basic functionality:
- Login test
- Send test email
- Search for known document
- Access key files
### User Acceptance Testing
Have actual users verify:
- Their data is present
- Workflows still function
- Performance is acceptable
### Load Testing
If applicable:
- Concurrent user access
- Large file transfers
- Search performance
## Common Issues
### Authentication Problems
- Wrong credentials
- Certificate issues
- Domain configuration
### Missing Data
- Incomplete transfers
- Permission errors
- Format incompatibilities
### Performance Issues
- Slow searches
- Network bottlenecks
- Resource constraints
## Validation Checklist
- [ ] All users can authenticate
- [ ] Email send/receive works
- [ ] Files are accessible
- [ ] Search returns results
- [ ] Backups are working
- [ ] Monitoring is active
## Next Steps
- [Overview](./overview.md) - Return to migration overview
- [Common Concepts](./common-concepts.md) - Migration fundamentals

215
docs/src/custom.css Normal file
View file

@ -0,0 +1,215 @@
/* Custom CSS for Rust Documentation - Fixes SVG text rendering */
/* CSS Custom Properties that can be injected into SVG documents */
:root {
--svg-main-text-color: #1a1a1a;
--svg-secondary-text-color: #666;
--svg-arrow-color: #666;
}
/* Force black text in light/rust themes */
.light,
.rust {
--svg-main-text-color: #1a1a1a !important;
--svg-secondary-text-color: #666 !important;
--svg-arrow-color: #666 !important;
}
/* Dark theme overrides */
.ayu,
.coal,
.navy,
.dark,
.theme--dark {
--svg-main-text-color: #ffffff !important;
--svg-secondary-text-color: #b0b0b0 !important;
--svg-arrow-color: #b0b0b0 !important;
}
/* For inline SVGs - direct styling */
.light svg .main-text,
.rust svg .main-text {
fill: #1a1a1a !important;
}
.light svg .secondary-text,
.rust svg .secondary-text {
fill: #666 !important;
}
.light svg .arrow-head,
.rust svg .arrow-head {
fill: #666 !important;
}
.light svg .arrow-line,
.rust svg .arrow-line {
stroke: #666 !important;
}
/* Dark theme inline SVG overrides */
.ayu svg .main-text,
.coal svg .main-text,
.navy svg .main-text,
.dark svg .main-text,
.theme--dark svg .main-text {
fill: #ffffff !important;
}
.ayu svg .secondary-text,
.coal svg .secondary-text,
.navy svg .secondary-text,
.dark svg .secondary-text,
.theme--dark svg .secondary-text {
fill: #b0b0b0 !important;
}
.ayu svg .arrow-head,
.coal svg .arrow-head,
.navy svg .arrow-head,
.dark svg .arrow-head,
.theme--dark svg .arrow-head {
fill: #b0b0b0 !important;
}
.ayu svg .arrow-line,
.coal svg .arrow-line,
.navy svg .arrow-line,
.dark svg .arrow-line,
.theme--dark svg .arrow-line {
stroke: #b0b0b0 !important;
}
/* Object element styling for better SVG integration */
object[type="image/svg+xml"] {
display: block;
max-width: 100%;
height: auto;
pointer-events: none; /* Prevent interaction issues */
background: transparent !important;
}
/* Ensure object fallback images are hidden when object loads */
object[type="image/svg+xml"] img {
display: none;
}
/* Ensure SVG containers have transparent background */
.content object,
.content img[src$=".svg"] {
background: transparent !important;
}
/* Remove any background from SVG wrappers */
.content > div:has(object[type="image/svg+xml"]) {
background: transparent !important;
}
/* Fix for mdBook's content area */
.content object[type="image/svg+xml"] {
margin: 1em 0;
background-color: transparent !important;
}
/* Override any mdBook theme backgrounds for SVG areas */
.rust .content object[type="image/svg+xml"],
.light .content object[type="image/svg+xml"],
.coal .content object[type="image/svg+xml"],
.navy .content object[type="image/svg+xml"],
.ayu .content object[type="image/svg+xml"] {
background-color: transparent !important;
}
/* Inject CSS variables into object document via JavaScript */
.light object[type="image/svg+xml"],
.rust object[type="image/svg+xml"] {
color-scheme: light;
}
.ayu object[type="image/svg+xml"],
.coal object[type="image/svg+xml"],
.navy object[type="image/svg+xml"],
.dark object[type="image/svg+xml"] {
color-scheme: dark;
}
/* Additional mdBook theme detection */
body:not([class*="theme"]) svg .main-text,
body:not([class*="ayu"]):not([class*="coal"]):not([class*="navy"])
svg
.main-text {
fill: var(--svg-main-text-color, #1a1a1a) !important;
}
body:not([class*="theme"]) svg .secondary-text,
body:not([class*="ayu"]):not([class*="coal"]):not([class*="navy"])
svg
.secondary-text {
fill: var(--svg-secondary-text-color, #666) !important;
}
body:not([class*="theme"]) svg .arrow-head,
body:not([class*="ayu"]):not([class*="coal"]):not([class*="navy"])
svg
.arrow-head {
fill: var(--svg-arrow-color, #666) !important;
}
body:not([class*="theme"]) svg .arrow-line,
body:not([class*="ayu"]):not([class*="coal"]):not([class*="navy"])
svg
.arrow-line {
stroke: var(--svg-arrow-color, #666) !important;
}
/* Print styles */
@media print {
svg .main-text {
fill: #1a1a1a !important;
}
svg .secondary-text {
fill: #666 !important;
}
svg .arrow-head {
fill: #666 !important;
}
svg .arrow-line {
stroke: #666 !important;
}
}
/* Accessibility improvements */
@media (prefers-contrast: high) {
svg .main-text {
fill: #000000 !important;
}
.dark svg .main-text,
.ayu svg .main-text,
.coal svg .main-text,
.navy svg .main-text {
fill: #ffffff !important;
}
}
/* Custom scrollbar for SVG containers if needed */
object[type="image/svg+xml"]::-webkit-scrollbar {
width: 8px;
height: 8px;
}
object[type="image/svg+xml"]::-webkit-scrollbar-track {
background: transparent;
}
object[type="image/svg+xml"]::-webkit-scrollbar-thumb {
background: rgba(0, 0, 0, 0.2);
border-radius: 4px;
}
.dark object[type="image/svg+xml"]::-webkit-scrollbar-thumb {
background: rgba(255, 255, 255, 0.2);
}

115
docs/src/theme-sync.js Normal file
View file

@ -0,0 +1,115 @@
// Theme synchronization for SVG documents in object elements
(function() {
'use strict';
// Function to update SVG theme
function updateSVGTheme(objectElement) {
try {
const svgDoc = objectElement.contentDocument;
if (!svgDoc) return;
const html = document.documentElement;
const body = document.body;
const svgRoot = svgDoc.documentElement;
// Detect current theme
const isRust = html.classList.contains('rust') || body.classList.contains('rust');
const isLight = html.classList.contains('light') || body.classList.contains('light');
const isDark = html.classList.contains('dark') ||
html.classList.contains('ayu') ||
html.classList.contains('navy') ||
html.classList.contains('coal') ||
body.classList.contains('theme--dark');
// Set CSS variables in SVG
if (isRust || isLight) {
svgRoot.style.setProperty('--main-text-color', '#1a1a1a');
svgRoot.style.setProperty('--secondary-text-color', '#666');
svgRoot.style.setProperty('--arrow-color', '#666');
} else if (isDark) {
svgRoot.style.setProperty('--main-text-color', '#ffffff');
svgRoot.style.setProperty('--secondary-text-color', '#b0b0b0');
svgRoot.style.setProperty('--arrow-color', '#b0b0b0');
}
// Also try to call the SVG's internal updateTheme function if it exists
if (svgDoc.defaultView && typeof svgDoc.defaultView.updateTheme === 'function') {
svgDoc.defaultView.updateTheme();
}
} catch (e) {
// Silent fail for cross-origin or other errors
console.debug('Could not update SVG theme:', e);
}
}
// Function to initialize all SVG objects
function initializeSVGThemes() {
const objects = document.querySelectorAll('object[type="image/svg+xml"]');
objects.forEach(obj => {
// Wait for object to load
if (obj.contentDocument) {
updateSVGTheme(obj);
} else {
obj.addEventListener('load', () => updateSVGTheme(obj));
}
});
}
// Watch for theme changes
function watchThemeChanges() {
const observer = new MutationObserver((mutations) => {
// Check if class attribute changed
const classChanged = mutations.some(m =>
m.type === 'attributes' && m.attributeName === 'class'
);
if (classChanged) {
initializeSVGThemes();
}
});
// Observe both html and body elements
observer.observe(document.documentElement, {
attributes: true,
attributeFilter: ['class']
});
observer.observe(document.body, {
attributes: true,
attributeFilter: ['class']
});
}
// Initialize on DOM ready
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', () => {
initializeSVGThemes();
watchThemeChanges();
});
} else {
initializeSVGThemes();
watchThemeChanges();
}
// Re-initialize on mdBook theme change (mdBook specific)
if (window.playground_text) {
// mdBook is present
const themeToggle = document.getElementById('theme-toggle');
if (themeToggle) {
themeToggle.addEventListener('click', () => {
setTimeout(initializeSVGThemes, 100);
});
}
// Also watch for theme picker changes
const themeChoices = document.querySelectorAll('#theme-list button');
themeChoices.forEach(btn => {
btn.addEventListener('click', () => {
setTimeout(initializeSVGThemes, 100);
});
});
}
// Expose function globally for manual updates
window.updateAllSVGThemes = initializeSVGThemes;
})();