index.html

<!doctype html>
<html lang="en" data-theme="dark">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>BoloDB Documentation — Ask Your Database in Plain English</title>
  <meta name="description" content="Complete documentation for BoloDB — a multi-tenant text-to-SQL product that lets non-technical users ask questions in plain English and get trusted answers from any SQL database." />
  <meta name="keywords" content="BoloDB, text-to-SQL, natural language database, AI database query, plain English SQL, OpenRouter, DeepSeek, PostgreSQL, MySQL, SQLite, Oracle, Snowflake, BigQuery" />
  <meta name="robots" content="index, follow" />
  <meta name="author" content="BoloDB" />
  <link rel="canonical" href="https://docs.bolodb.dev/" />

  <!-- Open Graph -->
  <meta property="og:type" content="website" />
  <meta property="og:url" content="https://docs.bolodb.dev/" />
  <meta property="og:title" content="BoloDB Documentation — Ask Your Database in Plain English" />
  <meta property="og:description" content="Complete documentation for BoloDB — text-to-SQL for non-technical users. Connect any database, ask questions, get trusted answers with charts and confidence levels." />
  <meta property="og:image" content="https://docs.bolodb.dev/logo.jpg" />
  <meta property="og:site_name" content="BoloDB Docs" />

  <!-- Twitter Card -->
  <meta name="twitter:card" content="summary_large_image" />
  <meta name="twitter:title" content="BoloDB Documentation" />
  <meta name="twitter:description" content="Complete documentation for BoloDB — text-to-SQL for non-technical users. Multi-tenant, RBAC, charts, and semantic layer." />
  <meta name="twitter:image" content="https://docs.bolodb.dev/logo.jpg" />

  <!-- Structured Data -->
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "WebSite",
    "name": "BoloDB Documentation",
    "url": "https://docs.bolodb.dev",
    "description": "Complete documentation for BoloDB — a multi-tenant text-to-SQL product powered by DeepSeek via OpenRouter.",
    "publisher": {
      "@type": "Organization",
      "name": "BoloDB",
      "url": "https://github.com/BoloDB"
    },
    "potentialAction": {
      "@type": "SearchAction",
      "target": "https://docs.bolodb.dev/?q={search_term_string}",
      "query-input": "required name=search_term_string"
    }
  }
  </script>
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "TechArticle",
    "name": "BoloDB Documentation",
    "url": "https://docs.bolodb.dev",
    "description": "Documentation for BoloDB, a text-to-SQL product for non-technical users.",
    "applicationCategory": "DeveloperApplication",
    "operatingSystem": "Cross-platform",
    "offers": {
      "@type": "Offer",
      "price": "0",
      "priceCurrency": "USD"
    }
  }
  </script>

  <link rel="preconnect" href="https://fonts.googleapis.com" />
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
  <link href="https://fonts.googleapis.com/css2?family=Hanken+Grotesk:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet" />
  <link rel="stylesheet" href="css/style.css" />
  <style>
    .landing-hero {
      text-align: center;
      padding: 100px 24px 60px;
      position: relative;
      overflow: hidden;
    }
    .landing-hero::before {
      content: '';
      position: absolute;
      top: -200px;
      left: 50%;
      transform: translateX(-50%);
      width: 800px;
      height: 600px;
      background: radial-gradient(ellipse, rgba(77,166,255,0.1) 0%, transparent 70%);
      pointer-events: none;
    }
    .landing-hero h1 {
      font-size: 3.5rem;
      font-weight: 800;
      letter-spacing: -0.03em;
      margin: 0 0 20px;
      line-height: 1.1;
      position: relative;
    }
    .landing-hero h1 .gradient {
      background: linear-gradient(135deg, var(--accent), var(--emerald));
      -webkit-background-clip: text;
      -webkit-text-fill-color: transparent;
      background-clip: text;
    }
    .landing-sub {
      font-size: 1.2rem;
      color: var(--text-secondary);
      max-width: 600px;
      margin: 0 auto 40px;
      line-height: 1.7;
      position: relative;
    }
    .landing-actions {
      display: flex;
      gap: 14px;
      justify-content: center;
      flex-wrap: wrap;
      position: relative;
    }
    .landing-chapters {
      max-width: 960px;
      margin: 0 auto;
      padding: 0 24px 80px;
    }
    .landing-chapters h2 {
      text-align: center;
      font-size: 1.8rem;
      margin: 60px 0 32px;
    }
    .chapter-grid {
      display: grid;
      grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
      gap: 16px;
    }
    .chapter-card {
      display: flex;
      flex-direction: column;
      gap: 10px;
      padding: 24px;
      background: var(--bg-card);
      border: 1px solid var(--border);
      border-radius: 12px;
      text-decoration: none;
      transition: border-color 0.2s, transform 0.2s;
    }
    .chapter-card:hover {
      border-color: var(--accent);
      transform: translateY(-2px);
    }
    .chapter-num {
      font-size: 0.75rem;
      font-weight: 700;
      color: var(--accent);
      text-transform: uppercase;
      letter-spacing: 0.08em;
    }
    .chapter-card h3 {
      font-size: 1.05rem;
      font-weight: 700;
      color: var(--text-primary);
      margin: 0;
    }
    .chapter-card p {
      font-size: 0.875rem;
      color: var(--text-muted);
      margin: 0;
      line-height: 1.5;
    }
    .arch-preview {
      max-width: 960px;
      margin: 0 auto;
      padding: 0 24px 80px;
    }
    .arch-preview h2 {
      text-align: center;
      font-size: 1.8rem;
      margin: 0 0 32px;
    }
  </style>
