repo-initialization

Complete guide for extracting the knowledge graph implementation from the research monorepo and setting up as a standalone opensource npm package.

Purpose

Transform @research/graph into @zabaca/lattice - a standalone, opensource knowledge graph package that anyone can install and use.

Repository Structure

/home/uptown/Projects/zabaca/lattice/
├── README.md                     # Main documentation
├── LICENSE                       # MIT license
├── package.json                  # NPM package config
├── tsconfig.json                 # TypeScript config
├── bun.lock                      # Dependencies
├── .gitignore
├── src/                          # Core package code
│   ├── cli.ts                    # CLI entry point
│   ├── main.ts                   # NestJS application
│   ├── graph/                    # Graph service (from packages/graph/src/graph/)
│   ├── sync/                     # Sync service (from packages/graph/src/sync/)
│   ├── search/                   # Search service (from packages/graph/src/search/)
│   └── utils/                    # Utilities (from @research/tools)
├── .claude/                      # Claude Code commands
│   └── commands/
│       ├── entity-extract.md    # From research repo
│       ├── graph-sync.md        # From research repo
│       └── research.md          # From research repo
├── infra/                        # Infrastructure setup
│   ├── k3s/                      # Kubernetes manifests
│   │   ├── namespace.yaml
│   │   ├── deployment.yaml
│   │   ├── service.yaml
│   │   ├── pvc.yaml
│   │   ├── pv.yaml
│   │   ├── ingress.yaml
│   │   └── nodeport-service.yaml
│   └── docker-compose.yaml      # Docker Compose alternative
├── examples/                     # Usage examples
│   └── basic-usage/
└── dist/                         # Build output (gitignored)

Step 1: Package Extraction

1.1 Files to Extract

From /home/uptown/Projects/research/:

Source	Destination	Notes
`packages/graph/src/`	`src/`	Core implementation (41 TS files)
`packages/research-tools/src/`	`src/utils/`	Frontmatter parsing utilities
`.claude/commands/entity-extract.md`	`.claude/commands/entity-extract.md`	Entity extraction command
`.claude/commands/graph-sync.md`	`.claude/commands/graph-sync.md`	Graph sync command
`.claude/commands/research.md`	`.claude/commands/research.md`	Research command

1.2 Dependencies to Copy

From packages/graph/package.json:

{
  "dependencies": {
    "@nestjs/common": "^11.1.6",
    "@nestjs/config": "^3.2.3",
    "@nestjs/core": "^11.1.6",
    "commander": "^14.0.1",
    "glob": "^10.3.10",
    "ioredis": "^5.4.2",
    "reflect-metadata": "^0.2.2",
    "rxjs": "^7.8.2",
    "zod": "^3.22.4"
  }
}

From packages/research-tools/package.json:

yaml (for frontmatter parsing)
zod (schema validation)

Step 2: Package Configuration

2.1 package.json

Based on codegraph example at /home/uptown/Projects/zabaca/codegraph/:

{
  "name": "@zabaca/lattice",
  "version": "0.1.0",
  "description": "Human-initiated, AI-powered knowledge graph for markdown documentation with FalkorDB",
  "type": "module",
  "bin": {
    "lattice": "dist/cli.js"
  },
  "files": [
    "dist",
    "README.md",
    "LICENSE",
    ".claude"
  ],
  "scripts": {
    "build": "bun build src/cli.ts --outdir dist --target bun --packages external",
    "prepublishOnly": "bun run build",
    "dev": "bun --watch src/cli.ts",
    "test": "bun test",
    "lattice": "bun run src/cli.ts",
    "release:patch": "bun test && bun pm version patch && bun publish && git push && git push --tags",
    "release:minor": "bun test && bun pm version minor && bun publish && git push && git push --tags",
    "release:major": "bun test && bun pm version major && bun publish && git push && git push --tags",
    "release:dry": "bun publish --dry-run"
  },
  "keywords": [
    "knowledge-graph",
    "markdown",
    "documentation",
    "semantic-search",
    "falkordb",
    "graph-database",
    "claude-code",
    "ai-powered",
    "entity-extraction"
  ],
  "author": "zabaca",
  "license": "MIT",
  "publishConfig": {
    "access": "public"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/Zabaca/lattice.git"
  },
  "dependencies": {
    "@nestjs/common": "^11.1.6",
    "@nestjs/config": "^3.2.3",
    "@nestjs/core": "^11.1.6",
    "commander": "^14.0.1",
    "glob": "^10.3.10",
    "ioredis": "^5.4.2",
    "reflect-metadata": "^0.2.2",
    "rxjs": "^7.8.2",
    "yaml": "^2.3.4",
    "zod": "^3.22.4"
  },
  "devDependencies": {
    "@types/bun": "latest"
  }
}

