Navegador

navegador / docs / architecture / graph-schema.md
Source Rendered
Blame History Raw 134 lines
1
# Graph Schema
2
3
## Node labels
4
5
### Code layer
6
7
| Label | Properties | Description |
8
|---|---|---|
9
| `Repository` | `name`, `path`, `url`, `ingested_at` | Top-level repo node |
10
| `File` | `path`, `language`, `lines`, `size` | Source file |
11
| `Module` | `name`, `file`, `path` | Python module or TS namespace |
12
| `Class` | `name`, `file`, `line`, `end_line`, `docstring`, `is_abstract` | Class definition |
13
| `Function` | `name`, `file`, `line`, `end_line`, `signature`, `docstring`, `is_async` | Top-level function |
14
| `Method` | `name`, `file`, `line`, `end_line`, `signature`, `docstring`, `is_async`, `is_classmethod`, `is_staticmethod` | Class method |
15
| `Variable` | `name`, `file`, `line`, `type_annotation` | Module-level variable |
16
| `Import` | `name`, `alias`, `file`, `line`, `from_module` | Import statement |
17
| `Decorator` | `name`, `expression`, `file`, `line` | Decorator applied to function/class |
18
19
### Knowledge layer
20
21
| Label | Properties | Description |
22
|---|---|---|
23
| `Domain` | `name`, `description`, `created_at` | Top-level grouping for concepts, rules, decisions |
24
| `Concept` | `name`, `description`, `domain`, `status`, `created_at` | Named domain concept or design pattern |
25
| `Rule` | `name`, `description`, `domain`, `severity`, `rationale`, `created_at` | Enforceable constraint; severity: `info`, `warning`, `critical` |
26
| `Decision` | `name`, `description`, `domain`, `rationale`, `alternatives`, `date`, `status`, `created_at` | Architectural decision record; status: `proposed`, `accepted`, `deprecated`, `superseded` |
27
| `WikiPage` | `title`, `content`, `url`, `source`, `updated_at` | Wiki page or document |
28
| `Person` | `name`, `email`, `role`, `team`, `created_at` | Team member or contributor |
29
30
---
31
32
## Edge types
33
34
| Edge | From | To | Meaning |
35
|---|---|---|---|
36
| `CONTAINS` | Repository, File, Module, Class | File, Class, Function, Method, Variable, Import | Structural containment |
37
| `DEFINES` | File, Class | Class, Function, Method | Definition site |
38
| `IMPORTS` | File | Import | File imports a module or symbol |
39
| `DEPENDS_ON` | File, Module | File, Module | Module-level dependency |
40
| `CALLS` | Function, Method | Function, Method | Direct function call (static analysis) |
41
| `REFERENCES` | Function, Method, File | Variable, Class, Function | Name reference (not a call) |
42
| `INHERITS` | Class | Class | Class inherits from parent |
43
| `IMPLEMENTS` | Class, Function | Concept | Code implements a concept or interface |
44
| `DECORATES` | Decorator | Function, Method, Class | Decorator applied to target |
45
| `BELONGS_TO` | Concept, Rule, Decision, Person | Domain | Membership in a domain |
46
| `RELATED_TO` | Any | Any | General semantic relationship |
47
| `GOVERNS` | Rule | Function, Method, Class, File | Rule applies to code node |
48
| `DOCUMENTS` | WikiPage | Concept, Function, Class, File | Documentation relationship |
49
| `ANNOTATES` | Concept, Rule | Function, Method, Class, File, Module | Knowledge node annotates code node |
50
| `ASSIGNED_TO` | Rule, Decision | Person | Work item or decision assigned to person |
51
| `DECIDED_BY` | Decision | Person | Decision was made by person |
52
| `TESTS` | Function, Method | Function, Method, Class | Test function exercises a source function or class |
53
| `COUPLED_WITH` | File, Module | File, Module | Files that change together frequently (from churn analysis) |
54
| `OWNS` | Person | File, Module, Class | Ownership from CODEOWNERS or annotation |
55
56
---
57
58
## Schema diagram
59
60
```mermaid
61
graph LR
62
subgraph Knowledge["Knowledge Layer"]
63
Domain
64
Concept
65
Rule
66
Decision
67
WikiPage
68
Person
69
end
70
71
subgraph Code["Code Layer"]
72
Repository
73
File
74
Module
75
Class
76
Function
77
Method
78
Decorator
79
Import
80
Variable
81
end
82
83
Repository -->|CONTAINS| File
84
File -->|CONTAINS| Class
85
File -->|CONTAINS| Function
86
File -->|IMPORTS| Import
87
Class -->|DEFINES| Method
88
Function -->|CALLS| Function
89
Method -->|CALLS| Function
90
Method -->|CALLS| Method
91
Class -->|INHERITS| Class
92
Decorator -->|DECORATES| Function
93
Decorator -->|DECORATES| Class
94
Decorator -->|DECORATES| Method
95
96
Domain -->|"(inverse) BELONGS_TO"| Concept
97
Domain -->|"(inverse) BELONGS_TO"| Rule
98
Domain -->|"(inverse) BELONGS_TO"| Decision
99
WikiPage -->|DOCUMENTS| Concept
100
WikiPage -->|DOCUMENTS| Function
101
102
Rule -->|GOVERNS| Function
103
Rule -->|GOVERNS| Class
104
Concept -->|ANNOTATES| Function
105
Concept -->|ANNOTATES| Class
106
Class -->|IMPLEMENTS| Concept
107
Decision -->|DECIDED_BY| Person
108
Rule -->|ASSIGNED_TO| Person
109
Function -->|TESTS| Function
110
Function -->|TESTS| Class
111
File -->|COUPLED_WITH| File
112
Person -->|OWNS| File
113
```
114
115
---
116
117
## Code vs knowledge layer distinction
118
119
The two layers have different **lifecycle** and **provenance**:
120
121
| Dimension | Code layer | Knowledge layer |
122
|---|---|---|
123
| Source | tree-sitter AST parsing | Manual curation, wiki, Planopticon |
124
| Refresh | On every `navegador ingest` | On demand (`navegador add`, `wiki ingest`, `planopticon ingest`) |
125
| Change rate | Fast (changes with every commit) | Slow (changes with design decisions) |
126
| Authorship | Derived from code | Human or meeting-authored |
127
| Queryability | Names, signatures, call graphs | Domain semantics, rationale, history |
128
129
Cross-layer edges (`ANNOTATES`, `GOVERNS`, `IMPLEMENTS`, `DOCUMENTS`) are the join points between the two layers. They are created explicitly by humans via `navegador annotate` or inferred during wiki/Planopticon ingestion.
130
131
Analysis edges (`TESTS`, `COUPLED_WITH`) are created by analysis commands (`navegador testmap`, `navegador churn`) and are derived rather than curated. They are refreshed whenever those commands are re-run.
132
133
`OWNS` edges are populated from CODEOWNERS file parsing (`navegador codeowners`) and from explicit `navegador annotate --owner` assignments.
134

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button