QueryLlama: Architecture & Build-Status Reference

QueryLlama is a hosted, multi-tenant SaaS platform for searching an organization's documents by keyword, by meaning, or both, with a planned retrieval-augmented-generation (RAG) layer for question-answering. The platform is in active early development. This reference distinguishes what is implemented and running today from what is designed in the schema or specification but not yet coded, so it can be used honestly in a security or procurement review.

The system is composed of a Next.js frontend deployed on Cloudflare Pages, a NestJS API deployed on Render, a Cloudflare Workers-based document-ingestion pipeline, Cloudflare R2 for file storage, and a Supabase-hosted Postgres database with the pgvector extension for embeddings. There is no desktop or on-premise component — QueryLlama is fully hosted.

• Frontend: Next.js, static export, Cloudflare Pages
• API: NestJS (TypeScript, strict mode), hosted on Render
• Ingestion: Cloudflare Workers, triggered via Cloudflare Queues
• File storage: Cloudflare R2
• Database: Supabase Postgres with pgvector

A client uploads a file directly to Cloudflare R2 via a presigned URL issued by the API, so file bytes never transit the API server. The API then enqueues a processing job on Cloudflare Queues. A Worker picks up the job, retrieves the file from R2, splits its text into overlapping chunks using a sliding window of approximately 2,048 characters with a 400-character overlap, computes a 768-dimension embedding per chunk via Cloudflare Workers AI (a BGE-base model), and writes the chunks and embeddings into Postgres, scoped to the uploading organization.

Supported file types are planned to include PDF, DOCX, XLSX, PPTX, TXT, Markdown, HTML, CSV, and common image formats; OCR for scanned documents and images, and parsing for some of these formats, are still being implemented. Virus/malware scanning on upload is designed but not yet implemented.

Every primary table — organizations, users, files, document chunks, audit logs — carries an organization-ID foreign key. Postgres Row-Level Security policies are defined on each of these tables, scoping every SELECT, INSERT, UPDATE and DELETE to rows belonging to the requesting user's organization. This is enforced inside the database engine itself: a bug in application-layer authorization logic cannot cause a cross-organization data leak, because the database will not return or accept rows outside the caller's scope.

Five roles are defined: super_admin (cross-organization platform operator), org_admin (manages an organization's users, documents and settings), group_admin (manages a subset of users or documents within an organization), member (can search and, once available, ask questions), and viewer (read-only search). These roles are enforced through the same Row-Level Security policy layer described above, rather than through application-only checks.

Group-level, fine-grained permission rules within an organization (for example, restricting a group's access to a subset of documents) are designed but not yet implemented.

An audit_logs table exists with fields for organization, actor, action, resource, resource ID, metadata, IP address, user agent, and timestamp. A database trigger blocks UPDATE and DELETE operations on this table outright, making a written entry immutable once recorded. What is not yet complete is the API-side instrumentation that writes every relevant action — document upload, search, role change, and so on — through to this table. The schema and the immutability guarantee are real today; comprehensive event coverage is in progress.

Keyword search is designed around Postgres full-text search over a generated tsvector column on document chunks. Semantic search is designed around pgvector cosine-similarity search over the 768-dimension chunk embeddings, using an IVFFlat index. Hybrid search — combining both result sets via reciprocal rank fusion — is specified but its implementation, along with any reranking step, has not yet shipped.

The planned RAG flow retrieves the top-ranked chunks for a query, constructs a prompt, and generates a streamed answer via an LLM (Cloudflare's Llama 3.1 8B Instruct by default), with citations referencing the source files the answer drew from. As of this writing, the API endpoint and the answer-generation flow are not yet implemented; only the underlying data model (an events table referencing source file IDs) exists.

The data model includes a per-organization AI-configuration table for a custom endpoint, model name, and a reference to a securely vaulted API key, intended to be proxied through Cloudflare AI Gateway. The OpenAI-compatible API format is the intended baseline for compatibility. The proxying logic and key-vault integration are designed but not yet implemented.

Authentication is designed around Supabase Auth, supporting email/password, Google and Microsoft OAuth, and TOTP-based two-factor authentication, with secure (httpOnly, Secure, SameSite=Strict) session cookies. Frontend login, registration and password-reset pages exist; the corresponding API endpoints are part of the active build, not yet wired end-to-end.

The data model includes a tier field on organizations (free, pro, enterprise), and the intended gating is: keyword and semantic search available broadly, hybrid search and RAG on paid tiers, and bring-your-own-LLM reserved for enterprise. As of this writing, there is no code-level enforcement of these limits and no billing integration — tier is a label in the schema, not yet an active gate.

The MVP is designed to run entirely on the free tiers of its constituent services (Render, Supabase, Cloudflare, and others), with a target run-rate of $0/month at MVP scale. Logging (via pino to Axiom) and error tracking (Sentry) are part of the design; full distributed tracing and metrics dashboards are specified but only partially integrated as of this writing.