Add template (#463)

docs/tech-specs/ARCHITECTURE_PRINCIPLES.md

@@ -1,106 +0,0 @@
-# Knowledge Graph Architecture Foundations
-
-## Foundation 1: Subject-Predicate-Object (SPO) Graph Model
-**Decision**: Adopt SPO/RDF as the core knowledge representation model
-
-**Rationale**:
-- Provides maximum flexibility and interoperability with existing graph technologies
-- Enables seamless translation to other graph query languages (e.g., SPO → Cypher, but not vice versa)
-- Creates a foundation that "unlocks a lot" of downstream capabilities
-- Supports both node-to-node relationships (SPO) and node-to-literal relationships (RDF)
-
-**Implementation**: 
-- Core data structure: `node → edge → {node | literal}`
-- Maintain compatibility with RDF standards while supporting extended SPO operations
-
-## Foundation 2: LLM-Native Knowledge Graph Integration
-**Decision**: Optimize knowledge graph structure and operations for LLM interaction
-
-**Rationale**:
-- Primary use case involves LLMs interfacing with knowledge graphs
-- Graph technology choices must prioritize LLM compatibility over other considerations
-- Enables natural language processing workflows that leverage structured knowledge
-
-**Implementation**:
-- Design graph schemas that LLMs can effectively reason about
-- Optimize for common LLM interaction patterns
-
-## Foundation 3: Embedding-Based Graph Navigation
-**Decision**: Implement direct mapping from natural language queries to graph nodes via embeddings
-
-**Rationale**:
-- Enables the simplest possible path from NLP query to graph navigation
-- Avoids complex intermediate query generation steps
-- Provides efficient semantic search capabilities within the graph structure
-
-**Implementation**:
-- `NLP Query → Graph Embeddings → Graph Nodes`
-- Maintain embedding representations for all graph entities
-- Support direct semantic similarity matching for query resolution
-
-## Foundation 4: Distributed Entity Resolution with Deterministic Identifiers
-**Decision**: Support parallel knowledge extraction with deterministic entity identification (80% rule)
-
-**Rationale**:
-- **Ideal**: Single-process extraction with complete state visibility enables perfect entity resolution
-- **Reality**: Scalability requirements demand parallel processing capabilities
-- **Compromise**: Design for deterministic entity identification across distributed processes
-
-**Implementation**:
-- Develop mechanisms for generating consistent, unique identifiers across different knowledge extractors
-- Same entity mentioned in different processes must resolve to the same identifier
-- Acknowledge that ~20% of edge cases may require alternative processing models
-- Design fallback mechanisms for complex entity resolution scenarios
-
-## Foundation 5: Event-Driven Architecture with Publish-Subscribe
-**Decision**: Implement pub-sub messaging system for system coordination
-
-**Rationale**:
-- Enables loose coupling between knowledge extraction, storage, and query components
-- Supports real-time updates and notifications across the system
-- Facilitates scalable, distributed processing workflows
-
-**Implementation**:
-- Message-driven coordination between system components
-- Event streams for knowledge updates, extraction completion, and query results
-
-## Foundation 6: Reentrant Agent Communication
-**Decision**: Support reentrant pub-sub operations for agent-based processing
-
-**Rationale**:
-- Enables sophisticated agent workflows where agents can trigger and respond to each other
-- Supports complex, multi-step knowledge processing pipelines
-- Allows for recursive and iterative processing patterns
-
-**Implementation**:
-- Pub-sub system must handle reentrant calls safely
-- Agent coordination mechanisms that prevent infinite loops
-- Support for agent workflow orchestration
-
-## Foundation 7: Columnar Data Store Integration
-**Decision**: Ensure query compatibility with columnar storage systems
-
-**Rationale**:
-- Enables efficient analytical queries over large knowledge datasets
-- Supports business intelligence and reporting use cases
-- Bridges graph-based knowledge representation with traditional analytical workflows
-
-**Implementation**:
-- Query translation layer: Graph queries → Columnar queries
-- Hybrid storage strategy supporting both graph operations and analytical workloads
-- Maintain query performance across both paradigms
-
----
-
-## Architecture Principles Summary
-
-1. **Flexibility First**: SPO/RDF model provides maximum adaptability
-2. **LLM Optimization**: All design decisions consider LLM interaction requirements
-3. **Semantic Efficiency**: Direct embedding-to-node mapping for optimal query performance
-4. **Pragmatic Scalability**: Balance perfect accuracy with practical distributed processing
-5. **Event-Driven Coordination**: Pub-sub enables loose coupling and scalability
-6. **Agent-Friendly**: Support complex, multi-agent processing workflows
-7. **Analytical Compatibility**: Bridge graph and columnar paradigms for comprehensive querying
-
-These foundations establish a knowledge graph architecture that balances theoretical rigor with practical scalability requirements, optimized for LLM integration and distributed processing.
-