One assistant over everything bot.auto knows.
A single-tenant conversational AI platform over Confluence and Slack, extensible to the rest of your stack, with every answer cited, current, and complete.
A platform that treats trust as the feature.
Your team asked for three things most AI assistants cannot prove: all the information, the context behind it, and its freshness. This document presents the architecture that delivers each one as an engineered, verifiable property, not a promise.
The platform gives every employee one conversational surface over the organization's knowledge. Answers assemble strictly from retrieved company content with per-claim citations; when confidence is low the system says "I don't know" and shows what it searched. Conversations are shared threads, corrections become team knowledge, and everything runs inside your own cloud account.
Six principles govern every decision in the sections that follow:
Everything runs inside your cloud.
Employees and administrators reach the platform through the web application, authenticated against your identity provider. The platform syncs from your source systems, calls a model endpoint you choose, and streams its audit log to your SIEM.
Figure 1 / System context
One core application, two planes.
The core application serves conversations and answers; the sync plane keeps the index complete and fresh. PostgreSQL with pgvector is the single system of record for documents, vectors, keyword search, permissions, threads, and audit.
Figure 2 / Components, client VPC
| Component | Responsibility | Technology |
|---|---|---|
| Web app | Chat, thread sharing, citations with freshness badges, admin console | Next.js + TypeScript |
| API / BFF | OIDC authentication, sessions, rate limiting, streaming | NestJS or Go, single gateway |
| Agent orchestrator | Question classification, plan generation, deterministic execution, citation assembly, "I don't know" gating | Core module; plans stored for reproducibility |
| Retrieval | Hybrid search with a mandatory permission filter; fusion and reranking per Section 05 | Core module over Postgres |
| Semantic catalog | Entity and alias graph, glossary, team wiki, skills; auto-bootstrapped from source metadata | Core module, Postgres tables |
| LLM gateway | Single chokepoint for model and embedding calls; provider swap by configuration; virtual keys and budgets per workload; retries, fallbacks, spend tracking | Self-hosted gateway proxy, cluster-internal admin |
| Connectors | OAuth, backfill, incremental sync, rate-limit backoff, deletion tombstones | One worker per source, shared framework |
| Distiller | LLM structuring of threads at sync time (Section 04) | Worker, isolated model budget |
| PostgreSQL + pgvector | System of record: documents, chunks, vectors, keyword index, permissions, threads, catalog, audit | RDS / Cloud SQL, Multi-AZ |
| Object store | Raw payloads for replay and re-indexing, attachments | S3 / GCS, versioned, encrypted |
Data access that proves its coverage.
Each source gets one adapter with two faces sharing auth and client code: a sync face feeding the index continuously, and a runtime face of live tools the assistant calls for point lookups and freshness verification.
This hybrid is deliberate: querying vendor search APIs at question time cannot prove coverage or measure freshness, and an index alone can lag reality. The index provides recall across millions of items; the live tools confirm currency before an answer ships. All transport is HTTPS with cursor pagination, exponential backoff, idempotent upserts, and tombstones for deletions.
Figure 3 / Adapter anatomy, one per source
Slack sync runs on Socket Mode: the connector holds an outbound persistent WebSocket, so events arrive in real time with no public inbound endpoint and no polling against rate limits. Events are acknowledged instantly, deduplicated, and the whole thread is re-fetched and stored as one unit so conversations are never internally stale.
| Source | Change detection | Reconciliation | Freshness target |
|---|---|---|---|
| Slack | Socket Mode: outbound WebSocket push (messages, edits, deletes, membership) | Cursor sweep per channel watermark | < 1 min |
| Confluence | Webhooks (page created / updated / removed) | Delta polling on last-modified | < 15 min |
| Permissions, all sources | Synced with content events | Periodic full reconcile | < 15 min |
Ingestion enrichment. Raw conversational text is a poor embedding target, so ingestion is two-tier: raw text becomes keyword-searchable the moment it lands, while the semantic layer builds asynchronously. A distillation pass structures each thread into a normalized artifact (searchable question, summary, resolution, systems touched); a bursting pass additionally embeds high-signal message runs so answers buried in tangents stay findable.
Retrieval where no single scorer is trusted alone.
Four signals each cover the others' blind spots, their rankings fuse by consensus, and a reranker restores surrounding context before a word is generated.
| Signal | Catches | Fails at |
|---|---|---|
| Full-text | Exact tokens: pasted error strings, flag names, hostnames | Paraphrase |
| Vector similarity | Paraphrase: question and answer that share no vocabulary | Exact identifiers; short filler ranks too high |
| Term rarity | Rare-token substance over conversational filler | |
| Age decay | Newer answer wins ties; stale advice loses |
Each signal ranks the permission-filtered candidate set independently; the lists fuse by reciprocal rank fusion so cross-signal consensus beats any single strong vote. A compact reranker scores the fused top set against the actual question, and winners are re-expanded with neighboring context so chunking never severs preconditions from answers. Embedding remains a per-corpus dial: where evaluations show vectors add no recall for a source, that source stops being embedded.
Plan, then execute (Phase 2). For analytical, multi-step questions the orchestrator separates planning from execution: the LLM writes an inspectable step-by-step plan, the platform executes it deterministically with scoped credentials, and results return as artifacts with citations. The plan itself is shown to the user and stored with the answer. Until Phase 2, such questions are declined gracefully rather than answered badly.
Three guarantees, engineered rather than promised.
Each requirement you named maps to load-bearing machinery you can verify in operation, on a dashboard, not in a slide.
Security your reviewers can walk through.
Six layers, each with named controls; the system is designed to pass a security review, not to survive one.
| Layer | Controls |
|---|---|
| Identity | OIDC to your IdP; IdP-group to role mapping (Member / Admin / Auditor); SCIM optional; workload identity between services, no static keys |
| Authorization | Normalized permission table per document; retrieval joins the caller's resolved principals; render-time re-check with the caller's own token |
| Data protection | TLS 1.2+ everywhere; KMS-encrypted storage; secrets in your secrets manager; source credentials never enter model context |
| Model boundary | All model traffic egresses through one gateway: provider allow-list, zero-data-retention configuration, per-workload keys and budgets; fully in-VPC inference available via Bedrock or Vertex private endpoints; network policy denies model egress to every other component |
| Prompt injection | Retrieved content delimited as untrusted data; instructions inside documents can never trigger tools or plans; plan execution reaches only approved APIs with per-run scoped credentials |
| Audit | Append-only audit tables streamed to your SIEM; auditor role read-only; per-answer reproducibility record; gateway logs request metadata only |
Seven decisions, trade-offs on the table.
Every major choice is recorded with its rationale and the cost we accept, so your team can challenge any of them before a line of code is written.
| # | Decision | Rationale | Trade-off accepted |
|---|---|---|---|
| 01 | Modular monolith core plus separate sync workers | Small team, unclear final boundaries; single-tenant scale needs no service sprawl | Later extraction cost; strict module boundaries keep it cheap |
| 02 | PostgreSQL + pgvector as the only database | One system of record; ~10M documents fits comfortably; fewest moving parts in a client-operated deployment; validated by production systems running this pattern at comparable scale | A dedicated search engine slots in behind the retrieval interface if the corpus grows ~10x |
| 03 | Ingest-and-index for v1; live query-at-source deferred | Collaboration-tool search APIs are too weak and rate-limited for grounded answers | Bounded, displayed sync lag; live SQL arrives in Phase 3 for warehouse-class connectors |
| 04 | Grounded, cited answers in v1; planning agent in Phase 2 | Citation-grounded retrieval covers the dominant lookup use case and ships months earlier | v1 declines heavy analytical questions gracefully |
| 05 | Self-hosted model gateway, provider-agnostic | Bedrock, Vertex, or direct API with zero data retention becomes a configuration entry; keys, budgets, retries, and spend tracking arrive built in | Provider-specific features need deliberate passthrough; one more component to operate |
| 06 | Kubernetes + Helm + Terraform as the delivery unit | Portable, auditable way to ship versioned updates into your cloud | Requires platform maturity; a managed-ops engagement is offered |
| 07 | Hybrid access per source class | Coverage and freshness guarantees force an index for conversational sources; native query engines beat any index for structured data; live tools give the freshness escape hatch | We own permission-sync correctness for indexed sources, mitigated by regression tests and render-time re-checks |
A phased path to production.
A discovery sprint settles the open questions, foundation follows, a working assistant over Confluence and Slack ships next, intelligence layers on top, and expansion runs on your timetable.
| Phase | Duration | Delivers |
|---|---|---|
| 0 · Discovery & foundation | 4-6 wk | Discovery sprint settles cloud and region, inference posture (in-VPC vs zero-data-retention agreement), scale inputs, operations model, and retention requirements; then infrastructure as code, Kubernetes, SSO, skeleton app, model gateway, audit logging |
| 1 · MVP | 10-12 wk | Confluence and Slack connectors with backfill and real-time sync, distillation pipeline, permission-aware hybrid retrieval, cited and freshness-badged chat, shared threads, project scoping, admin console with coverage and freshness dashboards |
| 2 · Intelligence | 8-10 wk | Plan-then-execute runtime, semantic catalog editing, skills, wiki pinning, expert lookup, report artifacts |
| 3 · Expansion | on your call | Jira, Drive, Salesforce, warehouse connectors with live SQL; scheduled automations; platform API |