Architecture Decision Records
This directory contains Architecture Decision Records (ADRs) for the Knowledge Graph System. Each ADR documents a significant architectural decision, its context, and consequences.
ADR Format
All ADRs follow a consistent format: - Status: Draft / Proposed / Accepted / Deprecated / Superseded - Date: When the decision was made - Deciders: Who made the decision - Context: The problem or situation requiring a decision - Decision: The architectural choice made - Consequences: Benefits, drawbacks, and other impacts
This index is auto-generated by adr index. Configuration: adr.yaml
Infrastructure
Containers, deployment, backup, storage, networking
| ADR | Title | Status |
|---|---|---|
| ADR-100 | Database-Driven Job Dispatch | Accepted |
| ADR-101 | ROCm Image Variant and Install-Time Selection | Accepted |
| ADR-102 | Portable Backup and Restore with Clone/Merge Semantics | Accepted |
| ADR-103 | Distribution strategy: nomic-first thin appliance with app-store tenancy | Proposed |
| ADR-104 | Unified provisioning architecture: install-path convergence and first-run claim protocol | Draft |
| ADR-105 | Scenario-driven TLS via an in-VM Traefik router | Accepted |
| ADR-106 | API Server Architecture for Scalable Neo4j Access | Accepted |
| ADR-107 | Backup/Restore Streaming Architecture | Accepted |
| ADR-108 | Server-Sent Events for Real-Time Progress Streaming | Draft |
| ADR-109 | Admin Module Architecture Pattern | Accepted |
| ADR-110 | Live Man Switch - AI Safety for Critical Operations | Superseded |
| ADR-111 | Scheduled Jobs System | Proposed |
| ADR-112 | CDN and Serverless Deployment Model | Proposed |
| ADR-113 | Timezone-Aware Datetime Utilities | Accepted |
| ADR-114 | Projection Artifact Storage in Garage | Accepted |
| ADR-115 | Garage Service Architecture | Proposed |
| ADR-116 | Artifact Persistence Pattern | Accepted |
| ADR-117 | Deployment Topology (Dev/Stable Split) | Draft |
| ADR-118 | Semantic Election Protocol for Distributed Concept Placement | Proposed |
| ADR-119 | appliance configuration delivery and first-boot orchestration | Draft |
Database/Schema
Apache AGE, migrations, schema design, PostgreSQL
| ADR | Title | Status |
|---|---|---|
| ADR-200 | Annealing Ontologies — Self-Organizing Knowledge Graph Structure | Accepted |
| ADR-201 | In-Memory Graph Acceleration Extension | Draft |
| ADR-202 | Timestamp Timezone Normalization | Proposed |
| ADR-203 | Graph Epoch Event Log | Draft |
| ADR-204 | Node Type and Abstract Property Representation for Concept Nodes | Draft |
| ADR-205 | PostgreSQL 18 Migration | Draft |
| ADR-206 | Closed-Vocabulary Annealing Actions with Tiered Escalation and Epistemic Ledger | Draft |
| ADR-207 | A Uniform Freshness Contract for Materialized Graph Derivations | Accepted |
| ADR-208 | Apache AGE Migration (Neo4j Replacement) | Proposed |
| ADR-209 | Multi-Schema PostgreSQL Architecture | Proposed |
| ADR-210 | Database Schema Migration Management | Proposed |
| ADR-211 | Operator Pattern for Platform Lifecycle Management | Accepted |
Ingestion
Content processing, jobs, extraction, deduplication
| ADR | Title | Status |
|---|---|---|
| ADR-300 | Job Approval Workflow with Pre-Ingestion Analysis | Draft |
| ADR-301 | Markdown Structured Content Preprocessing | Proposed |
| ADR-302 | Multimodal Image Ingestion with Configurable Prompt System | Proposed |
| ADR-303 | Human-Guided Graph Editing | Proposed |
| ADR-304.1 | Graph-Based Provenance Tracking | Proposed |
| ADR-304.2 | API Changes for Graph-Based Document Deduplication | Draft |
| ADR-305.1 | Multimodal Image Ingestion with Visual Context Injection | Proposed |
| ADR-305.2 | Appendix: Single-Stage vs Two-Stage Image Processing | Draft |
| ADR-306 | Concept Matching Strategies and Configuration | Draft |
| ADR-307 | Source Document Lifecycle | Proposed |
| ADR-308 | Deterministic Node and Edge Creation | Draft |
Auth/Security
RBAC, OAuth, API keys, endpoint security
| ADR | Title | Status |
|---|---|---|
| ADR-400 | Operative RBAC and Endpoint Security Baseline | Accepted |
| ADR-401 | Deterministic Security Enforcement Baseline | Draft |
| ADR-402 | Client-Initiated Token Revocation for Elevated Operations | Superseded |
| ADR-403 | User Management API with Lightweight JWT Authentication | Superseded |
| ADR-404 | Dynamic Role-Based Access Control (RBAC) System | Superseded |
| ADR-405 | Encrypted API Key Storage with Container Secrets | Accepted |
| ADR-406 | OAuth 2.0 Client Management for Multi-Client Authentication | Accepted |
| ADR-407 | API Endpoint Security Architecture | Superseded |
| ADR-408 | MCP File Ingestion Security Model | Draft |
| ADR-409 | Platform Admin Role | Superseded |
| ADR-410 | User Scoping and Artifact Ownership Model | Accepted |
Query/Search
Pathfinding, projections, diversity, search
| ADR | Title | Status |
|---|---|---|
| ADR-500 | Graph Program DSL and AST Architecture | Draft |
| ADR-501 | Catalog Browse Facade | Proposed |
| ADR-502 | Concept Deduplication Quality Validation | Accepted |
| ADR-503 | Semantic Diversity as Authenticity Signal | Draft |
| ADR-504 | Published Query Endpoints | Proposed |
| ADR-505 | Parallel Graph Query Optimization | Accepted |
| ADR-505.1 | Parallel Graph Query Implementation Findings | Accepted |
| ADR-506 | Pathfinding Optimization for Apache AGE | Proposed |
| ADR-506.1 | Pathfinding Performance Baseline | Accepted |
| ADR-507 | Document-Level Search | Proposed |
| ADR-508 | Configurable Search Similarity Threshold | Draft |
Vocabulary
Relationships, grounding, categorization
| ADR | Title | Status |
|---|---|---|
| ADR-600 | Semantically Sparse 30-Type Relationship Taxonomy | Accepted |
| ADR-601 | Dynamic Relationship Vocabulary Management | Proposed |
| ADR-602 | Autonomous Vocabulary Curation and Ontology Management | Proposed |
| ADR-603.1 | Automatic Edge Vocabulary Expansion with Intelligent Pruning | Proposed |
| ADR-603.2 | Implementation Quick Reference | Accepted |
| ADR-604 | Grounding-Aware Vocabulary Management | Proposed |
| ADR-605 | Probabilistic Vocabulary Categorization | Accepted |
| ADR-606 | Vocabulary Metadata as First-Class Graph | Accepted |
| ADR-607 | Vocabulary Expansion-Consolidation Cycle (The "Dreaming" Pattern) | Accepted |
| ADR-608 | Eager Vocabulary Categorization | Accepted |
| ADR-609 | LLM-Determined Relationship Direction Semantics | Proposed |
| ADR-610 | Vocabulary-Based Provenance Relationships | Accepted |
| ADR-611 | Vocabulary Explorers | Draft |
Interfaces
CLI, web, FUSE, MCP, visualization
| ADR | Title | Status |
|---|---|---|
| ADR-700 | Ontology Explorer | Draft |
| ADR-701 | Vocabulary Administration Interface | Draft |
| ADR-702 | Unified Graph Rendering Engine | Proposed |
| ADR-703 | Ontology Lifecycle Administration Interface | Draft |
| ADR-704 | Unified User-Scoped Resource Dispensing | Draft |
| ADR-705 | Session Visibility and Declarative Capability Gating | Draft |
| ADR-706 | CLI and Admin Tooling Separation | Accepted |
| ADR-707 | Unified TypeScript Client (CLI + MCP Server) | Accepted |
| ADR-708 | Type-Based Table Formatting System | Accepted |
| ADR-709 | CLI Theory of Operation - Hybrid Unix/Domain-Specific Design | Proposed |
| ADR-710 | Graph Visualization & Interactive Query Explorers | Proposed |
| ADR-711 | Explorer Methods, Uses, and Capabilities | Proposed |
| ADR-712 | Universal Visual Query Builder | Proposed |
| ADR-713 | Specialized Truth Convergence Visualizations | Proposed |
| ADR-714 | Web Application Workstation Architecture | Proposed |
| ADR-715 | Semantic FUSE Filesystem | Accepted |
| ADR-715.1 | FUSE Driver Implementation Specifics | Proposed |
| ADR-716 | Postmodern Theme System | Proposed |
| ADR-717 | Embedding Landscape Explorer | Accepted |
| ADR-718 | Document Explorer with Radial Concept Visualization | Proposed |
AI/Embeddings
Providers, extraction, convergence, prompts
| ADR | Title | Status |
|---|---|---|
| ADR-800 | Dynamic Model Catalog and OpenRouter Support | Accepted |
| ADR-801 | Uniform Provider Configuration Contract | Draft |
| ADR-802 | Unify Vision Providers Under the Uniform Provider Contract | Accepted |
| ADR-803 | Modality Embedding Architecture — Universal Text Space and Independent Per-Modality Embedders | Accepted |
| ADR-804 | Local Embedding Service with Hybrid Client/Server Architecture | Proposed |
| ADR-805 | AI Extraction Provider Configuration | Proposed |
| ADR-806 | Local LLM Inference for Concept Extraction | Accepted |
| ADR-807 | Single-Node Resource Management for Local Inference | Accepted |
| ADR-808 | Probabilistic Truth Convergence Through Contradiction Resolution | Proposed |
| ADR-809 | Unified Embedding Generation System | Proposed |
| ADR-810 | Rate Limiting and Per-Provider Concurrency Management | Accepted |
| ADR-811 | Polarity Axis Triangulation for Grounding Calculation | Accepted |
| ADR-812 | Source Text Embeddings for Grounding Truth Retrieval | Accepted |
| ADR-813 | Polarity Axis Analysis for Bidirectional Semantic Dimensions | Accepted |
Meta/Process
Documentation, workflow, access models, ADR system
| ADR | Title | Status |
|---|---|---|
| ADR-900 | ADR Numbering Domain System | Accepted |
| ADR-901 | Multi-Tier Agent Access Model | Proposed |
| ADR-902 | Node Fitness Scoring System | Proposed |
| ADR-903 | Semantic Tool Hint Networks | Proposed |
| ADR-904 | Pure Graph Design (Library Metaphor) | Proposed |
| ADR-905 | Source Text Tracking and Retrieval | Proposed |
| ADR-906 | Staging and Migration Workflows | Proposed |
| ADR-907 | Official Project Apparel Design Specifications | Proposed |
| ADR-908 | Documentation Strategy and Audience Framework | Accepted |