@lon-ask/dockit 0.1.0

package/apps/server/src/index.ts

@@ -0,0 +1,98 @@
+import express from 'express';
+import cors from 'cors';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getDb, initDb } from './infrastructure/persistence/sqlite/connection.js';
+import { SqliteEntryRepository } from './infrastructure/persistence/sqlite/SqliteEntryRepository.js';
+import { SqliteSourceRepository } from './infrastructure/persistence/sqlite/SqliteSourceRepository.js';
+import { SqliteBuildRepository } from './infrastructure/persistence/sqlite/SqliteBuildRepository.js';
+import { createSearchEngine } from './infrastructure/search/SearchEngineFactory.js';
+import { SearchUseCase } from './core/usecases/SearchUseCase.js';
+import { BuildUseCase } from './core/usecases/BuildUseCase.js';
+import { ConfigUseCase } from './core/usecases/ConfigUseCase.js';
+import { NotFoundError, ValidationError } from './core/domain/errors.js';
+import { ZipSourceProcessor } from './infrastructure/source-processors/ZipSourceProcessor.js';
+import { AntoraSourceProcessor } from './infrastructure/source-processors/AntoraSourceProcessor.js';
+import { AsciidocSourceProcessor } from './infrastructure/source-processors/AsciidocSourceProcessor.js';
+import { MavenSourceProcessor } from './infrastructure/source-processors/MavenSourceProcessor.js';
+import { GithubMarkdownSourceProcessor } from './infrastructure/source-processors/GithubMarkdownSourceProcessor.js';
+import { SourceCodeSourceProcessor } from './infrastructure/source-processors/SourceCodeSourceProcessor.js';
+import { DocumentNormalizer } from './infrastructure/source-processors/DocumentNormalizer.js';
+import { PathResolver } from './infrastructure/source-processors/PathResolver.js';
+import { GraphifyKnowledgeGraph } from './infrastructure/graph/GraphifyKnowledgeGraph.js';
+import { SqliteEntryReadModel } from './infrastructure/persistence/sqlite/SqliteEntryReadModel.js';
+import { createEntryRoutes } from './routes/entries.js';
+import { createSearchRoutes } from './routes/search.js';
+import { createBuildRoutes } from './routes/build.js';
+import { createSourceRoutes, createSourceFlatRoutes } from './routes/sources.js';
+import viewerRoutes from './routes/viewer.js';
+import { createGraphRoutes } from './routes/graph.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PORT = process.env.PORT || 3001;
+
+async function main() {
+  const app = express();
+  app.use(cors());
+  app.use(express.json());
+
+  const db = getDb();
+  const entryRepo = new SqliteEntryRepository(db);
+  const sourceRepo = new SqliteSourceRepository(db);
+  const buildRepo = new SqliteBuildRepository(db);
+  const entryReadModel = new SqliteEntryReadModel(db);
+  const searchEngine = await createSearchEngine(entryReadModel);
+
+  const configUseCase = new ConfigUseCase(entryRepo, sourceRepo);
+  const searchUseCase = new SearchUseCase(searchEngine);
+
+  const processors = [
+    new ZipSourceProcessor(),
+    new AntoraSourceProcessor(),
+    new AsciidocSourceProcessor(),
+    new MavenSourceProcessor(),
+    new GithubMarkdownSourceProcessor(),
+    new SourceCodeSourceProcessor(),
+  ];
+  const documentNormalizer = new DocumentNormalizer();
+  const pathResolver = new PathResolver();
+
+  const buildUseCase = new BuildUseCase(
+    buildRepo, sourceRepo, entryRepo, searchEngine,
+    processors, documentNormalizer, pathResolver,
+  );
+
+  app.use('/api/entries', createEntryRoutes(configUseCase));
+  app.use('/api/entries/:entryId/sources', createSourceRoutes(configUseCase));
+  app.use('/api/sources', createSourceFlatRoutes(configUseCase));
+  app.use('/api', createBuildRoutes(buildUseCase, configUseCase, buildRepo));
+  app.use('/api', createSearchRoutes(searchUseCase));
+  app.use('/api', createGraphRoutes(buildRepo, configUseCase));
+  app.use('/api', viewerRoutes);
+
+  // Global error handler — catches domain errors thrown by use cases
+  app.use((err: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
+    if (err instanceof NotFoundError) {
+      res.status(404).json({ error: err.message, code: err.code });
+      return;
+    }
+    if (err instanceof ValidationError) {
+      const body: Record<string, unknown> = { error: err.message, code: err.code };
+      if (err.field) body.field = err.field;
+      res.status(400).json(body);
+      return;
+    }
+    console.error('Unhandled error:', err);
+    const message = err instanceof Error ? err.message : 'Internal server error';
+    res.status(500).json({ error: message });
+  });
+
+  app.listen(PORT, () => {
+    console.log(`Dockit server running on http://localhost:${PORT}`);
+  });
+}
+
+main().catch((err) => {
+  console.error('Failed to start server:', err);
+  process.exit(1);
+});