</head>
<body>
  <header class="header">
    <div class="header-inner">
      <div style="display:flex;align-items:center;gap:16px">
        <a class="logo" href="index.html">
          <svg width="32" height="32" viewBox="0 0 32 32" fill="none">
            <path d="M6.5 5.5Q6.5 3.5 8.5 3.5L23.5 3.5Q25.5 3.5 25.5 5.5L25.5 17.5Q25.5 19.5 23.5 19.5L14.5 19.5L11 22.5L11.5 19.5L8.5 19.5Q6.5 19.5 6.5 17.5Z" stroke="#4da6ff" stroke-width="1.8" fill="none"/>
            <ellipse cx="16" cy="8.5" rx="4.5" ry="1.6" stroke="#4da6ff" stroke-width="1.8" fill="none"/>
            <path d="M11.5 8.5L11.5 14Q11.5 15.5 16 15.5Q20.5 15.5 20.5 14L20.5 8.5" stroke="#4da6ff" stroke-width="1.8" fill="none"/>
            <path d="M11.5 11.2Q11.5 12.7 16 12.7Q20.5 12.7 20.5 11.2" stroke="#4da6ff" stroke-width="1.8" fill="none"/>
          </svg>
          <div class="logo-text">Bolo<span>DB</span></div>
        </a>
      </div>
      <div class="header-right">
        <a class="header-link" href="https://bolodb.dev" target="_blank" rel="noopener">Home</a>
        <a class="header-link" href="https://github.com/BoloDB/bolodb" target="_blank" rel="noopener">GitHub</a>
        <div class="search-box">
          <svg class="search-icon" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="8"/><path d="M21 21l-4.35-4.35"/></svg>
          <input class="search-input" id="search-input" type="text" placeholder="Search docs... (⌘K)" autocomplete="off" />
          <div class="search-results" id="search-results"></div>
        </div>
      </div>
    </div>
  </header>

  <main class="main" style="margin-left:0">
    <div class="landing-hero">
      <h1>Ask your data.<br/><span class="gradient">Trust the answer.</span></h1>
      <p class="landing-sub">
        BoloDB is a multi-tenant text-to-SQL web application powered by DeepSeek v4 Flash via OpenRouter. Connect any SQL database, ask questions in plain English, and get instant answers with charts, confidence levels, and automatic self-repair. Manage workspaces with role-based access control.
      </p>
      <div class="landing-actions">
        <a class="btn btn-primary" href="pages/quick-start.html">
          <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M13 10V3L4 14h7v7l9-11h-7z"/></svg>
          Quick Start
        </a>
        <a class="btn btn-secondary" href="pages/what-is-bolodb.html">
          <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 6.253v13m0-13C10.832 5.477 9.246 5 7.5 5S4.168 5.477 3 6.253v13C4.168 18.477 5.754 18 7.5 18s3.332.477 4.5 1.253m0-13C13.168 5.477 14.754 5 16.5 5c1.747 0 3.332.477 4.5 1.253v13C19.832 18.477 18.247 18 16.5 18c-1.746 0-3.332.477-4.5 1.253"/></svg>
          Read the Docs
        </a>
        <a class="btn btn-secondary" href="https://github.com/BoloDB/bolodb" target="_blank" rel="noopener">
          <svg width="18" height="18" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>
          GitHub
        </a>
      </div>
    </div>

    <div class="landing-chapters">
      <h2>Documentation</h2>
      <div class="chapter-grid">
        <a class="chapter-card" href="pages/what-is-bolodb.html">
          <span class="chapter-num">Chapter 01</span>
          <h3>What is BoloDB?</h3>
          <p>The product in plain language — what happens when you connect a database and ask a question.</p>
        </a>
        <a class="chapter-card" href="pages/quick-start.html">
          <span class="chapter-num">Guide</span>
          <h3>Quick Start</h3>
          <p>Get BoloDB running in under 5 minutes with Docker.</p>
        </a>
        <a class="chapter-card" href="pages/question-to-answer.html">
          <span class="chapter-num">Chapter 02</span>
          <h3>Question → Answer</h3>
          <p>The full pipeline, step by step, with exact code locations for every step.</p>
        </a>
        <a class="chapter-card" href="pages/ai-layer.html">
          <span class="chapter-num">Chapter 03</span>
          <h3>The AI Layer</h3>
          <p>How BoloDB uses OpenRouter — models, prompts, API keys, retries, and errors.</p>
        </a>
        <a class="chapter-card" href="pages/schema-linking.html">
          <span class="chapter-num">Chapter 04</span>
          <h3>Schema Linking</h3>
          <p>How BoloDB picks which tables the AI sees — making answers cheaper and more accurate.</p>
        </a>
        <a class="chapter-card" href="pages/safety.html">
          <span class="chapter-num">Chapter 05</span>
          <h3>Safety & Self-Repair</h3>
          <p>Read-only enforcement, SQL validation, and the automatic repair loop.</p>
        </a>
        <a class="chapter-card" href="pages/trust.html">
          <span class="chapter-num">Chapter 06</span>
          <h3>Trust & Confidence</h3>
          <p>How BoloDB learns from your confirmations and computes confidence levels.</p>
        </a>
        <a class="chapter-card" href="pages/file-map.html">
          <span class="chapter-num">Chapter 07</span>
          <h3>File Map</h3>
          <p>Every file in the repository with a one-line description.</p>
        </a>
        <a class="chapter-card" href="pages/troubleshooting.html">
          <span class="chapter-num">Chapter 08</span>
          <h3>Troubleshooting</h3>
          <p>"Something is wrong" → what it means → where to look → how to fix it.</p>
        </a>
        <a class="chapter-card" href="pages/cost.html">
          <span class="chapter-num">Chapter 09</span>
          <h3>Cost Optimisation</h3>
          <p>Where AI costs come from and every mechanism BoloDB uses to keep them low.</p>
        </a>
        <a class="chapter-card" href="pages/auth-workspaces.html">
          <span class="chapter-num">Chapter 10</span>
          <h3>Auth &amp; Workspaces</h3>
          <p>Multi-tenant RBAC — JWT auth, Google OAuth, roles, permissions, and workspace management.</p>
        </a>
        <a class="chapter-card" href="pages/dashboards-charts.html">
          <span class="chapter-num">Chapter 11</span>
          <h3>Dashboards &amp; Charts</h3>
          <p>ECharts visualizations — bar, line, area, pie, number, and table charts auto-inferred from query results.</p>
        </a>
        <a class="chapter-card" href="pages/semantic-layer.html">
          <span class="chapter-num">Chapter 12</span>
          <h3>Semantic Layer</h3>
          <p>Custom business metrics, join paths, synonyms, and value mappings to guide AI SQL generation.</p>
        </a>
        <a class="chapter-card" href="pages/api-reference.html">
          <span class="chapter-num">Reference</span>
          <h3>API Reference</h3>
          <p>All REST endpoints with request/response shapes and code locations.</p>
        </a>
      </div>
    </div>

    <div class="arch-preview">
      <h2>Architecture Overview</h2>
      <div class="arch-diagram">
  Browser (SvelteKit 5 frontend, frontend/src)
     │  HTTP / SSE streaming (JWT cookie auth, X-Workspace-Id, X-Db-Id)
     ▼
  FastAPI backend (backend/app)
     │
     ├── controllers/query.py ── the question→answer pipeline (the heart)
     ├── llm.py ──────────────── the ONLY file that talks to OpenRouter (DeepSeek v4 Flash)
     ├── schema_link.py ──────── scores tables, picks what the AI sees
     ├── sqlvalidate.py ──────── static AST validation against real schema
     ├── repair.py ───────────── self-repair loop with schema-retry
     ├── semantic.py ─────────── semantic layer catalog & inference
     ├── database.py ─────────── DB introspection & read-only execution
     ├── dialects.py ─────────── per-dialect traits (PostgreSQL, MySQL, Oracle, Snowflake...)
     ├── pgdatabase/ ─────────── async PostgreSQL persistence (knowledge, users, workspaces)
     └── permissions.py ──────── RBAC — 21 capabilities across 7 resources</div>
    </div>
  </main>

  <script src="js/main.js"></script>
</body>
</html>