# Specification: Data Model (Graph + Vector)

To support the scenarios (Impact Analysis, Compliance Tracing), we need a rigid schema for the Graph (Neo4j) while keeping flexibility in the Vector payload (Qdrant).

## 1. Unified Identity
Every entity has a globally unique ID (URN) used across both databases.
**Format:** `urn:<source>:<type>:<path_or_id>`
*   `urn:github:repo:owner/name`
*   `urn:github:pr:owner/name/102`
*   `urn:code:file:owner/name:src/utils.ts`
*   `urn:code:function:owner/name:src/utils.ts:validateUser`

---

## 2. Neo4j Graph Schema (The Structure)

### Nodes (Labels)
| Label | Properties | Description |
| :--- | :--- | :--- |
| `Repository` | `name`, `owner`, `url`, `language` | A git repository. |
| `PR` | `number`, `title`, `author`, `state`, `merged_at` | A Pull Request. |
| `Issue` | `number`, `title`, `state` | A GitHub/Jira Issue. |
| `File` | `path`, `extension`, `sha` | A file in the codebase. |
| `CodeBlock` | `name`, `type` (func/class), `start_line` | A specific symbol (Parsed from AST). |
| `User` | `handle`, `email` | A developer or author. |

### Relationships (Edges)
| Relationship | From | To | Description |
| :--- | :--- | :--- | :--- |
| `CONTAINS` | `Repository` | `File` | File belongs to Repo. |
| `DEFINES` | `File` | `CodeBlock` | File contains function/class. |
| `CALLS` | `CodeBlock` | `CodeBlock` | Function A calls Function B. |
| `IMPORTS` | `File` | `File` | File A imports File B. |
| `MODIFIED_BY` | `PR` | `File` | PR touched this file. |
| `LINKED_TO` | `PR` | `Issue` | PR fixes or references Issue. |
| `AUTHORED` | `User` | `PR` / `Commit` | User created the work. |

---

## 3. Qdrant Vector Schema (The Semantics)

### Collection: `codebase`
Stores chunks of code and documentation.

**Payload:**
```json
{
  "urn": "urn:code:file:owner/name:src/utils.ts",
  "text": "def validate_session(token): ...",
  "metadata": {
    "repo": "owner/name",
    "language": "python",
    "last_modified": "2023-10-27"
  },
  "relations": {
    "pr_urns": ["urn:github:pr:owner/name/102"]  // Fast lookup back to graph
  }
}
```

### Collection: `work_items`
Stores semantic content of PRs, Issues, and architectural decisions.

**Payload:**
```json
{
  "urn": "urn:github:pr:owner/name/102",
  "text": "Fix login timeout by updating Intercom SDK...",
  "metadata": {
    "author": "matchdav",
    "state": "merged"
  }
}
```

---

## 4. Graph Expansion Logic
How to handle the "Compliance Auditor" scenario (Variable -> Class -> Field PII check):

**Query:** `MATCH (v:CodeBlock {name: "user_obj"})-[:TYPE_OF]->(c:Class)-[:HAS_FIELD]->(f:Field) RETURN f`
*   *Requirement:* The ingestion pipeline needs deeper semantic analysis (AST parsing) to link variables to their types.
*   *Phase 1 Implementation:* Regex-based "Best Guess" linking.
*   *Phase 2 Implementation:* LSIF (Language Server Index Format) ingestion for precise type resolution.
