Architecture Overview

┌─────────────┐
│ Your App    │
│ (Frontend   │
│  or Server) │
└──────┬──────┘
       │ Import @synap/sdk
       ▼
┌─────────────┐
│  Synap SDK  │  ← High-level API
│             │
│ • entities  │
│ • relations │
│ • events    │
└──────┬──────┘
       │ Uses @synap/client (tRPC)
       ▼
┌─────────────┐
│  API Layer  │  ← tRPC Routers
│ (Backend)   │
│             │
│ • 20 routers│
│ • Auth      │
│ • Validation│
└──────┬──────┘
       │
       ├─────────────┐
       │             │
       ▼             ▼
┌──────────┐   ┌──────────┐
│ Database │   │ Inngest  │
│(Postgres)│   │ Workers  │
│          │   │          │
│ • Read   │   │ • Write  │
│ • Query  │   │ • Process│
└──────────┘   └──────────┘

// 1. Your app calls SDK
await synap.entities.create({ type: 'task', title: 'Review PR' })

// 2. SDK publishes event via tRPC
client.events.log.mutate({
  eventType: 'entities.create.requested',
  data: { type: 'task', title: 'Review PR' }
})

// 3. API validates & logs event
POST /trpc/events.log
→ Insert into events table
→ Return success

// 4. Inngest picks up event
entitiesWorker.handle(event)
→ Validate data
→ Insert into entities table
→ Upload file (if content exists)
→ Emit validation event

// 5. Broadcasts update
→ SSE to connected clients
→ Webhooks to configured URLs

// 1. Your app calls SDK
const tasks = await synap.entities.list({ type: 'task' })

// 2. SDK queries via tRPC
client.entities.list.query({ type: 'task' })

// 3. API queries database
SELECT * FROM entities WHERE type = 'task' AND userId = ?

// 4. Returns results immediately
→ No event processing needed
→ Fast, synchronous

@synap/sdk
├── Built on @synap/client (tRPC client)
├── TypeScript for type safety
└── Exports:
    • SynapSDK (main class)
    • EntitiesAPI
    • RelationsAPI
    • EventsAPI

Backend (apps/api)
├── Next.js API routes
├── tRPC for type-safe APIs
├── 20 routers:
│   ├── entities (CRUD)
│   ├── relations (relationships)
│   ├── events (logging)
│   ├── search (full-text + semantic)
│   └── ... 16 more
└── Authentication (JWT/API keys)

PostgreSQL
├── Tables:
│   ├── entities (materialized view)
│   ├── events (event log)
│   ├── relations (connections)
│   ├── documents (content)
│   └── ... 20 more tables
└── Indexes for performance

Inngest Workers
├── entities Walker (create/update/delete)
├── relationsWorker (link management)
├── documentsWorker (content processing)
├── enrichmentProjector (AI features)
└── ... 8 workers total

events table:
├── id (UUID)
├── type (event type: 'entities.create.requested')
├── data (event payload)
├── userId (who)
├── timestamp (when)
└── metadata (additional context)

entities table:
├── id (UUID)
├── userId (owner)
├── type (entity type)
├── title (display name)
├── metadata (type-specific data)
└── timestamps

// Get all events for entity
const events = await synap.events.getHistory(entityId)
 
// Replay to rebuild state
let state = {}
for (const event of events) {
  if (event.type === 'entities.create.validated') {
    state = event.data
  }
  if (event.type === 'entities.update.validated') {
    state = { ...state, ...event.data }
  }
}

// Every query filtered by userId
SELECT * FROM entities WHERE userId = 'current_user'
 
// Every write includes userId
INSERT INTO events (userId, type, data) VALUES ('current_user', ...)
 
// Workers verify ownership
if (entity.userId !== event.userId) throw new Error('Unauthorized')

// Workers broadcast after processing
await broadcastNotification({
  userId: 'user_123',
  message: {
    type: 'entity.created',
    entityId: 'task_456'
  }
})

// Configure webhooks in API
POST /webhooks
{
  url: 'https://yourapp.com/synap-webhook',
  events: ['entities.create.validated', 'entities.update.validated']
}
 
// Receive notifications
webhook.send({
  event: 'entities.create.validated',
  data: { entityId: '...' }
})

const synap = new SynapSDK({
  url: 'https://api.synap.app',
  apiKey: process.env.SYNAP_API_KEY
})

# Clone repo
git clone https://github.com/synap-labs/synap
 
# Run with Docker
docker-compose up
 
# SDK points to your instance
const synap = new SynapSDK({
  url: 'http://localhost:3000',
  apiKey: 'your-key'
})

// API Key (recommended)
const synap = new SynapSDK({
  apiKey: process.env.SYNAP_API_KEY
})
 
// Custom headers (OAuth, etc.)
const synap = new SynapSDK({
  headers: () => ({
    Authorization: `Bearer ${getToken()}`
  })
})

┌─────────┐  ┌─────────┐  ┌─────────┐
│ API #1  │  │ API #2  │  │ API #3  │
└────┬────┘  └────┬────┘  └────┬────┘
     │            │            │
     └────────────┼────────────┘
                  │
           ┌──────▼──────┐
           │  Database   │
           └──────┬──────┘
                  │
     ┌────────────┼────────────┐
     │            │            │
┌────▼────┐  ┌───▼─────┐  ┌───▼─────┐
│Worker#1 │  │Worker#2 │  │Worker#3 │
└─────────┘  └─────────┘  └─────────┘

// Access underlying tRPC client
const result = await synap.client.search.query({
  query: 'advanced search',
  types: ['task', 'note'],
  limit: 100
})
 
// Call any of 20 routers
await synap.client.webhooks.create.mutate({
  url: 'https://...',
  events: ['entity.created']
})