package/apps/server/src/infrastructure/filesystem/FileSystemDocumentStore.ts

@@ -0,0 +1,27 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import type { IDocumentStore } from '../../core/ports/IDocumentStore.js';
+import { DATA_ROOT } from '../../services/paths.js';
+
+export class FileSystemDocumentStore implements IDocumentStore {
+  async getDocument(entryId: string, docPath: string): Promise<string> {
+    const resolved = path.resolve(DATA_ROOT, entryId, 'bundle', docPath);
+    const dataRoot = path.resolve(DATA_ROOT);
+    if (!resolved.startsWith(dataRoot)) {
+      throw new Error('Invalid document path');
+    }
+    if (!fs.existsSync(resolved)) {
+      throw new Error(`Document not found: ${docPath} for entry ${entryId}`);
+    }
+    return fs.readFileSync(resolved, 'utf-8');
+  }
+
+  async documentExists(entryId: string, docPath: string): Promise<boolean> {
+    const resolved = path.resolve(DATA_ROOT, entryId, 'bundle', docPath);
+    const dataRoot = path.resolve(DATA_ROOT);
+    if (!resolved.startsWith(dataRoot)) {
+      return false;
+    }
+    return fs.existsSync(resolved);
+  }
+}

package/apps/server/src/infrastructure/graph/GraphSearchDecorator.ts

@@ -0,0 +1,53 @@
+import type { ISearchEngine } from '../../core/ports/ISearchEngine.js';
+import type { IKnowledgeGraph } from '../../core/ports/IKnowledgeGraph.js';
+import type { SearchResult, GlobalSearchResult, HtmlFile, SearchEngineType } from '../../core/domain/types.js';
+
+export class GraphSearchDecorator implements ISearchEngine {
+  readonly capability: SearchEngineType;
+
+  constructor(
+    private readonly engine: ISearchEngine,
+    private readonly knowledgeGraph: IKnowledgeGraph,
+  ) {
+    this.capability = engine.capability;
+  }
+
+  async buildIndex(entryId: string, htmlFiles: HtmlFile[], log: (msg: string) => void): Promise<void> {
+    return this.engine.buildIndex(entryId, htmlFiles, log);
+  }
+
+  async search(entryId: string, query: string, limit = 10): Promise<SearchResult[]> {
+    const results = await this.engine.search(entryId, query, limit);
+    if (!this.knowledgeGraph.exists() || results.length === 0) return results;
+
+    const graphResult = this.knowledgeGraph.query(query);
+    if (graphResult.totalNodes === 0) return results;
+
+    const graphNames = new Set(graphResult.nodes.map((n) => n.name.toLowerCase()));
+    const scored = results.map((r) => {
+      let boost = 0;
+      const titleWords = r.title.toLowerCase().split(/\s+/);
+      const snippetWords = r.snippet.toLowerCase().split(/\s+/);
+      for (const word of titleWords) {
+        if (graphNames.has(word)) boost += 0.3;
+      }
+      for (const word of snippetWords) {
+        if (graphNames.has(word)) boost += 0.1;
+      }
+      return { ...r, _score: boost };
+    });
+
+    scored.sort((a, b) => (b._score || 0) - (a._score || 0));
+    return scored.slice(0, limit);
+  }
+
+  async globalSearch(query: string, limit = 20): Promise<GlobalSearchResult[]> {
+    return this.engine.globalSearch(query, limit);
+  }
+}
+
+declare module '../../core/domain/types.js' {
+  interface SearchResult {
+    _score?: number;
+  }
+}

