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