# Development Artifact Modeling in Neo4j
## Overview
This document details how to model software development artifacts as nodes and relationships in Neo4j using the MCP Neo4j Memory Server. The goal is to create a rich, interconnected graph that captures the full context of project development.
## Node Types and Properties
### CodeFile Node
Represents source code files, configuration files, and documentation.
**Properties:**
- `name`: File name (e.g., "UserService.ts")
- `path`: Full file path (e.g., "src/services/UserService.ts")
- `memoryType`: "codefile"
- `language`: Programming language or file type
- `size`: File size in bytes
- `complexity`: Cyclomatic complexity (for code files)
- `lastModified`: Timestamp of last modification
**Metadata:**
```json
{
"extension": "ts",
"framework": "Node.js",
"purpose": "user management service",
"testCoverage": 85,
"linesOfCode": 234
}
```
**Observations:**
- Code review comments
- Performance notes
- Refactoring decisions
- Bug fix implementations
### Function Node
Represents methods, functions, classes, or components within code files.
**Properties:**
- `name`: Function/method name
- `memoryType`: "function"
- `signature`: Function signature
- `returnType`: Return type
- `visibility`: public/private/protected
- `complexity`: Cyclomatic complexity
**Metadata:**
```json
{
"parameters": ["userId: string", "options: UserOptions"],
"async": true,
"pure": false,
"sideEffects": ["database write", "logging"],
"testCount": 12
}
```
### Feature Node
Represents user stories, requirements, or product capabilities.
**Properties:**
- `name`: Feature name (e.g., "User Authentication")
- `memoryType`: "feature"
- `status`: "planned|in-progress|complete|deprecated"
- `priority`: "critical|high|medium|low"
- `effort`: Story points or estimated hours
**Metadata:**
```json
{
"epic": "User Management",
"acceptanceCriteria": ["Users can log in", "Sessions persist"],
"stakeholder": "product-team",
"businessValue": "Enable user accounts"
}
```
### Bug Node
Represents defects, issues, or problems to resolve.
**Properties:**
- `name`: Bug title
- `memoryType`: "bug"
- `severity`: "critical|high|medium|low"
- `status`: "open|in-progress|resolved|closed"
- `reproducible`: boolean
- `impact`: User impact description
**Metadata:**
```json
{
"reporter": "jane.doe",
"environment": "production",
"steps": ["Login", "Navigate to profile", "Click save"],
"expected": "Profile saves successfully",
"actual": "500 error returned"
}
```
### Decision Node
Represents architectural choices, design decisions, or trade-offs.
**Properties:**
- `name`: Decision title
- `memoryType`: "decision"
- `category`: "architecture|design|technology|process"
- `impact`: "project|module|function"
- `reversible`: boolean
**Metadata:**
```json
{
"alternatives": ["PostgreSQL", "MongoDB", "DynamoDB"],
"chosen": "PostgreSQL",
"rationale": "ACID compliance required",
"tradeoffs": ["Less horizontal scaling", "Better consistency"],
"stakeholders": ["tech-lead", "dba-team"]
}
```
### Commit Node
Represents version control commits.
**Properties:**
- `name`: Commit hash (short)
- `memoryType`: "commit"
- `hash`: Full commit hash
- `message`: Commit message
- `timestamp`: Commit timestamp
**Metadata:**
```json
{
"author": "john.smith",
"branch": "feature/user-auth",
"filesChanged": 5,
"linesAdded": 156,
"linesDeleted": 23,
"reviewers": ["jane.doe", "tech-lead"]
}
```
### Task Node
Represents work items, todos, or development activities.
**Properties:**
- `name`: Task description
- `memoryType`: "task"
- `status`: "todo|in-progress|review|done"
- `effort`: Estimated hours or story points
- `deadline`: Due date if applicable
**Metadata:**
```json
{
"assignee": "john.smith",
"sprint": "Sprint 23",
"labels": ["backend", "authentication"],
"blockers": ["database schema approval"],
"subtasks": 3
}
```
### Person Node
Represents developers, stakeholders, or contributors.
**Properties:**
- `name`: Person's name
- `memoryType`: "person"
- `role`: "developer|architect|product-manager|tester"
- `team`: Team name
- `active`: boolean
**Metadata:**
```json
{
"email": "john.smith@company.com",
"expertise": ["TypeScript", "React", "PostgreSQL"],
"timezone": "EST",
"startDate": "2023-01-15"
}
```
### Technology Node
Represents tools, frameworks, libraries, or platforms.
**Properties:**
- `name`: Technology name
- `memoryType`: "technology"
- `category`: "language|framework|library|tool|platform"
- `version`: Version in use
- `status`: "active|deprecated|evaluating"
**Metadata:**
```json
{
"purpose": "web framework",
"license": "MIT",
"maintainer": "Vercel",
"alternatives": ["Express", "Koa", "Fastify"],
"adoptionReason": "better developer experience"
}
```
### Environment Node
Represents deployment environments or configurations.
**Properties:**
- `name`: Environment name (e.g., "production", "staging")
- `memoryType`: "environment"
- `region`: Geographic region
- `status`: "active|maintenance|deprecated"
**Metadata:**
```json
{
"provider": "AWS",
"instances": ["EC2", "RDS", "ElastiCache"],
"deploymentMethod": "GitHub Actions",
"monitoring": ["CloudWatch", "DataDog"],
"backupSchedule": "daily"
}
```
## Relationship Types and Use Cases
### IMPLEMENTS Relationship
**Usage:** Links features to their implementing code or functions to features.
**Examples:**
- `(Feature:UserAuth)-[IMPLEMENTS]->(CodeFile:auth.service.ts)`
- `(Function:validatePassword)-[IMPLEMENTS]->(Feature:PasswordValidation)`
**Properties:**
```json
{
"completeness": 0.95,
"quality": "good",
"reviewStatus": "approved",
"implementedAt": "2024-03-15T10:30:00Z"
}
```
### DEPENDS_ON Relationship
**Usage:** Represents dependencies between artifacts.
**Examples:**
- `(CodeFile:UserService)-[DEPENDS_ON]->(Technology:PostgreSQL)`
- `(Function:hashPassword)-[DEPENDS_ON]->(Function:generateSalt)`
**Properties:**
```json
{
"type": "hard|soft",
"optional": false,
"version": "^14.0.0",
"reason": "data persistence layer"
}
```
### FIXES Relationship
**Usage:** Links solutions to problems they resolve.
**Examples:**
- `(Commit:a1b2c3d)-[FIXES]->(Bug:login-timeout)`
- `(CodeFile:auth-fix.ts)-[FIXES]->(Bug:session-leak)`
**Properties:**
```json
{
"verification": "tested|manual|automated",
"regressionRisk": "low",
"fixedAt": "2024-03-20T14:15:00Z",
"tester": "jane.doe"
}
```
### INFLUENCES Relationship
**Usage:** Represents how decisions or people affect other artifacts.
**Examples:**
- `(Decision:microservices-arch)-[INFLUENCES]->(Feature:UserService)`
- `(Person:tech-lead)-[INFLUENCES]->(Decision:database-choice)`
**Properties:**
```json
{
"strength": 0.8,
"type": "positive|negative|neutral",
"reason": "architectural alignment",
"duration": "long-term"
}
```
### CONTAINS Relationship
**Usage:** Hierarchical containment relationships.
**Examples:**
- `(CodeFile:UserService.ts)-[CONTAINS]->(Function:createUser)`
- `(Feature:UserMgmt)-[CONTAINS]->(Task:implement-auth)`
**Properties:**
```json
{
"order": 3,
"visibility": "public",
"importance": "core",
"extractable": true
}
```
### ASSIGNED_TO Relationship
**Usage:** Links work items to responsible people.
**Examples:**
- `(Task:fix-login-bug)-[ASSIGNED_TO]->(Person:john.smith)`
- `(Bug:memory-leak)-[ASSIGNED_TO]->(Person:senior-dev)`
**Properties:**
```json
{
"assignedAt": "2024-03-15T09:00:00Z",
"workload": 0.5,
"skillMatch": "high",
"deadline": "2024-03-25T17:00:00Z"
}
```
### CREATED_BY Relationship
**Usage:** Tracks authorship and creation responsibility.
**Examples:**
- `(CodeFile:utils.ts)-[CREATED_BY]->(Person:jane.doe)`
- `(Decision:use-typescript)-[CREATED_BY]->(Person:tech-lead)`
**Properties:**
```json
{
"createdAt": "2024-03-10T11:30:00Z",
"confidence": "high",
"experience": "expert",
"context": "greenfield project"
}
```
## Advanced Relationship Patterns
### Multi-hop Queries
Find all code files affected by a decision:
```cypher
MATCH (d:Decision)-[*2..4]->(cf:CodeFile)
WHERE d.name = "Switch to TypeScript"
RETURN cf.name, cf.path
```
### Temporal Analysis
Track feature evolution over time:
```cypher
MATCH (f:Feature)-[r:IMPLEMENTS]-(c:CodeFile)
WHERE f.name = "User Authentication"
RETURN c.name, r.implementedAt
ORDER BY r.implementedAt
```
### Impact Analysis
Find all artifacts influenced by a person:
```cypher
MATCH (p:Person)-[INFLUENCES*1..3]->(artifact)
WHERE p.name = "Tech Lead"
RETURN DISTINCT labels(artifact)[0] as type,
count(*) as count
```
## Best Practices
### Node Creation
1. Use descriptive, unique names
2. Include rich metadata for context
3. Add observations as they occur
4. Maintain consistent property naming
### Relationship Modeling
1. Use specific relationship types over generic ones
2. Include relationship properties for context
3. Consider bidirectional relationships when appropriate
4. Maintain temporal information
### Query Optimization
1. Use node labels and property indexes
2. Limit traversal depth in complex queries
3. Use parameterized queries for security
4. Consider query performance impact
### Evolution Management
1. Archive deprecated nodes rather than deleting
2. Update relationship properties as context changes
3. Add observations for major changes
4. Maintain referential integrity
This modeling approach creates a rich, queryable representation of project development that enables sophisticated analysis and AI-assisted development support.