Architecture decisions

​

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 (proposed — design only, nothing shipped). 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.

​

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.