graph-only-architecture

Markdown files → Parse frontmatter → Extract entities → Sync to graph

Claude Code → CLI → Graph (direct)

-- Single table for all node types (graph.service.ts:136-148)
CREATE TABLE nodes (
  label VARCHAR NOT NULL,           -- 'Document', 'Technology', 'Concept', etc.
  name VARCHAR NOT NULL,            -- File path (for docs) or entity name
  properties JSON,                  -- { title, summary, topic, description, ... }
  embedding FLOAT[512],             -- Voyage voyage-3-lite embeddings
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW(),
  PRIMARY KEY(label, name)          -- Composite key
);

-- Relationships between nodes (graph.service.ts:150-162)
CREATE TABLE relationships (
  source_label VARCHAR NOT NULL,
  source_name VARCHAR NOT NULL,
  relation_type VARCHAR NOT NULL,   -- 'REFERENCES', 'APPEARS_IN'
  target_label VARCHAR NOT NULL,
  target_name VARCHAR NOT NULL,
  properties JSON,                  -- { documentPath, ... }
  created_at TIMESTAMP DEFAULT NOW(),
  PRIMARY KEY(source_label, source_name, relation_type, target_label, target_name)
);

-- No schema change needed!
-- Just store content in the existing properties JSON:
properties = {
  "title": "Research Title",
  "summary": "Brief summary",
  "topic": "databases",
  "content": "Full research content here..."  -- NEW
}

ALTER TABLE nodes ADD COLUMN content TEXT;

-- Then for Document nodes:
-- label = 'Document'
-- name = UUID or slug (not file path)
-- content = full research text
-- properties = { title, summary, topic }

// GraphService addition
async createDocument(doc: { title: string; content: string; ... }): Promise<string> {
  const id = crypto.randomUUID();
  await this.upsertNode('Document', {
    name: id,
    title: doc.title,
    summary: doc.summary,
    content: doc.content,  // Store in properties
    topic: doc.topic,
  });
  return id;
}

@Injectable()
@Command({ name: 'create', description: 'Create a new document in the graph' })
export class CreateCommand extends CommandRunner {
  constructor(
    private readonly graphService: GraphService,
    private readonly embeddingService: EmbeddingService,
  ) { super(); }

  async run(params: string[], options: CreateOptions): Promise<void> {
    const id = crypto.randomUUID();

    // Upsert document node (uses existing GraphService.upsertNode)
    await this.graphService.upsertNode('Document', {
      name: id,
      title: options.title,
      summary: options.summary,
      content: options.content || await this.readStdin(),
      topic: options.topic,
    });

    // Generate embedding (uses existing EmbeddingService)
    const embeddingText = `${options.title}\n\n${options.summary || ''}`;
    const embedding = await this.embeddingService.embed(embeddingText);
    await this.graphService.updateNodeEmbedding('Document', id, embedding);

    // Create entity relationships if provided
    if (options.entities) {
      const entities = JSON.parse(options.entities);
      for (const entity of entities) {
        await this.graphService.upsertNode(entity.type, {
          name: entity.name,
          description: entity.description,
        });
        await this.graphService.upsertRelationship(
          entity.type, entity.name,
          'APPEARS_IN',
          'Document', id,
        );
      }
    }

    console.log(`Created document ${id}`);
    process.exit(0);
  }
}

@Command({ name: 'update', description: 'Update an existing document' })
export class UpdateCommand extends CommandRunner {
  async run([id]: string[], options: UpdateOptions): Promise<void> {
    const updates: Partial<Document> = {};

    if (options.content) updates.content = options.content;
    if (options.title) updates.title = options.title;
    if (options.summary) updates.summary = options.summary;
    if (options.stdin) updates.content = await this.readStdin();

    updates.updated = new Date();

    await this.graphService.updateDocument(id, updates);

    // Re-generate embedding if content changed
    if (updates.content) {
      const doc = await this.graphService.getDocument(id);
      const embedding = await this.embeddingService.embed(
        composeDocumentEmbeddingText(doc)
      );
      await this.graphService.updateEmbedding(id, embedding);
    }

    console.log(`Updated document ${id}`);
  }
}

{
  "id": "abc123-def456",
  "title": "DuckDB Performance Analysis",
  "content": "Full research content here...",
  "summary": "Analysis of DuckDB query performance",
  "topic": "databases",
  "created": "2025-12-07T15:00:00Z",
  "updated": "2025-12-07T15:30:00Z",
  "entities": [
    {"name": "DuckDB", "type": "Technology", "description": "..."}
  ],
  "relationships": [
    {"source": "DuckDB", "relation": "IMPLEMENTS", "target": "OLAP"}
  ]
}

## Process

### Step 1: Search Existing Research
lattice search "<query>" --limit 10

### Step 2: Review Results
- If found: Display document content
- Ask user if existing research answers their question

### Step 3: Create New (if needed)
If user wants new research:

1. Perform web research
2. Create document directly:

lattice create \
  --title "Research Title" \
  --content "$(cat <<'EOF'
# Research Title

## Summary
...

## Key Findings
...

## Sources
...
EOF
)" \
  --summary "Brief summary for search" \
  --entities '[...]' \
  --relationships '[...]'

### Step 4: Entity Extraction
Entities are provided at creation time via --entities flag.
No separate extraction step needed.

-- Migrate content from files to graph
-- Run once for existing documents
UPDATE documents
SET content = (SELECT read_text(path))
WHERE content IS NULL;