2.2 tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "lib": ["ES2022"],
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "types": ["bun-types"]
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

2.3 .gitignore

node_modules/
dist/
*.log
.DS_Store
.env
.env.local
*.tsbuildinfo
coverage/
.idea/
.vscode/

Step 3: Infrastructure Setup

3.1 Docker Compose (Easy Setup)

infra/docker-compose.yaml:

version: '3.8'

services:
  falkordb:
    image: falkordb/falkordb:latest
    container_name: lattice-falkordb
    ports:
      - "6379:6379"  # Redis protocol
      - "3000:3000"  # FalkorDB UI
    volumes:
      - falkordb-data:/var/lib/falkordb/data
    environment:
      - FALKORDB_CACHE_SIZE=2GB
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 3

volumes:
  falkordb-data:
    driver: local

Usage:

# Start FalkorDB
cd /home/uptown/Projects/zabaca/lattice
docker-compose -f infra/docker-compose.yaml up -d

# Check status
docker-compose -f infra/docker-compose.yaml ps

# View UI
open http://localhost:3000

# Stop
docker-compose -f infra/docker-compose.yaml down

3.2 Kubernetes Setup (Production)

Based on /home/uptown/Projects/uptownhr/agents/packages/k3s/falkordb/:

infra/k3s/namespace.yaml:

apiVersion: v1
kind: Namespace
metadata:
  name: falkordb

infra/k3s/pv.yaml:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: falkordb-data-pv
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  hostPath:
    path: /var/lib/falkordb/data
  storageClassName: local-path

infra/k3s/pvc.yaml:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: falkordb-data-pvc
  namespace: falkordb
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: local-path

infra/k3s/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: falkordb
  namespace: falkordb
  labels:
    app: falkordb
spec:
  replicas: 1
  selector:
    matchLabels:
      app: falkordb
  template:
    metadata:
      labels:
        app: falkordb
    spec:
      containers:
      - name: falkordb
        image: falkordb/falkordb:latest
        ports:
        - containerPort: 6379
          name: redis
        - containerPort: 3000
          name: ui
        volumeMounts:
        - name: data
          mountPath: /var/lib/falkordb/data
        resources:
          requests:
            memory: "512Mi"
            cpu: "250m"
          limits:
            memory: "2Gi"
            cpu: "1000m"
        livenessProbe:
          tcpSocket:
            port: 6379
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          tcpSocket:
            port: 6379
          initialDelaySeconds: 5
          periodSeconds: 5
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: falkordb-data-pvc

infra/k3s/service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: falkordb-service
  namespace: falkordb
spec:
  selector:
    app: falkordb
  ports:
    - name: redis
      protocol: TCP
      port: 6379
      targetPort: 6379
    - name: ui
      protocol: TCP
      port: 3000
      targetPort: 3000
  type: ClusterIP

infra/k3s/nodeport-service.yaml (for local k3s access):

apiVersion: v1
kind: Service
metadata:
  name: falkordb-nodeport
  namespace: falkordb
spec:
  type: NodePort
  selector:
    app: falkordb
  ports:
    - name: redis
      protocol: TCP
      port: 6379
      targetPort: 6379
      nodePort: 30379
    - name: ui
      protocol: TCP
      port: 3000
      targetPort: 3000
      nodePort: 30300

infra/k3s/ingress.yaml (optional):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: falkordb-ingress
  namespace: falkordb
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - falkordb.yourdomain.com
      secretName: falkordb-tls
  rules:
    - host: falkordb.yourdomain.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: falkordb-service
                port:
                  number: 3000

Deployment commands:

# Deploy to k3s
kubectl apply -f infra/k3s/namespace.yaml
kubectl apply -f infra/k3s/pv.yaml
kubectl apply -f infra/k3s/pvc.yaml
kubectl apply -f infra/k3s/deployment.yaml
kubectl apply -f infra/k3s/service.yaml
kubectl apply -f infra/k3s/nodeport-service.yaml  # For local access

# Check status
kubectl get all -n falkordb

# Access UI (NodePort)
open http://localhost:30300

# Port forward (alternative)
kubectl port-forward -n falkordb svc/falkordb-service 6379:6379 3000:3000

Step 4: Claude Code Commands Migration

4.1 Update Command Paths

The commands reference paths that need updating:

entity-extract.md - Update to use new package structure:

# Before (in research repo)
Valid entity types: Topic, Technology, Concept, Tool, Process, Person, Organization

# After (in lattice repo)
Valid entity types: Topic, Technology, Concept, Tool, Process, Person, Organization
# (Same schema, just ensure it works standalone)

graph-sync.md - Update Task subagent instructions:

# Before
Uses @research/graph package

# After
Uses @zabaca/lattice package

research.md - Update to use lattice CLI:

