One AI knowledge hub for everything bot.auto knows.
A single-tenant AI knowledge hub over Confluence and Slack first, with the same adapter framework extending to your other third-party tools and internal applications, and every answer cited, fresh, and backed by coverage you can audit.
A knowledge hub 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 knowledge hub 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 knowledge hub 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
core answer pathplatform componentyour systems / externalphased scope
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
core answer pathplatform componentyour systems / externalphased scope
| 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 | Routes each question, chooses the retrieval strategy, assembles the answer with per-claim citations, and gates on confidence ("I don't know" over guessing). Hosts the Phase 2 plan-then-execute runtime for analytical questions. | Core module; every answer 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. The verification policy is explicit: answers about current state (permissions, statuses, latest versions) re-check their top citations against the live source, and when the source cannot be reached the answer says so rather than asserting currency. 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; polling is demoted to low-frequency reconciliation sweeps that catch anything a disconnect missed. 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 |
Any system can join. The adapter contract is deliberately small: a connector reads its source and emits items in the platform's canonical schema (content, author, timestamps, permissions), and everything downstream, indexing, retrieval, citations, freshness tracking, works unchanged. That is how Jira, Drive, Salesforce, data warehouses, and your internal applications and databases onboard in Phase 3 without rearchitecting.
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 inside an isolated execution environment with per-run scoped credentials and no standing access, 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; content-borne instructions blocked from invoking tools or plans by layered, adversarially tested controls; plan execution reaches only approved APIs with per-run scoped credentials |
| Audit | Audit events stream to write-once storage and your SIEM, independent of the operational database; auditor role read-only; per-answer reproducibility record; gateway logs request metadata only |
- Data store. Multi-AZ PostgreSQL with point-in-time-recovery backups and scheduled restore tests; read replicas offload retrieval as the corpus grows; vector index rebuilds run against a replica, never the primary.
- Model gateway. Stateless and horizontally replicated behind the cluster service, with provider fallback chains; if the gateway is unavailable, chat degrades to a clear retry state rather than silent failure.
- Disaster recovery. RTO and RPO targets are agreed in the discovery sprint; the architecture supports cross-region restore from versioned object-store payloads plus database point-in-time recovery.
- Backfill budget. Ingestion distillation runs under a dedicated, rate-limit-aware model budget with prioritization; a keyword-only degraded mode keeps search available if enrichment lags.
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 knowledge hub 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 in an isolated execution environment, semantic catalog editing, skills, wiki pinning, expert lookup, report artifacts |
| 3 · Expansion | on call | Jira, Drive, Salesforce, warehouse connectors with live SQL; internal applications and databases via the same adapter contract; scheduled automations; platform API |