The complete reference: 13 node types, 26 edge types, edge weights, layer schema, and tour schema.
Every node in the Knowledge Graph has a type that determines what it represents. The 13 types cover code artifacts as well as conceptual and infrastructure elements:
# Node Schema (JSON)
{
"id": "file:src-auth-login-js",
"type": "file",
"name": "login.js",
"description": "Handles user authentication flow",
"filePath": "src/auth/login.js",
"metadata": {
"language": "javascript",
"linesOfCode": 142,
"exports": ["login", "logout", "refreshToken"]
}
}
Required fields: id (unique, normalized), type (one of 13 types), name (human-readable), description (free text).
Optional fields: filePath (only for code-based types), metadata (type-specific data like language, LOC, exports).
concept vs. module: A concept is an abstract pattern (e.g., "Authentication Flow"), a module is a concrete code package (e.g., src/auth/).
Edges describe relationships between nodes. They are directed (source to target) and typed. The 26 types are grouped into 7 categories:
| Category | Edge Types | Example |
|---|---|---|
| Structural | imports, exports, contains, implements | login.js imports auth-utils.js |
| Behavioral | calls, subscribes, emits, handles | handleLogin() calls validateToken() |
| Data Flow | reads, writes, transforms, pipes | api.js reads from config.json |
| Dependencies | depends_on, extends, uses, requires | UserService depends_on Database |
| Semantic | related_to, similar_to, replaces, documents | README documents ProjectOverview |
| Infrastructure | deploys_to, connects_to, monitors | app deploys_to kubernetes-cluster |
| Schema/Data | defines, validates, migrates, seeds | UserSchema defines users-table |
# Edge Schema (JSON)
{
"source": "file:src-auth-login-js",
"target": "file:src-utils-auth-utils-js",
"type": "imports",
"weight": 0.7,
"metadata": {
"importedSymbols": ["hashPassword", "verifyJWT"]
}
}
Required fields: source (node ID), target (node ID), type (one of 26 types), weight (0.0-1.0).
Direction: Edges are always directed. "A imports B" means: A is the source, B is the target. Direction is semantically consistent: information flows from target to source.
Each edge type has a default weight expressing the "strength" of the relationship. Weights range from 0.1 (weak) to 1.0 (maximum). They are used in graph rendering for edge thickness and layout priority:
| Edge Type | Weight | Visualization | Meaning |
|---|---|---|---|
| contains | 1.0 | Strongest: parent contains child | |
| implements | 0.9 | Class implements interface | |
| extends | 0.9 | Inheritance | |
| calls | 0.8 | Direct function call | |
| imports | 0.7 | Import/require relationship | |
| depends_on | 0.7 | General dependency | |
| reads/writes | 0.6 | Data access | |
| subscribes | 0.5 | Event subscription | |
| related_to | 0.3 | Semantic similarity | |
| documents | 0.2 | Documentation reference |
These weights are defaults. The file-analyzer can adjust them based on context — e.g., a calls edge to a core function gets a higher weight than a calls edge to a logging utility.
Layers group nodes into architecture tiers. The architecture-analyzer typically detects 3-8 layers depending on project complexity:
# Layer Schema (JSON)
{
"layers": [
{
"id": "layer-frontend",
"name": "Frontend",
"description": "React components, pages, styles",
"nodeIds": [
"file:src-components-app-jsx",
"file:src-pages-home-jsx"
]
},
{
"id": "layer-api",
"name": "API Layer",
"description": "Express routes, middleware, controllers",
"nodeIds": ["..."]
},
{
"id": "layer-data",
"name": "Data Layer",
"description": "Database models, migrations, seeds",
"nodeIds": ["..."]
}
]
}
Fields: id (unique, "layer-" prefix), name (human-readable), description (what this tier contains), nodeIds (array of all nodes in this tier).
Typical layers: Frontend, API/Routes, Business Logic, Data Access, Database, Config/Infrastructure, Tests, Documentation.
One node per layer: Each node belongs to exactly one layer. Assignment is heuristic, based on file path, imports, and type.
The guided tour defines an ordered path through the Knowledge Graph — ideal for newcomers who want to understand the project systematically. The tour-builder typically creates 5-12 stops:
# Tour Schema (JSON)
{
"guided_tour": [
{
"order": 1,
"title": "Entry Point: App Setup",
"description": "The app starts here. index.js initializes Express, loads middleware, and connects the database.",
"nodeIds": [
"file:src-index-js",
"file:src-config-db-js"
]
},
{
"order": 2,
"title": "Routing: Who Responds to What?",
"description": "Route definitions in routes/ determine which controller handles which URL.",
"nodeIds": ["file:src-routes-index-js"],
"languageLesson": "Express routing uses app.use() for middleware and app.get()/post() for endpoints. Routers can be nested."
}
]
}
Required: order (sequence, 1-based), title (stop name), description (explanation), nodeIds (which nodes this stop highlights).
Optional: languageLesson — a short excursion into language-specific concepts (e.g., "What is an Express Router?"). Displayed as an expandable box in the dashboard.
Order logic: The tour-builder starts at the entry point (main/index), follows data flow through architecture layers, and ends at infrastructure/config.
skill.md.