agentic-sdlc 1.0.0 → 1.5.0

package/.agent/knowledge-base/architecture/KB-2026-01-01-003-neo4j-graph-database-skills.md

@@ -0,0 +1,1146 @@
+# Neo4j Graph Database Skills & Best Practices
+
+**Date:** 2026-01-01  
+**Sprint:** N/A (Research & Documentation)  
+**Category:** Architecture / Database  
+**Related Issues:** N/A  
+**Prepared By:** @SA
+
+---
+
+## Executive Summary
+
+This knowledge base entry provides comprehensive guidance on Neo4j graph database skills, with a focus on **Neo4j AuraDB (Cloud)** deployment. It covers Cypher query language, performance optimization, data modeling best practices, and cloud-specific configurations.
+
+**Key Topics Covered:**
+- Neo4j AuraDB Cloud setup and connection
+- Cypher query language essentials
+- Performance optimization and indexing
+- Data modeling patterns
+- Cloud-specific best practices
+- Security and access control
+- Integration with applications
+
+**Target Audience:** Developers, architects, and data engineers working with Neo4j Cloud (AuraDB)
+
+---
+
+## 1. Neo4j AuraDB Cloud Overview
+
+### 1.1 What is Neo4j AuraDB?
+
+Neo4j AuraDB is the fully managed cloud service for Neo4j graph database. It provides:
+- **Fully Managed:** No infrastructure management required
+- **Auto-Scaling:** Automatically scales based on workload
+- **Global Deployment:** Deploy in multiple regions worldwide
+- **High Availability:** Built-in redundancy and failover
+- **Automatic Backups:** Daily automated backups
+- **Security:** Enterprise-grade security by default
+- **Pay-as-you-go:** Flexible pricing based on usage
+
+### 1.2 AuraDB Tiers
+
+**AuraDB Free:**
+- Perfect for learning and development
+- Limited to 200k nodes + relationships
+- 1 database instance
+- Community support
+
+**AuraDB Professional:**
+- Production workloads
+- Scalable compute and storage
+- 24/7 support
+- Advanced monitoring
+- Custom backup schedules
+
+**AuraDB Enterprise:**
+- Mission-critical applications
+- Multi-region deployment
+- Advanced security features
+- Dedicated support
+- SLA guarantees
+
+### 1.3 Connecting to Neo4j AuraDB
+
+**Connection Details:**
+```
+URI: neo4j+s://xxxxx.databases.neo4j.io
+Port: 7687 (Bolt protocol with TLS)
+Username: neo4j
+Password: [your-generated-password]
+```
+
+**Connection String Format:**
+```
+neo4j+s://[instance-id].databases.neo4j.io
+```
+
+**Important Notes:**
+- ✅ Always use `neo4j+s://` (secure Bolt protocol)
+- ✅ Save your password immediately (shown only once)
+- ✅ Use connection URI from AuraDB console
+- ❌ Don't use `bolt://` (not secure)
+- ❌ Don't use `localhost` (cloud-based)
+
+---
+
+## 2. Getting Started with Neo4j AuraDB
+
+### 2.1 Creating Your First AuraDB Instance
+
+**Steps:**
+1. Sign up at https://neo4j.com/cloud/aura/
+2. Click "Create Database"
+3. Choose tier (Free for learning)
+4. Select region (closest to your users)
+5. Save connection credentials
+6. Wait for provisioning (1-2 minutes)
+
+### 2.2 Accessing AuraDB
+
+**Option 1: Neo4j Browser (Web UI)**
+- Click "Open" in AuraDB console
+- Use web-based query interface
+- Visual graph exploration
+- Query history and favorites
+
+**Option 2: Neo4j Desktop**
+- Add remote connection
+- Enter AuraDB connection details
+- Use desktop tools and plugins
+
+**Option 3: Application Drivers**
+- Python, JavaScript, Java, .NET, Go
+- Connect programmatically
+- Production applications
+
+### 2.3 First Query in AuraDB
+
+```cypher
+-- Test connection
+RETURN "Hello Neo4j AuraDB!" AS message;
+
+-- Check database info
+CALL dbms.components() YIELD name, versions, edition;
+
+-- View database statistics
+CALL apoc.meta.stats() YIELD nodeCount, relCount, labelCount;
+```
+
+---
+
+## 3. Cypher Query Language Essentials
+
+---
+
+## 4. Performance Optimization Strategies
+
+### 4.1 Indexing Best Practices
+
+**Index Types:**
+- **Unique Indexes:** Ensure property uniqueness across the graph
+- **Non-Unique Indexes:** Allow multiple nodes with same property value
+- **Composite Indexes:** Combine multiple properties for complex queries
+- **Full-Text Indexes:** Enable advanced text search capabilities
+- **Spatial Indexes:** Optimize geospatial queries
+
+**When to Create Indexes:**
+- Properties frequently used in WHERE clauses
+- Properties used in MATCH patterns
+- Properties used for lookups and searches
+- Unique identifiers (email, user ID, etc.)
+
+**Index Creation Examples:**
+```cypher
+-- Create simple index
+CREATE INDEX FOR (n:Person) ON (n.name);
+
+-- Create unique constraint (automatically creates index)
+CREATE CONSTRAINT FOR (n:Person) REQUIRE n.email IS UNIQUE;
+
+-- Create composite index
+CREATE INDEX FOR (n:Person) ON (n.firstName, n.lastName);
+
+-- Create full-text index
+CALL db.index.fulltext.createNodeIndex(
+  "personFullText",
+  ["Person"],
+  ["name", "bio", "description"]
+);
+
+-- List all indexes
+CALL db.indexes();
+
+-- Drop index
+DROP INDEX FOR (n:Person) ON (n.name);
+```
+
+**Indexing Guidelines:**
+- ✅ Index properties used in frequent queries
+- ✅ Use composite indexes for multi-property queries
+- ✅ Monitor index usage and performance
+- ❌ Don't over-index (impacts write performance)
+- ❌ Avoid indexing rarely-queried properties
+- ⚠️ Balance read vs write performance
+
+**Performance Impact:**
+- Indexed queries: 10-1000x faster
+- Write operations: Slightly slower with more indexes
+- Storage: Indexes consume additional disk space
+
+---
+
+### 4.2 Query Optimization Techniques
+
+**Use EXPLAIN and PROFILE:**
+```cypher
+-- View execution plan without running
+EXPLAIN 
+MATCH (n:Person {name: "Alice"}) 
+RETURN n;
+
+-- Run query and see detailed metrics
+PROFILE 
+MATCH (n:Person {name: "Alice"}) 
+RETURN n;
+```
+
+**Optimization Strategies:**
+
+1. **Specify Node Labels:**
+```cypher
+-- ❌ Slow: Scans all nodes
+MATCH (n {name: "Alice"}) RETURN n;
+
+-- ✅ Fast: Uses label index
+MATCH (n:Person {name: "Alice"}) RETURN n;
+```
+
+2. **Limit Result Sets:**
+```cypher
+-- Always use LIMIT for large datasets
+MATCH (n:Person) 
+RETURN n 
+ORDER BY n.created DESC 
+LIMIT 100;
+```
+
+3. **Use Parameters:**
+```cypher
+-- ✅ Allows query plan caching
+MATCH (n:Person {name: $name}) 
+RETURN n;
+```
+
+4. **Avoid Cartesian Products:**
+```cypher
+-- ❌ Creates cartesian product
+MATCH (a:Person), (b:Company) 
+RETURN a, b;
+
+-- ✅ Use relationships
+MATCH (a:Person)-[:WORKS_AT]->(b:Company) 
+RETURN a, b;
+```
+
+5. **Optimize Path Queries:**
+```cypher
+-- ❌ Unbounded (dangerous on large graphs)
+MATCH p=(a)-[*]->(b) RETURN p;
+
+-- ✅ Bounded depth
+MATCH p=(a)-[*1..3]->(b) RETURN p;
+
+-- ✅ Use shortestPath for efficiency
+MATCH p=shortestPath((a)-[*]-(b)) RETURN p;
+```
+
+**Query Performance Checklist:**
+- [ ] Node labels specified in MATCH clauses
+- [ ] Indexes created on frequently queried properties
+- [ ] LIMIT used on large result sets
+- [ ] Parameters used instead of literals
+- [ ] Path queries have depth limits
+- [ ] Cartesian products avoided
+- [ ] Query profiled and optimized
+
+---
+
+### 4.3 Memory and Configuration Tuning
+
+**Key Configuration Parameters:**
+
+```properties
+# Memory Settings (neo4j.conf)
+dbms.memory.heap.initial_size=2G
+dbms.memory.heap.max_size=4G
+dbms.memory.pagecache.size=4G
+
+# Query Timeout
+dbms.transaction.timeout=60s
+
+# Connection Pool
+dbms.connector.bolt.thread_pool_min_size=5
+dbms.connector.bolt.thread_pool_max_size=400
+```
+
+**Memory Allocation Guidelines:**
+- **Heap Memory:** 1-4GB for most applications
+- **Page Cache:** As much as possible (stores graph data)
+- **OS Memory:** Leave 1-2GB for operating system
+
+**Rule of Thumb:**
+- Page Cache ≈ Size of graph data on disk
+- Heap ≈ 1-4GB (rarely needs more)
+- Total RAM = Heap + Page Cache + OS (1-2GB)
+
+---
+
+## 5. Advanced Neo4j Techniques
+
+### 5.1 Full-Text Search
+
+**Creating Full-Text Indexes:**
+```cypher
+-- Create full-text index on multiple properties
+CALL db.index.fulltext.createNodeIndex(
+  "articleSearch",
+  ["Article", "BlogPost"],
+  ["title", "content", "summary"]
+);
+
+-- Query full-text index
+CALL db.index.fulltext.queryNodes(
+  "articleSearch", 
+  "graph database"
+) YIELD node, score
+RETURN node.title, score
+ORDER BY score DESC
+LIMIT 10;
+
+-- Advanced search with operators
+CALL db.index.fulltext.queryNodes(
+  "articleSearch",
+  "graph AND (database OR neo4j)"
+) YIELD node, score
+RETURN node;
+```
+
+**Full-Text Search Features:**
+- Fuzzy matching
+- Boolean operators (AND, OR, NOT)
+- Phrase queries
+- Wildcard searches
+- Relevance scoring
+
+---
+
+### 5.2 Spatial Indexing and Geospatial Queries
+
+**Creating Spatial Data:**
+```cypher
+-- Create nodes with point properties
+CREATE (store:Store {
+  name: "Downtown Store",
+  location: point({latitude: 40.7128, longitude: -74.0060})
+});
+
+-- Create spatial index
+CREATE INDEX FOR (n:Store) ON (n.location);
+```
+
+**Geospatial Queries:**
+```cypher
+-- Find stores within radius (meters)
+MATCH (s:Store)
+WHERE distance(
+  s.location, 
+  point({latitude: 40.7128, longitude: -74.0060})
+) < 5000
+RETURN s.name, 
+       distance(s.location, point({latitude: 40.7128, longitude: -74.0060})) AS distanceMeters
+ORDER BY distanceMeters;
+
+-- Find nearest stores
+MATCH (s:Store)
+WITH s, distance(
+  s.location,
+  point({latitude: 40.7128, longitude: -74.0060})
+) AS dist
+ORDER BY dist
+LIMIT 5
+RETURN s.name, dist;
+
+-- Bounding box query
+MATCH (s:Store)
+WHERE s.location.latitude > 40.0 
+  AND s.location.latitude < 41.0
+  AND s.location.longitude > -75.0
+  AND s.location.longitude < -73.0
+RETURN s;
+```
+
+---
+
+### 5.3 Graph Algorithms
+
+**Common Graph Algorithms:**
+
+1. **Shortest Path:**
+```cypher
+MATCH p=shortestPath(
+  (a:Person {name: "Alice"})-[:KNOWS*]-(b:Person {name: "Bob"})
+)
+RETURN p, length(p) AS pathLength;
+```
+
+2. **All Shortest Paths:**
+```cypher
+MATCH p=allShortestPaths(
+  (a:Person {name: "Alice"})-[:KNOWS*]-(b:Person {name: "Bob"})
+)
+RETURN p;
+```
+
+3. **PageRank (requires Graph Data Science library):**
+```cypher
+CALL gds.pageRank.stream('myGraph')
+YIELD nodeId, score
+RETURN gds.util.asNode(nodeId).name AS name, score
+ORDER BY score DESC
+LIMIT 10;
+```
+
+4. **Community Detection:**
+```cypher
+CALL gds.louvain.stream('myGraph')
+YIELD nodeId, communityId
+RETURN communityId, collect(gds.util.asNode(nodeId).name) AS members;
+```
+
+---
+
+## 6. Data Modeling Best Practices
+
+### 6.1 Graph Modeling Principles
+
+**Key Principles:**
+1. **Model relationships explicitly** - Don't hide relationships in properties
+2. **Use meaningful relationship types** - Be specific (WORKS_AT vs RELATED_TO)
+3. **Denormalize when beneficial** - Duplicate data for query performance
+4. **Model for queries** - Design based on how you'll query the data
+5. **Use labels for categorization** - Multiple labels are fine
+
+**Good vs Bad Modeling:**
+
+❌ **Bad: Relationships as Properties**
+```cypher
+CREATE (p:Person {
+  name: "Alice",
+  friendIds: ["123", "456", "789"]
+});
+```
+
+✅ **Good: Explicit Relationships**
+```cypher
+CREATE (alice:Person {name: "Alice"})
+CREATE (bob:Person {name: "Bob"})
+CREATE (alice)-[:FRIENDS_WITH {since: 2020}]->(bob);
+```
+
+---
+
+### 6.2 Common Graph Patterns
+
+**1. Hierarchical Structures:**
+```cypher
+-- Organization hierarchy
+CREATE (ceo:Person:Executive {name: "CEO"})
+CREATE (vp1:Person:Executive {name: "VP Sales"})
+CREATE (vp2:Person:Executive {name: "VP Engineering"})
+CREATE (mgr1:Person:Manager {name: "Sales Manager"})
+CREATE (emp1:Person:Employee {name: "Sales Rep"})
+
+CREATE (ceo)-[:MANAGES]->(vp1)
+CREATE (ceo)-[:MANAGES]->(vp2)
+CREATE (vp1)-[:MANAGES]->(mgr1)
+CREATE (mgr1)-[:MANAGES]->(emp1);
+```
+
+**2. Time-Based Relationships:**
+```cypher
+-- Track relationship history
+CREATE (alice:Person {name: "Alice"})
+CREATE (company1:Company {name: "Acme Corp"})
+CREATE (company2:Company {name: "Tech Inc"})
+
+CREATE (alice)-[:WORKED_AT {
+  from: date("2018-01-01"),
+  to: date("2020-12-31"),
+  position: "Developer"
+}]->(company1)
+
+CREATE (alice)-[:WORKS_AT {
+  from: date("2021-01-01"),
+  position: "Senior Developer"
+}]->(company2);
+```
+
+**3. Recommendation Patterns:**
+```cypher
+-- Collaborative filtering
+MATCH (user:User {id: $userId})-[:PURCHASED]->(product:Product)
+      <-[:PURCHASED]-(other:User)-[:PURCHASED]->(recommendation:Product)
+WHERE NOT (user)-[:PURCHASED]->(recommendation)
+RETURN recommendation.name, COUNT(*) AS score
+ORDER BY score DESC
+LIMIT 10;
+```
+
+**4. Access Control Patterns:**
+```cypher
+-- Role-based access
+CREATE (user:User {name: "Alice"})
+CREATE (role:Role {name: "Admin"})
+CREATE (resource:Resource {name: "Database"})
+CREATE (permission:Permission {name: "READ"})
+
+CREATE (user)-[:HAS_ROLE]->(role)
+CREATE (role)-[:HAS_PERMISSION]->(permission)
+CREATE (permission)-[:ON_RESOURCE]->(resource);
+
+-- Check access
+MATCH (user:User {name: "Alice"})-[:HAS_ROLE]->(:Role)
+      -[:HAS_PERMISSION]->(p:Permission {name: "READ"})
+      -[:ON_RESOURCE]->(r:Resource {name: "Database"})
+RETURN COUNT(p) > 0 AS hasAccess;
+```
+
+---
+
+## 7. Common Use Cases
+
+### 7.1 Social Networks
+- Friend recommendations
+- Mutual connections
+- Influence analysis
+- Community detection
+- Content recommendations
+
+### 7.2 Fraud Detection
+- Pattern recognition
+- Anomaly detection
+- Network analysis
+- Transaction tracking
+- Risk scoring
+
+### 7.3 Knowledge Graphs
+- Entity relationships
+- Semantic search
+- Question answering
+- Data integration
+- Ontology management
+
+### 7.4 Recommendation Engines
+- Collaborative filtering
+- Content-based recommendations
+- Hybrid approaches
+- Real-time personalization
+
+### 7.5 Network and IT Operations
+- Dependency mapping
+- Impact analysis
+- Root cause analysis
+- Capacity planning
+- Service topology
+
+---
+
+## 8. Integration and Drivers
+
+### 8.1 Official Drivers for AuraDB
+
+**Python (neo4j driver):**
+```python
+from neo4j import GraphDatabase
+
+class AuraDBConnection:
+    def __init__(self, uri, user, password):
+        # Use neo4j+s:// for AuraDB secure connection
+        self.driver = GraphDatabase.driver(
+            uri, 
+            auth=(user, password),
+            encrypted=True  # Required for AuraDB
+        )
+    
+    def close(self):
+        self.driver.close()
+    
+    def query(self, cypher, parameters=None):
+        with self.driver.session() as session:
+            result = session.run(cypher, parameters)
+            return [record.data() for record in result]
+
+# Usage with AuraDB
+conn = AuraDBConnection(
+    "neo4j+s://xxxxx.databases.neo4j.io",
+    "neo4j",
+    "your-password"
+)
+results = conn.query("MATCH (n:Person) RETURN n.name LIMIT 10")
+conn.close()
+```
+
+**JavaScript (neo4j-driver):**
+```javascript
+const neo4j = require('neo4j-driver');
+
+// AuraDB connection with secure protocol
+const driver = neo4j.driver(
+  'neo4j+s://xxxxx.databases.neo4j.io',
+  neo4j.auth.basic('neo4j', 'your-password'),
+  { 
+    encrypted: 'ENCRYPTION_ON',
+    trust: 'TRUST_SYSTEM_CA_SIGNED_CERTIFICATES'
+  }
+);
+
+const session = driver.session({ database: 'neo4j' });
+
+async function runQuery() {
+  try {
+    const result = await session.run(
+      'MATCH (n:Person) RETURN n.name LIMIT 10'
+    );
+    
+    result.records.forEach(record => {
+      console.log(record.get('n.name'));
+    });
+  } finally {
+    await session.close();
+    await driver.close();
+  }
+}
+
+runQuery();
+```
+
+**Node.js with Environment Variables:**
+```javascript
+// .env file
+NEO4J_URI=neo4j+s://xxxxx.databases.neo4j.io
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=your-password
+
+// app.js
+require('dotenv').config();
+const neo4j = require('neo4j-driver');
+
+const driver = neo4j.driver(
+  process.env.NEO4J_URI,
+  neo4j.auth.basic(
+    process.env.NEO4J_USER,
+    process.env.NEO4J_PASSWORD
+  )
+);
+```
+
+**Java:**
+```java
+import org.neo4j.driver.*;
+
+public class AuraDBExample {
+    public static void main(String[] args) {
+        // AuraDB connection
+        Driver driver = GraphDatabase.driver(
+            "neo4j+s://xxxxx.databases.neo4j.io",
+            AuthTokens.basic("neo4j", "your-password"),
+            Config.builder()
+                .withEncryption()
+                .build()
+        );
+        
+        try (Session session = driver.session()) {
+            Result result = session.run(
+                "MATCH (n:Person) RETURN n.name LIMIT 10"
+            );
+            
+            while (result.hasNext()) {
+                Record record = result.next();
+                System.out.println(record.get("n.name").asString());
+            }
+        }
+        
+        driver.close();
+    }
+}
+```
+
+**Connection Best Practices for AuraDB:**
+- ✅ Always use `neo4j+s://` protocol
+- ✅ Enable encryption in driver config
+- ✅ Store credentials in environment variables
+- ✅ Use connection pooling (built-in)
+- ✅ Implement retry logic for transient errors
+- ✅ Close sessions and drivers properly
+- ❌ Don't hardcode credentials
+- ❌ Don't disable encryption
+
+---
+
+## 9. Neo4j AuraDB Cloud Operations
+
+### 9.1 AuraDB-Specific Features
+
+**Automatic Backups:**
+- Daily automated backups
+- 7-day retention (Professional)
+- 30-day retention (Enterprise)
+- Point-in-time recovery
+- No manual backup needed
+
+**Monitoring and Metrics:**
+```cypher
+-- Check database size
+CALL apoc.meta.stats() 
+YIELD nodeCount, relCount, labelCount, propertyKeyCount
+RETURN nodeCount, relCount, labelCount, propertyKeyCount;
+
+-- Monitor query performance
+CALL dbms.listQueries() 
+YIELD queryId, query, elapsedTimeMillis, status
+WHERE elapsedTimeMillis > 1000
+RETURN queryId, query, elapsedTimeMillis
+ORDER BY elapsedTimeMillis DESC;
+```
+
+**Scaling in AuraDB:**
+- **Vertical Scaling:** Upgrade instance size in console
+- **Storage:** Automatically expands as needed
+- **Compute:** Scale CPU/memory independently
+- **No Downtime:** Most scaling operations are online
+
+**AuraDB Console Features:**
+- Real-time metrics dashboard
+- Query performance monitoring
+- Connection management
+- Backup and restore
+- User management
+- Billing and usage
+
+---
+
+### 9.2 AuraDB Security Best Practices
+
+**Authentication:**
+```cypher
+-- Change default password immediately
+ALTER CURRENT USER SET PASSWORD FROM 'old-password' TO 'new-strong-password';
+
+-- Create additional users (Professional/Enterprise)
+CREATE USER analyst SET PASSWORD 'secure-password' CHANGE NOT REQUIRED;
+GRANT ROLE reader TO analyst;
+```
+
+**Network Security:**
+- All connections encrypted by default (TLS 1.2+)
+- IP allowlisting available (Enterprise)
+- VPC peering supported (Enterprise)
+- No public internet exposure option
+
+**Access Control:**
+```cypher
+-- Role-based access control
+CREATE ROLE dataScientist;
+GRANT MATCH {*} ON GRAPH neo4j TO dataScientist;
+GRANT READ {*} ON GRAPH neo4j TO dataScientist;
+
+-- Grant role to user
+GRANT ROLE dataScientist TO analyst;
+
+-- Revoke access
+REVOKE ROLE dataScientist FROM analyst;
+```
+
+**Security Checklist for AuraDB:**
+- [ ] Changed default password
+- [ ] Using strong, unique passwords
+- [ ] Credentials stored in secrets manager
+- [ ] Least privilege access implemented
+- [ ] Regular access audits
+- [ ] Monitor connection logs
+- [ ] Enable IP allowlisting (if available)
+- [ ] Use environment variables for credentials
+
+---
+
+### 9.3 Cost Optimization for AuraDB
+
+**Strategies to Reduce Costs:**
+
+1. **Right-Size Your Instance:**
+   - Start with smaller instance
+   - Monitor usage metrics
+   - Scale up only when needed
+
+2. **Optimize Queries:**
+   - Use indexes effectively
+   - Limit result sets
+   - Avoid expensive operations
+   - Profile and optimize slow queries
+
+3. **Data Management:**
+   - Archive old data
+   - Remove unused nodes/relationships
+   - Implement data retention policies
+
+4. **Development vs Production:**
+   - Use AuraDB Free for development
+   - Separate dev/staging/prod instances
+   - Pause non-production instances when not in use
+
+**Monitoring Costs:**
+```cypher
+-- Check database size (impacts storage costs)
+CALL apoc.meta.stats() YIELD nodeCount, relCount
+RETURN nodeCount, relCount,
+       (nodeCount + relCount) AS totalObjects;
+
+-- Identify large nodes (potential optimization)
+MATCH (n)
+WITH n, size(keys(n)) AS propCount
+WHERE propCount > 20
+RETURN labels(n), propCount, count(*) AS nodeCount
+ORDER BY propCount DESC
+LIMIT 10;
+```
+
+---
+
+## 10. AuraDB vs Self-Hosted Neo4j
+
+### Comparison Table
+
+| Feature | AuraDB Cloud | Self-Hosted |
+|---------|--------------|-------------|
+| **Setup Time** | Minutes | Hours/Days |
+| **Management** | Fully managed | Manual |
+| **Scaling** | Automatic | Manual |
+| **Backups** | Automatic | Manual setup |
+| **Security** | Built-in | Configure yourself |
+| **Updates** | Automatic | Manual |
+| **High Availability** | Built-in | Configure clustering |
+| **Cost** | Pay-as-you-go | Infrastructure + ops |
+| **Best For** | Most use cases | Specific requirements |
+
+**When to Use AuraDB:**
+- ✅ Fast time to market
+- ✅ Focus on application, not infrastructure
+- ✅ Variable workloads
+- ✅ Global deployment needed
+- ✅ Limited DevOps resources
+
+**When to Self-Host:**
+- ✅ Strict data residency requirements
+- ✅ Existing infrastructure investment
+- ✅ Very specific performance needs
+- ✅ Cost optimization at massive scale
+- ✅ Air-gapped environments
+
+---
+
+## 10. Security Best Practices
+
+### 10.1 Authentication and Authorization
+
+**User Management:**
+```cypher
+-- Create user
+CREATE USER alice SET PASSWORD 'securePassword' CHANGE REQUIRED;
+
+-- Grant roles
+GRANT ROLE reader TO alice;
+
+-- Custom role with specific permissions
+CREATE ROLE dataAnalyst;
+GRANT MATCH {*} ON GRAPH neo4j TO dataAnalyst;
+GRANT READ {*} ON GRAPH neo4j TO dataAnalyst;
+```
+
+**Security Checklist:**
+- [ ] Change default password immediately
+- [ ] Use strong passwords
+- [ ] Implement role-based access control
+- [ ] Enable SSL/TLS for connections
+- [ ] Restrict network access
+- [ ] Regular security audits
+- [ ] Monitor access logs
+- [ ] Keep Neo4j updated
+
+---
+
+## 11. Common Pitfalls and Solutions
+
+### 11.1 Performance Issues
+
+**Problem:** Slow queries
+**Solutions:**
+- Add indexes on frequently queried properties
+- Use PROFILE to identify bottlenecks
+- Limit path query depth
+- Specify node labels in MATCH clauses
+- Avoid cartesian products
+
+**Problem:** Out of memory errors
+**Solutions:**
+- Increase page cache size
+- Use LIMIT on large result sets
+- Process data in batches
+- Optimize query patterns
+- Add more RAM
+
+---
+
+### 11.2 Data Modeling Issues
+
+**Problem:** Relationships as properties
+**Solution:** Model relationships explicitly
+
+**Problem:** Over-connected nodes (super nodes)
+**Solution:** 
+- Use intermediate nodes
+- Implement time-based partitioning
+- Consider alternative modeling
+
+**Problem:** Unclear relationship types
+**Solution:** Use specific, meaningful relationship names
+
+---
+
+## 12. Learning Resources
+
+### 12.1 Official Resources
+- **Neo4j Documentation:** https://neo4j.com/docs/
+- **GraphAcademy:** Free online courses and certifications
+- **Neo4j Community Forum:** Active community support
+- **Neo4j Blog:** Latest updates and best practices
+
+### 12.2 Practice Exercises
+
+**Beginner:**
+1. Create a simple social network
+2. Model a product catalog
+3. Build a movie recommendation system
+
+**Intermediate:**
+4. Implement access control system
+5. Create fraud detection patterns
+6. Build knowledge graph
+
+**Advanced:**
+7. Optimize large-scale queries
+8. Implement custom graph algorithms
+9. Design multi-tenant architecture
+
+---
+
+## 13. Quick Reference Cheat Sheet
+
+### Essential Cypher Commands
+
+```cypher
+-- CREATE
+CREATE (n:Label {property: "value"})
+CREATE (a)-[:RELATIONSHIP]->(b)
+
+-- MATCH
+MATCH (n:Label) RETURN n
+MATCH (a)-[r:REL]->(b) RETURN a, r, b
+
+-- WHERE
+MATCH (n:Person) WHERE n.age > 30 RETURN n
+
+-- SET
+MATCH (n:Person {name: "Alice"}) SET n.age = 31
+
+-- DELETE
+MATCH (n:Person {name: "Alice"}) DELETE n
+MATCH (n:Person {name: "Alice"}) DETACH DELETE n
+
+-- MERGE (create if not exists)
+MERGE (n:Person {email: "alice@example.com"})
+ON CREATE SET n.created = timestamp()
+ON MATCH SET n.lastSeen = timestamp()
+
+-- AGGREGATION
+MATCH (n:Person) RETURN COUNT(n)
+MATCH (n:Person) RETURN AVG(n.age)
+MATCH (n:Person) RETURN COLLECT(n.name)
+
+-- ORDERING & LIMITING
+MATCH (n:Person) RETURN n ORDER BY n.age DESC LIMIT 10
+
+-- PATH QUERIES
+MATCH p=(a)-[*1..3]->(b) RETURN p
+MATCH p=shortestPath((a)-[*]-(b)) RETURN p
+```
+
+---
+
+## 14. Key Takeaways
+
+### For Developers
+1. **Think in Graphs:** Model relationships explicitly
+2. **Index Strategically:** Index frequently queried properties
+3. **Profile Queries:** Use EXPLAIN and PROFILE for optimization
+4. **Limit Depth:** Always bound path queries
+5. **Use Parameters:** Enable query plan caching
+
+### For Architects
+1. **Model for Queries:** Design based on access patterns
+2. **Plan for Scale:** Consider indexing and partitioning early
+3. **Security First:** Implement RBAC from the start
+4. **Monitor Performance:** Track query performance metrics
+5. **Backup Strategy:** Implement automated backups
+
+### For Data Scientists
+1. **Leverage Algorithms:** Use Graph Data Science library
+2. **Explore Patterns:** Graph queries reveal hidden insights
+3. **Visualize Results:** Use Neo4j Browser for exploration
+4. **Iterate Quickly:** Graph model is flexible
+5. **Combine Approaches:** Mix graph with traditional analytics
+
+---
+
+## 15. Next Steps
+
+### Immediate Actions
+1. Install Neo4j Desktop or create Aura account
+2. Complete GraphAcademy beginner course
+3. Practice with sample datasets
+4. Build a small project
+5. Join Neo4j community forum
+
+### Short-Term Goals (1-3 Months)
+1. Master Cypher query language
+2. Understand indexing strategies
+3. Learn data modeling patterns
+4. Explore Graph Data Science library
+5. Build production-ready application
+
+### Long-Term Goals (3-12 Months)
+1. Achieve Neo4j certification
+2. Contribute to community
+3. Optimize large-scale deployments
+4. Implement advanced algorithms
+5. Mentor others in graph databases
+
+---
+
+## Related Knowledge Base Entries
+- See: `.agent/knowledge-base/architecture/` for architecture patterns
+- See: `tools/neo4j/README.md` for Neo4j tools documentation
+- See: `docs/architecture/NEO4J-LEARNING-QUERIES.md` for query examples
+- See: `docs/architecture/BRAIN.md` for brain architecture integration
+- See: `docs/sprints/SPRINT-NEO4J-BRAIN.md` for Neo4j brain sprint details
+
+## Integration with Agentic SDLC
+
+### Auto-Sync Knowledge Base to Neo4j
+
+**Location:** `tools/neo4j/sync_skills_to_neo4j.py`
+
+Automatically sync knowledge base entries to Neo4j Cloud:
+
+```bash
+# Sync all KB entries
+python tools/neo4j/sync_skills_to_neo4j.py
+
+# Dry run (preview without syncing)
+python tools/neo4j/sync_skills_to_neo4j.py --dry-run
+
+# Show statistics only
+python tools/neo4j/sync_skills_to_neo4j.py --stats-only
+```
+
+### Query Skills from Neo4j
+
+**Location:** `tools/neo4j/query_skills_neo4j.py`
+
+Query and explore the skills knowledge graph:
+
+```bash
+# List all skills
+python tools/neo4j/query_skills_neo4j.py --all-skills
+
+# Skills for specific technology
+python tools/neo4j/query_skills_neo4j.py --tech "Neo4j"
+
+# Related skills
+python tools/neo4j/query_skills_neo4j.py --skill "Graph Databases"
+
+# Learning path for category
+python tools/neo4j/query_skills_neo4j.py --learning-path "Architecture"
+```
+
+### Automated Workflow
+
+**Hook Configuration:** `.kiro/hooks/auto-research-hook.json`
+
+Set up automatic Neo4j sync when KB entries are created:
+
+```json
+{
+  "name": "kb-auto-sync-neo4j",
+  "trigger": "on_file_save",
+  "condition": "file_path contains '.agent/knowledge-base/KB-'",
+  "action": {
+    "type": "command",
+    "command": "python tools/neo4j/sync_skills_to_neo4j.py"
+  }
+}
+```
+
+### Research Agent Integration
+
+**Location:** `tools/research/research_agent.py`
+
+The research agent can query Neo4j for related knowledge:
+
+```bash
+# Research with Neo4j integration
+python tools/research/research_agent.py --task "Neo4j optimization" --type architecture
+```
+
+The agent will:
+1. Search file-based knowledge base
+2. Query Neo4j knowledge graph (if configured)
+3. Find related technologies and skills
+4. Generate comprehensive research report
+
+**Configuration:** Add Neo4j credentials to `.env`:
+
+```bash
+NEO4J_URI=neo4j+s://xxxxx.databases.neo4j.io
+NEO4J_USERNAME=neo4j
+NEO4J_PASSWORD=your-password
+NEO4J_DATABASE=neo4j
+```
+
+---
+
+## References and Sources
+
+**Research Sources:**
+- [Neo4j Official Documentation](https://neo4j.com/docs/)
+- [House of Graphs - Neo4j Indexing](https://houseofgraphs.com/blog/neo4j-indexing/)
+- [Shep Bryan's Cypher Cheatsheet](https://www.shepbryan.com/blog/neo4j-cypher-cheatsheet)
+- Neo4j GraphAcademy courses
+- Neo4j community best practices
+
+**Content was rephrased for compliance with licensing restrictions**
+
+---
+
+#neo4j #graph-database #cypher #architecture #knowledge-base #database #performance-optimization
+