Skip to main content

​
Motivation

Code shows what the system does; it rarely shows why. The Architecture Decision Records (ADRs) are the editorial trail of the choices that shaped AskMyDocs — each one a problem, the options weighed, the decision, and its consequences. This page is the narrative over those records: it groups them into the arcs they belong to and explains how each built on the last. The full records live in docs/adr/ in the repository.

​
The foundational arc: knowledge as a typed, governed asset

The first three ADRs define what makes AskMyDocs more than RAG-over-files.
  • ADR 0001 — Canonical knowledge layer. Decisions and rejections cannot be represented in a flat corpus. ADR 0001 adds typed canonical columns inside knowledge_documents (9 artifact types, status lifecycle, retrieval priority) so the system can carry “we chose X over Y” as first-class, ranked knowledge. See the retrieval pipeline.
  • ADR 0002 — Lightweight knowledge graph. Typed artifacts need typed relationships. ADR 0002 adds kb_nodes/kb_edges as a derived projection of markdown — rebuildable from Git — with project-scoped composite FKs. See the canonical graph.
  • ADR 0003 — Human-gated promotion. Machine-generated content must never silently become truth. ADR 0003 makes promotion a human editorial gate: skills and the suggest/candidates endpoints produce drafts; only humans (git → GitHub Action) and operators (kb:promote) commit canonical storage. This boundary is referenced by every later automation decision.

​
The integration arc: standalone packages, host wiring

As capabilities grew, they were extracted into reusable, MIT-licensed packages — the host uses them, never the reverse.
  • ADR 0004 — Sister-package integration. The IoC contract pattern: a package depends only on a host-bound interface; the host implements it with real retrieval / RBAC / audit.
  • ADR 0008 — Universal connectors + source-aware ingestion. Per-source converters and chunkers (Notion, Confluence, Drive, Jira, …) plus the modern chat surface. See connectors.
  • ADR 0009 — Connector package extraction. Each connector becomes its own composer package, discovered via composer-extra; the host binds them through the ingestion bridge. See sister packages.
  • ADR 0011 — AI-Act compliance integration. Disclosure, consent, and audit-evidence surfaces wired from extracted compliance packages. See PII & compliance.

​
The platform arc: review, workflows, notifications, lifecycle

  • ADR 0005 / ADR 0006 / ADR 0007 — the React 19 host bump, the nightly eval-harness regression cron, and the opt-in adversarial nightly: the quality-gate machinery that keeps retrieval honest over time.
  • ADR 0010 — Tabular Review + Workflows + AI-suggest. Structured multi-document extraction and reusable workflow templates over the Flow saga architecture. See the admin panel.
  • ADR 0012 — Notification system. A DB-backed multi-channel notification layer (mail / webhook / Slack / Teams / Discord).
  • ADR 0013 — KB lifecycle intelligence. Content-gap analytics, obsolescence-impact analysis, and search-failure rollups.
  • ADR 0023 — System administration boundary. Platform-wide registry authority (system-admin) is separated from maximum tenant privilege (super-admin), with a conservative legacy migration, protected CLI bootstrap and no MCP global write surface. See system administration.
  • ADR 0024 — Membership-required operational access. Global authority never implies customer-data access: every tenant route requires a real membership, while /api/system-admin/* remains the separate platform control plane.
  • ADR 0025 — Registration intent and company onboarding. Public codes distinguish joining one existing tenant from creating a new company, using a reserved string namespace rather than a numeric-ID range or a second invite table. See invitations.
  • ADR 0027 — Widget identity credentials and current-session restore. One tenant-scoped, audited credential core; an explicit identity-scoped current-session query; and the security-motivated exception that keeps one-time ik_ secrets out of MCP transcripts.
  • ADR 0028 — Source ACL mirroring and ingest-time provenance (shipped in three phases, v8.32 → v8.34). The ingestion contract records what a document is and not where its authority comes from, so a file shared with three people upstream becomes readable by everyone with the project. The design mirrors source permissions through two opt-in capability interfaces rather than a required argument — eight connectors and a public template consume that contract — and makes the load-bearing choice that a principal which cannot be resolved to an internal subject fails closed to restricted-unmapped instead of falling back to project-wide visibility, since that fallback is the bug being fixed. It also separates authorship origin (provenance) from curation tier (the Auto-Wiki firewall of ADR 0014): a human-accepted page summarising an external email is accepted and externally authored at once, and both facts matter. Enforcement extends the R33 SQL seam described in the security & threat model.

​
The autonomy arc: self-compiling knowledge, safely

  • ADR 0014 — Auto-Wiki auto tier. The culmination: an LLM compiles raw docs into enriched, cross-linked, navigable knowledge — but as a second-class generation_source='auto' tier, quarantined behind the reranker firewall and still subject to the ADR 0003 human promotion gate. It is the proof that automation and the trust gradient can coexist. See the auto-wiki engine.

​
The document-intelligence arc: from file to reviewed, portable knowledge

  • ADR 0029 — OCR converter, pluggable drivers, and OCR provenance. Scanned PDFs and images enter the same registry-driven pipeline as every other format: one OcrConverter registered before PdfConverter, four drivers behind one contract (docling, mistral-ocr, vision-llm, tesseract), figures written beside the document, a confidence per page, and — the load-bearing part — the existing PII seam (ADR 0020) and the existing provenance vocabulary (ADR 0028) reused unchanged. OCR records how the text was obtained, not who authored it; an OCR’d inbound letter stays external text that may be quoted but never drives a tool call. The cycle’s invariant is drawn here: an agent that read a scan may propose a correction, never commit one. Default-OFF until the review lane (W3) has a measured baseline.
  • ADR 0030 — Conversion artifacts on the Time Machine. The version model AskMyDocs already has — the archived knowledge_documents row and its chunks — finally carries the document itself. The converted Markdown becomes a stored artifact written in both ingest paths through the one persistence core, three nullable columns arrive with it — version_actor and version_reason record who created a version and why, content_hash is the integrity hash of the stored artifact — diff prefers artifacts and falls back to reconstruction (both branches tested), and retention and deletion cover the artifact. The erasure boundary is stated, not assumed: the Art.17 crypto-shred targets the vault and stops at the AI boundary — it never erases stored Markdown, OCR figures or the original source, which are raw assets before the PII seam; those are erased by hard-deleting the documents that contain the subject, an operator step of the DSAR runbook. No versions table is added: the family is the version model, and the narrower gap the audit found is closed without rebuilding what v8.7 shipped.

​
Decision rationale (meta)

  • Why keep ADRs at all? A wrong fact in a quick-reference propagates into queries and tests. ADRs are the durable why that survives staff turnover and keeps later PRs from unwinding deliberate constraints.
  • Why a narrative page on top of the index? The index is lookup; the arcs explain dependency — you cannot understand the auto-wiki tier (0014) without the promotion gate (0003) and the graph (0002).

​
Gotchas & operations

  • Do not unwind a non-obvious decision without a superseding ADR. The “no AI SDKs / raw Http::” choice, the human-gated promotion boundary, and the source-of-truth-is-markdown rule are load-bearing.
  • A new architectural decision ships its own ADR in docs/adr/ — each numbered record above links directly to its file.

Architecture overview

The system spine that connects the subsystems.

Auto-Wiki engine

The autonomy arc’s culmination (ADR 0014).