Complete Platform Architecture

How BetterBee Works Under the Hood

A comprehensive overview of our retrieval-augmented generation pipeline, supported file formats, industry applications, and security guarantees.

Section 01

The Ingestion & Retrieval Pipeline

End-to-end data lifecycle from raw document upload to cited streaming generation.

Direct-to-S3 Ingestion

Client requests presigned upload URLs directly from FastAPI. Raw bytes upload directly to private AWS S3, bypassing web proxy bottlenecks.

Layout-Aware Structural Parsing

Background tasks parse documents while preserving layout anchors: PDF page numbers, Word headings, Excel sheet tabs, and PowerPoint slide indices.

Vector Embeddings & Tenant Isolation

Text is chunked into 1000-character blocks with overlap, transformed into 384-dimensional dense vectors via SentenceTransformers, and stored in isolated ChromaDB collections.

Grounded LLM Synthesis & Streaming

ChromaDB cosine retrieval fetches top matches. Groq Llama 3 synthesizes answers streamed via SSE with verifiable citation metadata.

Preserving Structural Truth

Unlike basic search systems that concatenate entire documents into flat text, BetterBee's parsing engine retains coordinate anchors:

Page Numbers: Injected into chunk metadata during PDF page extraction.
Slide Indices: Tagged on PowerPoint shapes and slide notes.
Sheet & Row Keys: Formatted into structured Markdown tables from Excel workbooks.
Recursive Chunking: 1,000 characters per chunk with 200-character overlaps to prevent split definitions.

Execution Flow & Latency Budget (~420ms total)

1. Client Query & Auth Verification: 15 ms

2. ChromaDB Dense Vector Search: 45 ms

3. Context Assembly & Prompt Injection: 8 ms

4. Groq TTFT (Time to First Token): 110 ms

5. SSE Token Streaming & Citations: 242 ms

Section 02

Enterprise Industry Use Cases

How legal, finance, engineering, and operations teams leverage BetterBee daily.

Legal & Compliance

Contract auditing, liability review, and regulatory clauses

Accelerate agreement review by asking direct questions across NDAs, MSAs, and vendor contracts. Locate governing law clauses, termination notice periods, and liability caps in seconds.

Example Questions:

“What are our indemnification obligations in Vendor_Agreement_2024.pdf?”

“List all contracts with auto-renewal notice periods under 30 days.”

“Compare Section 4 (IP Assignment) across Version 1 and Version 2.”

Finance & Operations

Balance sheet analysis, quarterly reports, and budget variance

Cross-reference multi-tab Excel models and PDF investor updates. Extract EBITDA figures, operational expense ratios, and revenue breakdowns without manual cell hunting.

Example Questions:

“What was the operating profit margin variance between Q2 and Q3?”

“Extract the capital expenditure table from FY24_Budget.xlsx.”

“Summarize all risk factors listed in the annual audit report.”

Engineering & Architecture

Technical specifications, API docs, and architecture RFCs

Give engineering teams instant access to system specifications, database schemas, and migration runbooks. BetterBee indexes Markdown and technical specs seamlessly.

Example Questions:

“What is the required authentication header format for the Payments API?”

“Find the disaster recovery failover steps in Infrastructure_Runbook.md.”

“Which database tables contain customer billing metadata?”

HR & Employee Onboarding

Company policies, employee handbooks, and standard procedures

Empower employees to self-serve answers regarding healthcare benefits, PTO policies, travel expense limits, and security guidelines through natural conversation.

Example Questions:

“What is the maximum reimbursement for home office equipment?”

“What are the steps to request parental leave under Employee_Handbook.pdf?”

“What is the standard procedure for reporting security vulnerabilities?”

Section 03

Supported Document Formats

Native parsers built for structural extraction without information loss.

PDF Documents

.pdf

Extracts textual content while tracking individual page boundaries. Handles complex multi-page reports, legal filings, and whitepapers.

Page-level citation attribution

Header/footer filtering

Multi-column text flow support

Microsoft Word

.docx

Parses headings, paragraph hierarchies, bulleted lists, and embedded tables from Word (.docx) specifications and contracts.

Section & heading preservation

Embedded table cell extraction

Footnote and bullet list parsing

Excel Spreadsheets

.xlsx

Iterates across all worksheet tabs, formatting rows and tabular cell grids into clean Markdown tables suitable for LLM reasoning.

Multi-sheet name preservation

Header-row schema mapping

Numerical cell formatting retention

PowerPoint Presentations

.pptx

Extracts text boxes, slide titles, bullet hierarchies, and presenter speaker notes from presentation decks.

Slide-number indexing

Slide title semantic grouping

Speaker note text extraction

Markdown

.md

Preserves GitHub-flavored Markdown formatting, fenced code snippets, callout blocks, and structural table grids.

Heading outline preservation

Fenced code block grouping

Link & footnote retention

Plain Text & Logs

.txt

Fast ingestion of standard plain text, logs, configuration files, and transcribed audio/meeting transcripts.

Chunk overlap continuity

UTF-8 / ASCII compatibility

Fast zero-overhead parsing

Section 04

Security & Data Governance

Guaranteed tenant isolation, zero model training, and private cloud storage.

Zero Model Training

Your uploaded documents, indexed vector embeddings, and conversation histories are strictly your property. BetterBee never contributes customer data to public AI training datasets or third-party corpuses.

Tenant-Isolated Vector Collections

Embeddings in ChromaDB are segregated by workspace identifiers. Vector similarity queries are restricted to the selected workspace boundary, mathematically preventing cross-tenant information bleed.

Private AWS S3 Storage & Encryption

Uploaded files reside directly in your private AWS S3 bucket. All transfers utilize TLS 1.3 in transit and AWS SSE-S3 256-bit encryption at rest. Pre-signed upload URLs expire within 60 minutes.

Clerk JWT Authentication & JWKS Caching

Every API request is authenticated via JSON Web Tokens (JWT) verified against Clerk's cryptographically signed public keys. Fast local JWKS caching ensures zero verification network bottlenecks.

Infrastructure & Security Specifications

Data at RestAWS S3 AES-256 server-side encryption & PostgreSQL encryption

Data in TransitEnforced TLS 1.3 for all REST endpoints, SSE streams, and S3 direct uploads

Authentication LayerClerk OAuth / SSO with JWT session tokens and short-lived JWKS signatures

Vector Storage IsolationChromaDB collection per-workspace partitioning with strict foreign-key verification

Start Searching Your Documents Today

Create your first workspace, upload company documentation, and start receiving grounded answers in minutes.

Open Workspaces