package/apps/server/src/infrastructure/graph/GraphifyKnowledgeGraph.ts

@@ -0,0 +1,172 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { IKnowledgeGraph } from '../../core/ports/IKnowledgeGraph.js';
+import type {
+  GraphNode,
+  GraphEdge,
+  GraphMetadata,
+  GraphQueryResult,
+  GraphPathResult,
+  KnowledgeGraphData,
+} from '../../core/domain/knowledge-graph.js';
+
+export class GraphifyKnowledgeGraph implements IKnowledgeGraph {
+  private data: KnowledgeGraphData | null = null;
+  private adjacency: Map<string, Map<string, GraphEdge[]>> = new Map();
+
+  constructor(entryDir: string) {
+    const graphPath = path.join(entryDir, 'graph.json');
+    if (fs.existsSync(graphPath)) {
+      try {
+        const raw = JSON.parse(fs.readFileSync(graphPath, 'utf-8'));
+        this.data = this.normalizeGraphData(raw);
+        this.buildAdjacency();
+      } catch {
+        this.data = null;
+      }
+    }
+  }
+
+  private normalizeGraphData(raw: Record<string, unknown>): KnowledgeGraphData {
+    const rawNodes = (raw.nodes as Record<string, unknown>[]) || [];
+    const rawEdges = (raw.edges as Record<string, unknown>[]) || (raw.links as Record<string, unknown>[]) || [];
+    const meta = (raw.metadata as Record<string, unknown>) || {};
+
+    const nodes: GraphNode[] = rawNodes.map((n) => ({
+      id: n.id as string,
+      name: (n.name ?? n.label ?? n.norm_label ?? n.id) as string,
+      file: (n.file ?? n.source_file ?? '') as string,
+      type: (n.type ?? n.file_type ?? '') as string,
+      line: (n.line ?? 0) as number,
+      community: (n.community as number) ?? 0,
+    }));
+
+    const edges: GraphEdge[] = rawEdges.map((e) => ({
+      source: (e.source as string) ?? (e.source as any)?.id ?? '',
+      target: (e.target as string) ?? (e.target as any)?.id ?? '',
+      type: (e.type as string) ?? 'depends',
+      id: (e.id as string) ?? `${e.source}-${e.target}`,
+    }));
+
+    return {
+      nodes,
+      edges,
+      metadata: {
+        nodeCount: (meta.nodeCount as number) || nodes.length,
+        edgeCount: (meta.edgeCount as number) || edges.length,
+        communityCount: (meta.communityCount as number) || 0,
+        godNodes: (meta.godNodes as number) || 0,
+        languages: (meta.languages as string[]) || [],
+      },
+    };
+  }
+
+  private buildAdjacency(): void {
+    if (!this.data) return;
+    for (const node of this.data.nodes) {
+      this.adjacency.set(node.id, new Map());
+    }
+    for (const edge of this.data.edges) {
+      const srcMap = this.adjacency.get(edge.source);
+      if (srcMap) {
+        const existing = srcMap.get(edge.target) || [];
+        existing.push(edge);
+        srcMap.set(edge.target, existing);
+      }
+    }
+  }
+
+  exists(): boolean {
+    return this.data !== null && this.data.nodes.length > 0;
+  }
+
+  query(query: string, limit = 20): GraphQueryResult {
+    if (!this.data) return { nodes: [], edges: [], totalNodes: 0, totalEdges: 0 };
+
+    const q = query.toLowerCase();
+    const matchedNodes = this.data.nodes.filter(
+      (n) =>
+        (n.name || '').toLowerCase().includes(q) ||
+        (n.file || '').toLowerCase().includes(q) ||
+        (n.type || '').toLowerCase().includes(q),
+    );
+
+    const nodeIds = new Set(matchedNodes.map((n) => n.id));
+    const matchedEdges = this.data.edges.filter(
+      (e) => nodeIds.has(e.source) || nodeIds.has(e.target),
+    );
+
+    return {
+      nodes: matchedNodes.slice(0, limit),
+      edges: matchedEdges.slice(0, limit * 2),
+      totalNodes: matchedNodes.length,
+      totalEdges: matchedEdges.length,
+    };
+  }
+
+  findPath(from: string, to: string): GraphPathResult {
+    if (!this.data) return { found: false, nodes: [], edges: [], length: 0 };
+
+    const startNode = this.findNodeByName(from);
+    const endNode = this.findNodeByName(to);
+    if (!startNode || !endNode) return { found: false, nodes: [], edges: [], length: 0 };
+
+    const visited = new Set<string>();
+    const queue: Array<{ nodeId: string; path: string[] }> = [{ nodeId: startNode.id, path: [startNode.id] }];
+    visited.add(startNode.id);
+
+    while (queue.length > 0) {
+      const { nodeId, path } = queue.shift()!;
+      if (nodeId === endNode.id) {
+        const pathNodes = path.map((id) => this.data!.nodes.find((n) => n.id === id)!).filter(Boolean);
+        const pathEdges: GraphEdge[] = [];
+        for (let i = 0; i < path.length - 1; i++) {
+          const edges = this.adjacency.get(path[i])?.get(path[i + 1]);
+          if (edges) pathEdges.push(edges[0]);
+        }
+        return { found: true, nodes: pathNodes, edges: pathEdges, length: path.length - 1 };
+      }
+      const neighbors = this.adjacency.get(nodeId);
+      if (neighbors) {
+        for (const [neighborId] of neighbors) {
+          if (!visited.has(neighborId)) {
+            visited.add(neighborId);
+            queue.push({ nodeId: neighborId, path: [...path, neighborId] });
+          }
+        }
+      }
+    }
+
+    return { found: false, nodes: [], edges: [], length: 0 };
+  }
+
+  findGodNodes(limit = 10): GraphNode[] {
+    if (!this.data) return [];
+    const degreeMap = new Map<string, number>();
+    for (const edge of this.data.edges) {
+      degreeMap.set(edge.source, (degreeMap.get(edge.source) || 0) + 1);
+      degreeMap.set(edge.target, (degreeMap.get(edge.target) || 0) + 1);
+    }
+    return this.data.nodes
+      .map((n) => ({ ...n, degree: degreeMap.get(n.id) || 0 }))
+      .sort((a, b) => (b.degree || 0) - (a.degree || 0))
+      .slice(0, limit);
+  }
+
+  getMetadata(): GraphMetadata {
+    if (!this.data) return { nodeCount: 0, edgeCount: 0, communityCount: 0, godNodes: 0, languages: [] };
+    return { ...this.data.metadata };
+  }
+
+  getNode(id: string): GraphNode | undefined {
+    return this.data?.nodes.find((n) => n.id === id);
+  }
+
+  private findNodeByName(name: string): GraphNode | undefined {
+    if (!this.data) return undefined;
+    return (
+      this.data.nodes.find((n) => n.id === name || n.name === name) ||
+      this.data.nodes.find((n) => n.name.toLowerCase().includes(name.toLowerCase()))
+    );
+  }
+}

