npm package: @noyrax/5d-database-plugin
Description: 5-dimensional database layer for documentation system with semantic brain integration. Provides SQLite databases for modules, symbols, dependencies, ADRs, and changes. Includes semantic search and MCP server integration for AI agents.
Latest version: 0.1.14-beta.16

# 5D Database Plugin + Semantic Brain

**Semantic Brain für LLM-Agenten** - Eine intelligente Wissensbasis, die es AI-Agenten ermöglicht, Code-Systeme zu verstehen, **OHNE dass sie diese vorher kennen müssen**.

VS Code Extension für 5-dimensionale Datenbank-Speicherung der Dokumentations-System-Daten mit semantischer Suche.

## ⚠️ WICHTIG: System-Kopplung

**Das Documentation System Plugin (Noyrax) und das 5D Database Plugin MÜSSEN gekoppelt werden - sie funktionieren nur gemeinsam!**

```
Noyrax (Documentation System) → generiert docs/ → 5D Database Plugin → SQLite-DBs → MCP-Server → LLM-Agenten
```

- **Noyrax** generiert die `docs/` Ordnerstruktur mit allen 5 Dimensionen
- **5D Database Plugin** liest `docs/` und speichert die Daten in SQLite-Datenbanken
- **MCP-Server** ermöglicht LLM-Agenten-Zugriff auf die Datenbanken

### Monorepo-Integration

In diesem Workspace sind beide Plugins als Monorepo integriert:
- `documentation-system-plugin/` - Noyrax Documentation System Plugin
- `5d-database-plugin/` - 5D Database Plugin
- `docs/` - Gemeinsam genutzte Dokumentation

Siehe `SETUP_NEW_PROJECT.md` für vollständigen Setup-Workflow.

## Übersicht

Das 5D Database Plugin speichert die 5 Dimensionen des Documentation System Plugins in separaten SQLite-Datenbanken:

- **X-Dimension (Modules)**: Modul-Dokumentation aus `docs/modules/*.md`
- **Y-Dimension (Symbols)**: Symbol-Index aus `docs/index/symbols.jsonl`
- **Z-Dimension (Dependencies)**: Dependency-Graph aus `docs/system/DEPENDENCY_GRAPH.md`
- **W-Dimension (ADRs)**: Architecture Decision Records aus `docs/adr/*.md`
- **T-Dimension (Changes)**: Change Reports aus `docs/system/CHANGE_REPORT.md`

## Features

- **5 separate SQLite-Datenbanken** - Eine pro Dimension für optimale Performance
- **Hash-basierte Änderungserkennung** - Inkrementelle Updates nur bei Änderungen
- **Cross-Dimension-Queries** - Verknüpfungen zwischen Dimensionen
- **MCP-Server Integration** - Systemweiter Zugriff via Model Context Protocol
- **VS Code UI** - Database Explorer und Status Bar Integration
- **Monorepo-Integration** - Noyrax und 5D Database Plugin im gleichen Workspace
- **Workflow-Orchestrierung** - Vollständiger Workflow (Generate Docs → Ingest → Embeddings)

## Installation

### Via npm (Recommended for CLI Tools)

```bash
npm install -g @noyrax/5d-database-plugin
```

**Available CLI Tools:**
- `noyrax-5d-database` - Ingest documentation
- `noyrax-5d-database-query` - Query database
- `noyrax-5d-database-tool` - Use MCP tools directly
- `noyrax-5d-database-search` - Semantic search
- `noyrax-5d-database-embedding` - Generate embeddings

**Example:**
```bash
# Ingest documentation
noyrax-5d-database ingest /path/to/workspace

# Query modules
noyrax-5d-database-query /path/to/workspace modules src/api/user-service.ts

# Semantic search
noyrax-5d-database-tool /path/to/workspace semantic_discovery "How does authentication work?" 5
```

### Via VS Code Extension

⚠️ **Voraussetzung: Documentation System Plugin (Noyrax) muss installiert sein und `docs/` generiert haben!**

