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-012 | API Server Architecture for Scalable Neo4j Access | Accepted |
| ADR-015 | Backup/Restore Streaming Architecture | Accepted |
| ADR-018 | Server-Sent Events for Real-Time Progress Streaming | Draft |
| ADR-020 | Admin Module Architecture Pattern | Accepted |
| ADR-021 | Live Man Switch - AI Safety for Critical Operations | Superseded |
| ADR-050 | Scheduled Jobs System | Proposed |
| ADR-055 | CDN and Serverless Deployment Model | Proposed |
| ADR-056 | Timezone-Aware Datetime Utilities | Accepted |
| ADR-079 | Projection Artifact Storage in Garage | Accepted |
| ADR-080 | Garage Service Architecture | Proposed |
| ADR-083 | Artifact Persistence Pattern | Accepted |
| ADR-086 | Deployment Topology (Dev/Stable Split) | Draft |
| ADR-088 | Semantic Election Protocol for Distributed Concept Placement | Proposed |
Database/Schema
Apache AGE, migrations, schema design, PostgreSQL
| ADR | Title | Status |
|---|---|---|
| ADR-016 | Apache AGE Migration (Neo4j Replacement) | Proposed |
| ADR-024 | Multi-Schema PostgreSQL Architecture | Proposed |
| ADR-040 | Database Schema Migration Management | Proposed |
| ADR-061 | Operator Pattern for Platform Lifecycle Management | Accepted |
| ADR-200 | Breathing Ontologies — Self-Organizing Knowledge Graph Structure | Draft |
Ingestion
Content processing, jobs, extraction, deduplication
| ADR | Title | Status |
|---|---|---|
| ADR-014 | Job Approval Workflow with Pre-Ingestion Analysis | Draft |
| ADR-023 | Markdown Structured Content Preprocessing | Proposed |
| ADR-033 | Multimodal Image Ingestion with Configurable Prompt System | Proposed |
| ADR-037 | Human-Guided Graph Editing | Proposed |
| ADR-051 | Graph-Based Provenance Tracking | Proposed |
| ADR-051 | API Changes for Graph-Based Document Deduplication | Draft |
| ADR-057 | Multimodal Image Ingestion with Visual Context Injection | Proposed |
| ADR-057.2 | Appendix: Single-Stage vs Two-Stage Image Processing | Draft |
| ADR-072 | Concept Matching Strategies and Configuration | Draft |
| ADR-081 | Source Document Lifecycle | Proposed |
| ADR-089 | Deterministic Node and Edge Creation | Draft |
Auth/Security
RBAC, OAuth, API keys, endpoint security
| ADR | Title | Status |
|---|---|---|
| ADR-017 | Client-Initiated Token Revocation for Elevated Operations | Proposed |
| ADR-027 | User Management API with Lightweight JWT Authentication | Superseded |
| ADR-028 | Dynamic Role-Based Access Control (RBAC) System | Proposed |
| ADR-031 | Encrypted API Key Storage with Container Secrets | Accepted |
| ADR-054 | OAuth 2.0 Client Management for Multi-Client Authentication | Accepted |
| ADR-060 | API Endpoint Security Architecture | Proposed |
| ADR-062 | MCP File Ingestion Security Model | Draft |
| ADR-074 | Platform Admin Role | Proposed |
| ADR-082 | User Scoping and Artifact Ownership Model | Accepted |
Query/Search
Pathfinding, projections, diversity, search
| ADR | Title | Status |
|---|---|---|
| ADR-030 | Concept Deduplication Quality Validation | Accepted |
| ADR-063 | Semantic Diversity as Authenticity Signal | Draft |
| ADR-066 | Published Query Endpoints | Proposed |
| ADR-071 | Parallel Graph Query Optimization | Accepted |
| ADR-071.1 | Parallel Graph Query Implementation Findings | Accepted |
| ADR-076 | Pathfinding Optimization for Apache AGE | Proposed |
| ADR-076.1 | Pathfinding Performance Baseline | Accepted |
| ADR-084 | Document-Level Search | Proposed |
Vocabulary
Relationships, grounding, categorization
| ADR | Title | Status |
|---|---|---|
| ADR-022 | Semantically Sparse 30-Type Relationship Taxonomy | Accepted |
| ADR-025 | Dynamic Relationship Vocabulary Management | Proposed |
| ADR-026 | Autonomous Vocabulary Curation and Ontology Management | Proposed |
| ADR-032 | Automatic Edge Vocabulary Expansion with Intelligent Pruning | Proposed |
| ADR-032.2 | Implementation Quick Reference | Accepted |
| ADR-046 | Grounding-Aware Vocabulary Management | Proposed |
| ADR-047 | Probabilistic Vocabulary Categorization | Accepted |
| ADR-048 | Vocabulary Metadata as First-Class Graph | Accepted |
| ADR-052 | Vocabulary Expansion-Consolidation Cycle (The "Dreaming" Pattern) | Accepted |
| ADR-053 | Eager Vocabulary Categorization | Accepted |
| ADR-059 | LLM-Determined Relationship Direction Semantics | Proposed |
| ADR-065 | Vocabulary-Based Provenance Relationships | Accepted |
| ADR-077 | Vocabulary Explorers | Draft |
Interfaces
CLI, web, FUSE, MCP, visualization
| ADR | Title | Status |
|---|---|---|
| ADR-011 | CLI and Admin Tooling Separation | Accepted |
| ADR-013 | Unified TypeScript Client (CLI + MCP Server) | Accepted |
| ADR-019 | Type-Based Table Formatting System | Accepted |
| ADR-029 | CLI Theory of Operation - Hybrid Unix/Domain-Specific Design | Proposed |
| ADR-034 | Graph Visualization & Interactive Query Explorers | Proposed |
| ADR-035 | Explorer Methods, Uses, and Capabilities | Proposed |
| ADR-036 | Universal Visual Query Builder | Proposed |
| ADR-064 | Specialized Truth Convergence Visualizations | Proposed |
| ADR-067 | Web Application Workstation Architecture | Proposed |
| ADR-069 | Semantic FUSE Filesystem | Proposed |
| ADR-069.1 | FUSE Driver Implementation Specifics | Proposed |
| ADR-075 | Postmodern Theme System | Proposed |
| ADR-078 | Embedding Landscape Explorer | Accepted |
| ADR-085 | Document Explorer with Radial Concept Visualization | Proposed |
| ADR-700 | Ontology Explorer | Draft |
| ADR-701 | Vocabulary Administration Interface | Draft |
AI/Embeddings
Providers, extraction, convergence, prompts
| ADR | Title | Status |
|---|---|---|
| ADR-039 | Local Embedding Service with Hybrid Client/Server Architecture | Proposed |
| ADR-041 | AI Extraction Provider Configuration | Proposed |
| ADR-042 | Local LLM Inference for Concept Extraction | Accepted |
| ADR-043 | Single-Node Resource Management for Local Inference | Accepted |
| ADR-044 | Probabilistic Truth Convergence Through Contradiction Resolution | Proposed |
| ADR-045 | Unified Embedding Generation System | Proposed |
| ADR-049 | Rate Limiting and Per-Provider Concurrency Management | Accepted |
| ADR-058 | Polarity Axis Triangulation for Grounding Calculation | Accepted |
| ADR-068 | Source Text Embeddings for Grounding Truth Retrieval | Accepted |
| ADR-070 | Polarity Axis Analysis for Bidirectional Semantic Dimensions | Accepted |
Meta/Process
Documentation, workflow, access models, ADR system
| ADR | Title | Status |
|---|---|---|
| ADR-001 | Multi-Tier Agent Access Model | Proposed |
| ADR-002 | Node Fitness Scoring System | Proposed |
| ADR-003 | Semantic Tool Hint Networks | Proposed |
| ADR-004 | Pure Graph Design (Library Metaphor) | Proposed |
| ADR-005 | Source Text Tracking and Retrieval | Proposed |
| ADR-006 | Staging and Migration Workflows | Proposed |
| ADR-038 | Official Project Apparel Design Specifications | Proposed |
| ADR-087 | Documentation Strategy and Audience Framework | Draft |
| ADR-900 | ADR Numbering Domain System | Draft |