package/apps/server/src/infrastructure/graph/index.ts

@@ -0,0 +1,2 @@
+export { GraphifyKnowledgeGraph } from './GraphifyKnowledgeGraph.js';
+export { GraphSearchDecorator } from './GraphSearchDecorator.js';

package/apps/server/src/infrastructure/persistence/sqlite/SqliteBuildRepository.ts

@@ -0,0 +1,34 @@
+import type Database from 'better-sqlite3';
+import type { Build } from '../../../core/domain/types.js';
+import type { IBuildRepository } from '../../../core/ports/IBuildRepository.js';
+import { getDb } from './connection.js';
+
+export class SqliteBuildRepository implements IBuildRepository {
+  private db: Database.Database;
+
+  constructor(db?: Database.Database) {
+    this.db = db ?? getDb();
+  }
+
+  async create(entryId: string): Promise<Build> {
+    const id = crypto.randomUUID();
+    const now = new Date().toISOString();
+    this.db.prepare(
+      'INSERT INTO builds (id, entry_id, status, started_at) VALUES (?, ?, ?, ?)'
+    ).run(id, entryId, 'building', now);
+    return this.findLatest(entryId) as Promise<Build>;
+  }
+
+  async update(buildId: string, status: Build['status'], log: string): Promise<void> {
+    const now = new Date().toISOString();
+    this.db.prepare(
+      'UPDATE builds SET status = ?, log = ?, finished_at = ? WHERE id = ?'
+    ).run(status, log, now, buildId);
+  }
+
+  async findLatest(entryId: string): Promise<Build | undefined> {
+    return this.db.prepare(
+      'SELECT * FROM builds WHERE entry_id = ? ORDER BY started_at DESC LIMIT 1'
+    ).get(entryId) as Build | undefined;
+  }
+}

