Die vollständige Referenz: 13 Node-Typen, 26 Edge-Typen, Edge-Gewichte, Layer-Schema und Tour-Schema.
Jeder Knoten im Knowledge Graph hat einen Typ, der bestimmt, was er repräsentiert. Die 13 Typen decken sowohl Code-Artefakte als auch konzeptuelle und infrastrukturelle Elemente ab:
# 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"]
}
}
Pflichtfelder: id (eindeutig, normalisiert), type (einer der 13 Typen), name (menschenlesbar), description (Freitext).
Optionale Felder: filePath (nur bei code-basierten Typen), metadata (typ-spezifische Zusatzdaten wie Sprache, LOC, Exports).
concept vs. module: Ein concept ist ein abstraktes Muster (z.B. "Authentication Flow"), ein module ist ein konkretes Code-Paket (z.B. src/auth/).
Edges beschreiben die Beziehungen zwischen Nodes. Sie sind gerichtet (Source → Target) und typisiert. Die 26 Typen sind in 7 Kategorien gruppiert:
| Kategorie | Edge-Typen | Beispiel |
|---|---|---|
| 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"]
}
}
Pflichtfelder: source (Node-ID), target (Node-ID), type (einer der 26 Typen), weight (0.0-1.0).
Richtung: Edges sind immer gerichtet. "A imports B" bedeutet: A ist die Source, B ist das Target. Die Richtung ist semantisch konsistent: Informationsfluss von Target zu Source.
Jeder Edge-Typ hat ein Standardgewicht, das die "Stärke" der Beziehung ausdrückt. Gewichte reichen von 0.1 (schwach) bis 1.0 (maximal). Sie werden beim Graph-Rendering für Kantendicke und Layout-Priorität verwendet:
| Edge-Typ | Gewicht | Visualisierung | Bedeutung |
|---|---|---|---|
| contains | 1.0 | Stärkste Beziehung: Parent enthält Child | |
| implements | 0.9 | Klasse implementiert Interface | |
| extends | 0.9 | Vererbung | |
| calls | 0.8 | Direkter Funktionsaufruf | |
| imports | 0.7 | Import/Require-Beziehung | |
| depends_on | 0.7 | Allgemeine Abhängigkeit | |
| reads/writes | 0.6 | Datenzugriff | |
| subscribes | 0.5 | Event-Subscription | |
| related_to | 0.3 | Semantische Ähnlichkeit | |
| documents | 0.2 | Dokumentationsreferenz |
Diese Gewichte sind Defaults. Der file-analyzer kann sie basierend auf dem Kontext anpassen — z.B. erhält ein calls-Edge zu einer Kernfunktion ein höheres Gewicht als ein calls-Edge zu einem Logging-Utility.
Layers gruppieren Nodes in Architektur-Schichten. Der architecture-analyzer erkennt typischerweise 3-8 Layers, abhängig von der Komplexität des Projekts:
# 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",
"file:src-styles-main-css"
]
},
{
"id": "layer-api",
"name": "API Layer",
"description": "Express routes, middleware, controllers",
"nodeIds": ["file:src-routes-auth-js", "..."]
},
{
"id": "layer-data",
"name": "Data Layer",
"description": "Database models, migrations, seeds",
"nodeIds": ["..."]
}
]
}
Felder: id (eindeutig, Präfix "layer-"), name (menschenlesbar), description (was diese Schicht enthält), nodeIds (Array aller Nodes in dieser Schicht).
Typische Layers: Frontend, API/Routes, Business Logic, Data Access, Database, Config/Infrastructure, Tests, Documentation.
Ein Node pro Layer: Jeder Node gehört zu genau einem Layer. Die Zuordnung erfolgt heuristisch durch den architecture-analyzer basierend auf Dateipfad, Imports und Typ.
Die Guided Tour definiert einen geordneten Pfad durch den Knowledge Graph — ideal für Einsteiger, die das Projekt systematisch verstehen wollen. Der tour-builder erstellt typischerweise 5-12 Stationen:
# Tour-Schema (JSON)
{
"guided_tour": [
{
"order": 1,
"title": "Einstiegspunkt: App-Setup",
"description": "Die App startet hier. index.js initialisiert Express, lädt Middleware und verbindet die Datenbank.",
"nodeIds": [
"file:src-index-js",
"file:src-config-db-js"
]
},
{
"order": 2,
"title": "Routing: Wer antwortet auf was?",
"description": "Die Route-Definitionen in routes/ bestimmen, welcher Controller auf welche URL reagiert.",
"nodeIds": ["file:src-routes-index-js"],
"languageLesson": "Express-Routing nutzt app.use() für Middleware und app.get()/post() für Endpoints. Der Router kann verschachtelt werden."
},
{
"order": 3,
"title": "Datenmodelle: Was wird gespeichert?",
"description": "Die Models definieren die Datenstruktur. Jedes Model entspricht einer Datenbank-Tabelle.",
"nodeIds": ["file:src-models-user-js", "file:src-models-post-js"]
}
]
}
Pflichtfelder: order (Reihenfolge, 1-basiert), title (Stationsname), description (Erklärung), nodeIds (welche Nodes diese Station zeigt).
Optional: languageLesson — ein kurzer Exkurs zu sprachspezifischen Konzepten (z.B. "Was ist ein Express-Router?"). Wird im Dashboard als ausklappbare Box angezeigt.
Reihenfolge-Logik: Der tour-builder startet beim Einstiegspunkt (main/index), folgt dann dem Datenfluss durch die Architektur-Layer und endet bei Infrastruktur/Config.
skill.md.