1. **Documentation System Plugin (Noyrax) installieren** und `docs/` generieren
2. **5D Database Plugin installieren:**
   ```bash
   code --install-extension 5d-database-plugin-0.1.0.vsix
   ```
3. **Workspace öffnen** (muss `docs/` enthalten)
4. **Extension aktiviert sich automatisch** beim Start
5. **Ingestion ausführen:** `Ctrl+Shift+P` → "Ingest Documentation"

Siehe `SETUP_NEW_PROJECT.md` für vollständige Anleitung mit beiden Plugins.

## Verwendung

### Ingestion

Die Dokumentation wird automatisch beim ersten Start oder manuell via Command ingestiert:

- **Command**: `5d-database.ingest` - Ingestiert alle Dimensionen
- **CLI**: `node out/cli/ingest-cli.js <workspace-root> [--full]`
- **npm**: `noyrax-5d-database ingest <workspace-root> [--full]`

### CLI-Tools für direkten Zugriff

Für AI-Agenten und Entwickler stehen CLI-Tools für direkten Datenbank-Zugriff zur Verfügung:

- **Ingest-CLI**: `noyrax-5d-database ingest` - Vollständige Ingestion (5D + V-Dimension)
- **Embedding-CLI**: `noyrax-5d-database-embedding` - Embedding-Pipeline manuell ausführen (nur V-Dimension)
- **Query-CLI**: `noyrax-5d-database-query` - Datenbank-Queries (Modules, Symbols, Dependencies, ADRs, Changes)
- **Tool-CLI**: `noyrax-5d-database-tool` - MCP-Tools direkt nutzen (bootstrap, semantic_discovery, system_explanation, learning_path, cross_analysis, gap_analysis, architecture_mining)
- **Search-CLI**: `noyrax-5d-database-search` - Semantic Search über V-Dimension
- **MCP-Server**: `noyrax-5d-database-mcp` - MCP-Server für externe LLM-Agenten

**Hinweis:** Die Embedding-Pipeline wird automatisch bei der Ingestion ausgeführt, kann aber auch manuell via `noyrax-5d-database-embedding` ausgeführt werden (z.B. wenn ChromaDB nachträglich gestartet wurde).

### Environment Variables

Das System nutzt folgende Environment Variables (können in `.env` Datei oder als System-Environment-Variablen gesetzt werden):

- **`OPENAI_API_KEY`** (erforderlich für Embeddings):
  - API-Key für OpenAI (für Embedding-Generierung und optional Summarization)
  - Wird automatisch aus `.env` Datei geladen
  - Beispiel: `OPENAI_API_KEY=sk-...`

- **`EMBEDDING_STRATEGY`** (optional, default: `optimize`):
  - Strategie für große Module-Dokumentationen (>8000 Tokens)
  - Mögliche Werte:
    - `optimize` (default): Intelligente Kürzung - behält Struktur, entfernt Details
    - `hierarchical`: Nur Struktur (Header, Namen, Signaturen) - Details in Y-Dimension
    - `summarize`: LLM-basierte Summarization (erfordert `OPENAI_API_KEY`)
  - Beispiel: `EMBEDDING_STRATEGY=summarize`

**Token-Limit-Handling:**
- OpenAI text-embedding-3-small hat ein Context-Length-Limit von 8192 Tokens
- Große Module-Dokumentationen werden automatisch erkannt (>8000 Tokens)
- Die gewählte Strategie wird automatisch angewendet
- Bei Summarization-Fehlern: Automatischer Fallback auf Optimize-Strategie

Siehe `docs/adr/021-embedding-system-generator-pipeline.md` für Details zu den Strategien.

**Gap Analysis Tool:**

Das `gap_analysis` Tool identifiziert systematisch Dokumentationslücken:

```bash
# Finde Module mit vielen Dependencies aber ohne/wenigen ADRs
noyrax-5d-database-tool <workspace-root> gap_analysis

# Mit Parametern
noyrax-5d-database-tool <workspace-root> gap_analysis --min-deps 5 --limit 20
```