package/apps/server/src/infrastructure/persistence/sqlite/SqliteEntryReadModel.ts

@@ -0,0 +1,17 @@
+import type Database from 'better-sqlite3';
+import type { IEntryReadModel, EntryReadModelItem } from '../../../core/ports/IEntryReadModel.js';
+import { getDb } from './connection.js';
+
+export class SqliteEntryReadModel implements IEntryReadModel {
+  private db: Database.Database;
+
+  constructor(db?: Database.Database) {
+    this.db = db ?? getDb();
+  }
+
+  async listReadyEntries(): Promise<EntryReadModelItem[]> {
+    return this.db.prepare(
+      "SELECT id, name, version FROM entries WHERE status = 'ready' ORDER BY name"
+    ).all() as EntryReadModelItem[];
+  }
+}

package/apps/server/src/infrastructure/persistence/sqlite/SqliteEntryRepository.ts

@@ -0,0 +1,81 @@
+import type Database from 'better-sqlite3';
+import type { Entry, CreateEntryInput, UpdateEntryInput } from '../../../core/domain/types.js';
+import type { IEntryRepository } from '../../../core/ports/IEntryRepository.js';
+import { DomainError } from '../../../core/domain/errors.js';
+import { getDb } from './connection.js';
+
+export class SqliteEntryRepository implements IEntryRepository {
+  private db: Database.Database;
+
+  constructor(db?: Database.Database) {
+    this.db = db ?? getDb();
+  }
+
+  async findAll(): Promise<(Entry & { source_count: number })[]> {
+    return this.db.prepare(`
+      SELECT e.*, COUNT(s.id) as source_count
+      FROM entries e
+      LEFT JOIN sources s ON s.entry_id = e.id
+      GROUP BY e.id
+      ORDER BY e.created_at DESC
+    `).all() as (Entry & { source_count: number })[];
+  }
+
+  async findById(id: string): Promise<Entry | undefined> {
+    return this.db.prepare('SELECT * FROM entries WHERE id = ?').get(id) as Entry | undefined;
+  }
+
+  async save(entry: Entry): Promise<void> {
+    this.db.prepare(
+      'INSERT OR REPLACE INTO entries (id, name, version, description, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)'
+    ).run(entry.id, entry.name, entry.version, entry.description, entry.status, entry.created_at, entry.updated_at);
+  }
+
+  async update(id: string, input: UpdateEntryInput): Promise<void> {
+    const existing = await this.findById(id);
+    if (!existing) return;
+    const now = new Date().toISOString();
+    this.db.prepare(
+      'UPDATE entries SET name = ?, version = ?, description = ?, updated_at = ? WHERE id = ?'
+    ).run(
+      input.name ?? existing.name,
+      input.version ?? existing.version,
+      input.description ?? existing.description,
+      now,
+      id,
+    );
+  }
+
+  async delete(id: string): Promise<void> {
+    this.db.prepare('DELETE FROM entries WHERE id = ?').run(id);
+  }
+
+  async updateStatus(id: string, status: Entry['status']): Promise<void> {
+    this.db.prepare('UPDATE entries SET status = ? WHERE id = ?').run(status, id);
+  }
+
+  async create(input: CreateEntryInput): Promise<Entry> {
+    // Resolve unique ID:
+    // - Use input.id if provided and available
+    // - Fall back to random UUID if no id given
+    // - If the provided id already exists, append -2, -3, etc.
+    let id = input.id ?? crypto.randomUUID();
+    if (input.id) {
+      let suffix = 2;
+      let candidateId = id;
+      while (this.db.prepare('SELECT 1 FROM entries WHERE id = ?').get(candidateId)) {
+        candidateId = `${id}-${suffix}`;
+        suffix++;
+      }
+      id = candidateId;
+    }
+
+    const now = new Date().toISOString();
+    this.db.prepare(
+      'INSERT INTO entries (id, name, version, description, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)'
+    ).run(id, input.name, input.version, input.description ?? '', now, now);
+    const entry = await this.findById(id);
+    if (!entry) throw new DomainError('Failed to create entry', 'PERSISTENCE_ERROR');
+    return entry;
+  }
+}