# Before
bun graph search --semantic "$ARGUMENTS" --limit 10

# After
lattice search --semantic "$ARGUMENTS" --limit 10

4.2 Environment Configuration

Create .env.example:

# FalkorDB Connection
FALKORDB_HOST=localhost
FALKORDB_PORT=6379
FALKORDB_PASSWORD=

# Voyage AI (for embeddings)
VOYAGE_API_KEY=your_voyage_api_key_here

# Graph Settings
GRAPH_NAME=knowledge_graph
EMBEDDING_MODEL=voyage-3

Step 5: README Documentation

Create comprehensive README.md:

# Lattice

Human-initiated, AI-powered knowledge graph for markdown documentation.

## Features

- 🧠 **AI-Powered Entity Extraction**: Claude extracts entities and relationships from your docs
- 📝 **YAML Frontmatter Schema**: Human-readable, version-controlled entity definitions
- 🔍 **Semantic Search**: Cross-entity semantic search with Voyage AI embeddings
- ⚡ **Incremental Sync**: Only process changed documents
- 🗄️ **FalkorDB**: Fast, self-hosted graph database with built-in vector search
- 🛠️ **Claude Code Integration**: Slash commands for seamless workflow

## Quick Start

### 1. Install

\`\`\`bash
npm install -g @zabaca/lattice
# or
bun install -g @zabaca/lattice
\`\`\`

### 2. Start FalkorDB

\`\`\`bash
docker-compose -f node_modules/@zabaca/lattice/infra/docker-compose.yaml up -d
\`\`\`

### 3. Initialize

\`\`\`bash
cd your-docs-project
lattice init
\`\`\`

### 4. Extract Entities

Use Claude Code:
\`\`\`bash
/entity-extract docs/my-document.md
\`\`\`

### 5. Sync to Graph

\`\`\`bash
lattice sync
\`\`\`

### 6. Search

\`\`\`bash
lattice search --semantic "knowledge graph architecture"
\`\`\`

## CLI Commands

| Command | Description |
|---------|-------------|
| \`lattice init\` | Initialize Lattice in current project |
| \`lattice sync\` | Sync documents to graph |
| \`lattice search\` | Semantic search across entities |
| \`lattice stats\` | Show graph statistics |
| \`lattice validate\` | Validate frontmatter schemas |

## Claude Code Integration

Lattice includes slash commands for Claude Code:

- \`/entity-extract [file]\` - Extract entities from a document
- \`/graph-sync\` - Batch extract and sync modified docs
- \`/research [topic]\` - Smart research with semantic search

## Documentation

- [Architecture](./docs/architecture.md)
- [Entity Schema](./docs/schema.md)
- [Examples](./examples/)

## License

MIT
\`\`\`

---

## Step 6: GitHub Repository Setup

### 6.1 Create Repository

```bash
# On GitHub
# Create repository: zabaca/lattice
# Description: "Human-initiated, AI-powered knowledge graph for markdown documentation"
# Public repository
# MIT license

6.2 Initialize Git

cd /home/uptown/Projects/zabaca/lattice
git init
git add .
git commit -m "Initial commit: Lattice knowledge graph package"
git branch -M main
git remote add origin https://github.com/Zabaca/lattice.git
git push -u origin main

Step 7: NPM Publishing

7.1 Build and Test

cd /home/uptown/Projects/zabaca/lattice
bun install
bun run build
bun test

7.2 Dry Run

bun run release:dry

7.3 Publish

# Login to npm (if not already)
npm login

# Publish (starts at 0.1.0)
bun publish

7.4 Future Releases

# Patch release (0.1.0 → 0.1.1)
bun run release:patch

# Minor release (0.1.1 → 0.2.0)
bun run release:minor

# Major release (0.2.0 → 1.0.0)
bun run release:major

Step 8: Post-Setup Checklist

Migration Notes

From Research Repo

Users of the research repo @research/graph will need to:

Install global package: npm install -g @zabaca/lattice
Update Claude Code commands to use lattice CLI
Set up FalkorDB using provided infrastructure files
Re-sync their documents: lattice sync

Breaking Changes from @research/graph

CLI command changed: bun graph → lattice
Package name: @research/graph → @zabaca/lattice
Requires separate FalkorDB setup (not assumed to exist)

Future Enhancements

Auto-install infrastructure: lattice setup --docker to auto-configure FalkorDB
Multi-database support: Add Neo4j, MemGraph adapters
VSCode extension: Inline entity extraction in editor
Web UI: Dashboard for exploring the knowledge graph
Cloud deployment: One-click deploy to Railway/Render
Pipeline-auto mode: Optional automatic extraction on file save

Resources

Implementation Comparison - How Lattice compares to alternatives
Naming Process - Why “Lattice”