Adoption Path

Three tiers of adoption, from lightweight to full platform:

Tier 1: Real-Time Layer

Recommended starting point. Your existing application stays unchanged. TopGun handles only the real-time collaborative features you choose to add.

Example: A project management app keeps all data in Postgres via REST API. But the Kanban board state (card positions, assignments, comments) flows through TopGun for instant collaborative updates. User management, billing, and reports stay on the existing stack.

What you need

1. A running TopGun server:

# Start the TopGun server
DATABASE_URL=postgres://user:pass@localhost/myapp PORT=8080 cargo run --bin test-server --release

2. Client-side integration in your React app:

import React from 'react';
import { TopGunClient } from '@topgunbuild/client';
import { IDBAdapter } from '@topgunbuild/adapters';
import { TopGunProvider, useQuery, useClient } from '@topgunbuild/react';

// 1. Create client (your existing app stays unchanged)
const client = new TopGunClient({
  serverUrl: 'ws://localhost:8080',
  storage: new IDBAdapter()
});
client.start();

// 2. Add a real-time collaborative component
function KanbanBoard({ boardId }: { boardId: string }) {
  const client = useClient();
  const { data: cards } = useQuery('kanban-' + boardId);

  const moveCard = (cardId: string, column: string) => {
    client.getMap('kanban-' + boardId).set(cardId, {
      column, movedAt: Date.now()
    });
  };

  return (
    <div>{cards.map(card => (
      <div key={card.id}>{card.column}: {card.id}</div>
    ))}</div>
  );
}

When to use Tier 1

• You have an existing app and want to add real-time features
• You want instant collaborative editing without changing your backend
• You need offline support for specific features
• You want to evaluate TopGun without risk to existing infrastructure

What you gain

• Zero-latency reads and writes for real-time features
• Automatic CRDT conflict resolution (no custom merge code)
• Offline support with automatic sync on reconnect
• Works alongside your existing REST/GraphQL API

Tier 2: Cache + Sync

TopGun sits in front of your existing PostgreSQL database as an in-memory data grid. Reads come from memory (0ms latency). Writes go through to PostgreSQL (write-through). TopGun adds CRDT sync, live queries, and offline support on top.

# Point TopGun at your existing PostgreSQL instance
# TopGun creates its own tables (topgun_*) alongside yours
DATABASE_URL=postgres://user:pass@localhost/myapp \
PORT=8080 \
cargo run --bin test-server --release

TopGun creates its own topgun_* tables alongside your existing data. See the PostgreSQL guide for details on how TopGun coexists with your schema.

When to use Tier 2

• You want in-memory read performance for your existing data
• You need live queries that push updates to clients automatically
• You want to add CRDT sync and offline support across your entire app
• Your app is read-heavy and would benefit from caching

What you gain

• Everything from Tier 1, plus:
• In-memory reads across all data (0ms latency)
• Write-through to PostgreSQL for durability
• Live queries across all TopGun data
• No schema migration required

Tier 3: Full Platform

For new applications or full migrations, TopGun becomes your primary data store, compute layer, and sync engine. One deployment replaces the combination of a database, cache, sync engine, search engine, and stream processor.

# Full platform: TopGun handles everything
# Storage, compute, sync, search, streaming
DATABASE_URL=postgres://user:pass@localhost/topgun \
PORT=8080 \
TOPGUN_CLUSTER_SEEDS=node2:9000,node3:9000 \
cargo run --bin test-server --release

When to use Tier 3

• Building a new application from scratch
• You want a single platform for storage, compute, sync, and search
• You need distributed clustering with automatic partitioning
• You want full-text search, stream processing, and pub/sub built in

What you gain

• Everything from Tier 1 and 2, plus:
• Multi-node clustering with automatic partitioning (271 partitions)
• Full-text search (Tantivy-powered)
• Server-side entry processors
• Topic pub/sub with ordered delivery
• PostgreSQL-backed durability