package/apps/server/src/infrastructure/persistence/sqlite/SqliteSourceRepository.ts

@@ -0,0 +1,65 @@
+import type Database from 'better-sqlite3';
+import type { Source, CreateSourceInput, UpdateSourceInput } from '../../../core/domain/types.js';
+import type { ISourceRepository } from '../../../core/ports/ISourceRepository.js';
+import { getDb } from './connection.js';
+
+function parseSource(row: Record<string, unknown>): Source {
+  return {
+    ...row,
+    config: JSON.parse(row.config as string),
+  } as Source;
+}
+
+export class SqliteSourceRepository implements ISourceRepository {
+  private db: Database.Database;
+
+  constructor(db?: Database.Database) {
+    this.db = db ?? getDb();
+  }
+
+  async findByEntryId(entryId: string): Promise<Source[]> {
+    const rows = this.db.prepare(
+      'SELECT * FROM sources WHERE entry_id = ? ORDER BY created_at DESC'
+    ).all(entryId) as (Omit<Source, 'config'> & { config: string })[];
+    return rows.map(parseSource);
+  }
+
+  async findById(id: string): Promise<Source | undefined> {
+    const row = this.db.prepare('SELECT * FROM sources WHERE id = ?').get(id) as (Omit<Source, 'config'> & { config: string }) | undefined;
+    return row ? parseSource(row) : undefined;
+  }
+
+  async save(source: Source): Promise<void> {
+    this.db.prepare(
+      'INSERT OR REPLACE INTO sources (id, entry_id, type, label, config, status, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)'
+    ).run(source.id, source.entry_id, source.type, source.label, JSON.stringify(source.config), source.status, source.created_at);
+  }
+
+  async create(entryId: string, input: CreateSourceInput): Promise<Source> {
+    const id = crypto.randomUUID();
+    const now = new Date().toISOString();
+    this.db.prepare(
+      'INSERT INTO sources (id, entry_id, type, label, config, created_at) VALUES (?, ?, ?, ?, ?, ?)'
+    ).run(id, entryId, input.type, input.label, JSON.stringify(input.config), now);
+    const source = await this.findById(id);
+    if (!source) throw new Error('Failed to create source');
+    return source;
+  }
+
+  async update(id: string, input: UpdateSourceInput): Promise<void> {
+    const existing = await this.findById(id);
+    if (!existing) return;
+    const newConfig = input.config ?? existing.config;
+    this.db.prepare(
+      'UPDATE sources SET label = ?, config = ? WHERE id = ?'
+    ).run(input.label ?? existing.label, JSON.stringify(newConfig), id);
+  }
+
+  async delete(id: string): Promise<void> {
+    this.db.prepare('DELETE FROM sources WHERE id = ?').run(id);
+  }
+
+  async updateStatus(id: string, status: Source['status']): Promise<void> {
+    this.db.prepare('UPDATE sources SET status = ? WHERE id = ?').run(status, id);
+  }
+}