Das Tool analysiert alle Module, berechnet Gap-Scores basierend auf Dependency-Count und ADR-Count, und gibt priorisierte Empfehlungen zurück. Siehe `docs/adr/034-gap-analysis-tool.md` für Details.

**Architecture Mining Tool:**

Das `architecture_mining` Tool leitet rückwirkend Architektur-Entscheidungen aus dem Code ab:

```bash
# Analysiere gesamtes System für Architektur-Patterns
noyrax-5d-database-tool <workspace-root> architecture_mining

# Analysiere spezifische Datei
noyrax-5d-database-tool <workspace-root> architecture_mining <filePath>
```

Das Tool nutzt die **5D-Datenbanken (Semantic Brain)** - nicht den Code direkt:
- **X-Dimension (Modules)**: Modul-Pfade, Dateinamen, Struktur
- **Y-Dimension (Symbols)**: Symbol-Namen, Klassen-Namen
- **Z-Dimension (Dependencies)**: Dependency-Graph
- **W-Dimension (ADRs)**: Bestehende ADRs zum Vergleich

Es erkennt Patterns wie Repository Pattern, API Layer, Builder Pattern, Factory Pattern, Service Layer und Layered Architecture. Siehe `docs/adr/035-architecture-mining-tool.md` für Details.

Siehe `MCP_SERVER_SETUP.md` für detaillierte Anleitung.

### MCP-Server (für LLM-Agenten)

Der MCP-Server bietet Zugriff auf alle Dimensionen via Model Context Protocol:

- **Resources**: `db://modules/{pluginId}`, `db://symbols/{pluginId}`, etc.
- **Tools**: 
  - `bootstrap` - First-Contact für Agenten ohne Vorwissen
  - `semantic_discovery` - Semantic Search in natürlicher Sprache
  - `system_explanation` - System-Übersicht, Entry Points, Architecture ADRs
  - `learning_path` - Geführte Lernpfade
  - `query_modules`, `query_symbols`, `query_dependencies`, `cross_analysis`
  - `gap_analysis` - Systematische Dokumentationslücken-Identifikation
  - `architecture_mining` - Rückwirkende Architektur-Entscheidungs-Erkennung aus Code
  - `generate_documentation` - Dokumentation generieren (Noyrax-Integration)
  - `check_docs_status` - Prüft ob docs/ existiert und aktuell ist

Siehe `MCP_SERVER_SETUP.md` für detaillierte Setup-Anleitung für LLM-Agenten.

### Database Explorer

Der Database Explorer zeigt alle 5 Dimensionen in der VS Code Sidebar:
- X: Modules
- Y: Symbols
- Z: Dependencies
- W: ADRs
- T: Changes

## Architektur

### Datenbank-Schema

Jede Dimension hat ihre eigene SQLite-Datenbank:
- `{workspace}/.database-plugin/modules.db` - X-Dimension
- `{workspace}/.database-plugin/symbols.db` - Y-Dimension
- `{workspace}/.database-plugin/dependencies.db` - Z-Dimension
- `{workspace}/.database-plugin/adrs.db` - W-Dimension
- `{workspace}/.database-plugin/changes.db` - T-Dimension
- `{workspace}/.database-plugin/vectors.db` - V-Dimension (Embeddings für Semantic Search)

### ID-Strategie

- **Internal IDs**: UUID v4 für Primärschlüssel
- **External IDs**: Fachliche IDs (symbol_id, adr_number, etc.)
- **ID-Mapping**: Tabellen für External-ID → Internal-ID Übersetzung

### Cross-Dimension-Referenzen

- Symbol-ID → Modul-ID Auflösung
- ADR → File-Path Verknüpfungen
- Dependency → Symbol Evidence Links

## Entwicklung

### Build

```bash
npm install
npm run compile
```

### Tests

```bash
npm test
npm run test:coverage
```

### Projektstruktur