package/apps/server/src/infrastructure/persistence/sqlite/connection.ts

@@ -0,0 +1,52 @@
+import Database from 'better-sqlite3';
+import path from 'node:path';
+import fs from 'node:fs';
+import { DATA_ROOT } from '../../../services/paths.js';
+
+const DB_PATH = path.join(DATA_ROOT, 'dockit.db');
+let db: Database.Database | null = null;
+
+export function getDb(): Database.Database {
+  if (!db) {
+    const dir = path.dirname(DB_PATH);
+    fs.mkdirSync(dir, { recursive: true });
+    db = new Database(DB_PATH);
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
+    initDb(db);
+  }
+  return db;
+}
+
+export function initDb(database: Database.Database): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS entries (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      version TEXT NOT NULL,
+      description TEXT DEFAULT '',
+      status TEXT DEFAULT 'pending' CHECK(status IN ('pending', 'building', 'ready', 'error')),
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS sources (
+      id TEXT PRIMARY KEY,
+      entry_id TEXT NOT NULL REFERENCES entries(id) ON DELETE CASCADE,
+      type TEXT NOT NULL CHECK(type IN ('zip', 'antora', 'maven', 'asciidoc', 'github-markdown', 'source-code')),
+      label TEXT NOT NULL,
+      config TEXT NOT NULL DEFAULT '{}',
+      status TEXT DEFAULT 'pending' CHECK(status IN ('pending', 'building', 'ready', 'error')),
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS builds (
+      id TEXT PRIMARY KEY,
+      entry_id TEXT NOT NULL REFERENCES entries(id) ON DELETE CASCADE,
+      status TEXT DEFAULT 'pending' CHECK(status IN ('pending', 'building', 'ready', 'error')),
+      log TEXT DEFAULT '',
+      started_at TEXT NOT NULL DEFAULT (datetime('now')),
+      finished_at TEXT
+    );
+  `);
+}

package/apps/server/src/infrastructure/search/SearchEngineFactory.ts

@@ -0,0 +1,43 @@
+import type { ISearchEngine } from '../../core/ports/ISearchEngine.js';
+import type { IEntryReadModel } from '../../core/ports/IEntryReadModel.js';
+import type { IKnowledgeGraph } from '../../core/ports/IKnowledgeGraph.js';
+import type { SearchEngineType } from '../../core/domain/types.js';
+import { JsonSearchEngine } from './json/JsonSearchEngine.js';
+import { GraphSearchDecorator } from '../graph/GraphSearchDecorator.js';
+
+export async function createSearchEngine(
+  entryReadModel: IEntryReadModel,
+  engine: SearchEngineType = 'vector',
+  knowledgeGraph?: IKnowledgeGraph,
+): Promise<ISearchEngine> {
+  let engine_ = engine;
+  switch (engine_) {
+    case 'vector':
+      return wrapWithGraph(await createVectorSearchEngine(entryReadModel), knowledgeGraph);
+    case 'json':
+    default:
+      return wrapWithGraph(new JsonSearchEngine(entryReadModel), knowledgeGraph);
+  }
+}
+
+function wrapWithGraph(engine: ISearchEngine, knowledgeGraph?: IKnowledgeGraph): ISearchEngine {
+  if (knowledgeGraph && knowledgeGraph.exists()) {
+    return new GraphSearchDecorator(engine, knowledgeGraph);
+  }
+  return engine;
+}
+
+async function createVectorSearchEngine(entryReadModel: IEntryReadModel): Promise<ISearchEngine> {
+  try {
+    await import('@lancedb/lancedb');
+    const { VectorSearchEngine } = await import('./vector/VectorSearchEngine.js');
+    return new VectorSearchEngine(entryReadModel);
+  } catch {
+    console.error(
+      '[dockit] Vector search engine is not available. ' +
+      'Install @lancedb/lancedb and @dockit/embeddings, then set search.engine to "vector". ' +
+      'Falling back to JSON search.'
+    );
+    return new JsonSearchEngine(entryReadModel);
+  }
+}