```
5d-database-plugin/
├── src/
│   ├── api/              # API-Layer pro Dimension
│   ├── core/             # Multi-DB-Manager, Migration, ID-Mapper
│   ├── ingestors/        # Ingestion-Module pro Dimension
│   ├── models/           # TypeScript-Modelle
│   ├── repositories/     # Repository-Layer pro Dimension
│   ├── services/         # Cross-Dimension-Services
│   ├── validators/       # Konsistenz- und Integritäts-Validierung
│   ├── mcp/              # MCP-Server Integration
│   ├── ui/               # VS Code UI-Komponenten
│   └── extension.ts      # Extension Entry Point
├── schemas/sqlite/       # SQL-Schema-Migrationen
└── __tests__/            # Tests
```

## Phase 2: Semantic Brain - ✅ IMPLEMENTIERT

Das Semantic Brain ist vollständig implementiert und bietet:

- ✅ **V-Dimension** - Vektordatenbank für Embeddings
- ✅ **Embedding System** - OpenAI-Integration für Embedding-Generierung
- ✅ **Semantic Search API** - Vector Similarity Search über alle Dimensionen
- ✅ **Importance Scoring** - PageRank und Betweenness Centrality
- ✅ **Navigation Metadata** - Entry Points und Clusters
- ✅ **Self-Understanding** - Bootstrap API, Self-Explanation API, Learning Paths
- ✅ **Deterministic Context Builder** - Strukturierter Kontext ohne KI-Generierung
- ✅ **MCP-Server Integration** - Vollständige Integration für LLM-Agenten

### Vektordatenbank

- **SQLite VSS** für macOS/Linux (native Extension)
- **ChromaDB** für Windows (HTTP-Server)
- **Platform-Detection** - Automatische Auswahl der besten Lösung
- **Graceful Degradation** - Fallback auf Cosine Similarity wenn keine verfügbar

Siehe `CHROMADB_SETUP.md` für ChromaDB-Konfiguration.

## Kernfunktionalität für LLM-Agenten

1. **Semantic Discovery**: Natürliche Sprache → relevante Code-Entitäten finden
2. **Deterministic Navigation**: Strukturierter Kontext aus Fakten (keine KI-Halluzinationen)
3. **Self-Understanding**: System erklärt sich selbst (Bootstrap API, Self-Explanation API)
4. **Learning Paths**: Geführte Pfade zum Erlernen des Systems
5. **Cross-Dimension Intelligence**: Verknüpfungen zwischen allen Dimensionen

## Dokumentation

- **`SETUP_NEW_PROJECT.md`** - Vollständiger Setup-Workflow für neue Projekte (gekoppelt mit Noyrax)
- **`MCP_SERVER_SETUP.md`** - MCP-Server-Konfiguration für LLM-Agenten (Claude Desktop, etc.)
- **`QUICK_START.md`** - Schnellstart-Anleitung für Entwickler
- **`CHROMADB_SETUP.md`** - ChromaDB-Installation und -Konfiguration (Windows)
- **`docs/adr/`** - Architecture Decision Records (32 ADRs dokumentieren alle Entscheidungen)

## Strategische Vision

- **[`../../VISION.md`](../../VISION.md)** - Vision: Autonome KI-gesteuerte Softwareentwicklung
- **[`../../INNOVATION_ANALYSIS.md`](../../INNOVATION_ANALYSIS.md)** - Innovations-Analyse: Was macht das System besonders?
- **[`../../PROBLEM_SOLUTION_MAPPING.md`](../../PROBLEM_SOLUTION_MAPPING.md)** - Problem-Lösung-Mapping
- **[`../../AI_CODING_IMPLICATIONS.md`](../../AI_CODING_IMPLICATIONS.md)** - AI-Coding Implications
- **[`../../BUSINESS_IMPACT.md`](../../BUSINESS_IMPACT.md)** - Business Impact: Kosteneinsparungen
- **[`../../QUALITY_IMPROVEMENT.md`](../../QUALITY_IMPROVEMENT.md)** - Qualitätsverbesserung
- **[`../../DOMAIN_TRANSFERABILITY.md`](../../DOMAIN_TRANSFERABILITY.md)** - Domänen-Transferfähigkeit

## License

MIT