add relay compatible subscription support to graphql query builder

api/Cargo.lock

···
  "anyhow",
  "async-graphql",
  "async-graphql-axum",
+ "async-stream",
  "async-trait",
  "atproto-client",
  "atproto-identity",

api/Cargo.toml

···
 async-graphql = { version = "7.0", features = ["dynamic-schema", "dataloader"] }
 async-graphql-axum = "7.0"
 lazy_static = "1.5"
+async-stream = "0.3"

api/src/graphql/handler.rs

···
 //! GraphQL HTTP handler for Axum
 
 use async_graphql::dynamic::Schema;
+use async_graphql::http::{WebSocket as GraphQLWebSocket, WebSocketProtocols, WsMessage};
 use async_graphql_axum::{GraphQLRequest, GraphQLResponse};
 use axum::{
-    extract::{Query, State},
+    extract::{ws::{WebSocket, Message}, Query, State, WebSocketUpgrade},
     http::{HeaderMap, StatusCode},
-    response::Html,
+    response::{Html, Response},
 };
+use futures_util::{StreamExt, SinkExt};
 use serde::Deserialize;
 use std::sync::Arc;
 use tokio::sync::RwLock;
···
     );
 
     Ok(Html(graphiql_html))
+}
+
+/// GraphQL WebSocket handler for subscriptions
+/// Accepts slice URI from query parameter (?slice=...)
+pub async fn graphql_subscription_handler(
+    State(state): State<AppState>,
+    Query(params): Query<GraphQLParams>,
+    ws: WebSocketUpgrade,
+) -> Result<Response, (StatusCode, String)> {
+    let slice_uri = params.slice.ok_or_else(|| {
+        (
+            StatusCode::BAD_REQUEST,
+            "Missing slice parameter. Provide ?slice=... query parameter".to_string(),
+        )
+    })?;
+
+    let schema = match get_or_build_schema(&state, &slice_uri).await {
+        Ok(s) => s,
+        Err(e) => {
+            tracing::error!("Failed to get GraphQL schema: {:?}", e);
+            return Err((
+                StatusCode::INTERNAL_SERVER_ERROR,
+                format!("Schema error: {:?}", e),
+            ));
+        }
+    };
+
+    // Upgrade to WebSocket and handle GraphQL subscriptions manually
+    Ok(ws
+        .protocols(["graphql-transport-ws", "graphql-ws"])
+        .on_upgrade(move |socket| handle_graphql_ws(socket, schema)))
+}
+
+/// Handle GraphQL WebSocket connection
+async fn handle_graphql_ws(socket: WebSocket, schema: Schema) {
+    let (ws_sender, ws_receiver) = socket.split();
+
+    // Convert axum WebSocket messages to strings for async-graphql
+    let input = ws_receiver.filter_map(|msg| {
+        futures_util::future::ready(match msg {
+            Ok(Message::Text(text)) => Some(text.to_string()),
+            _ => None, // Ignore other message types
+        })
+    });
+
+    // Create GraphQL WebSocket handler
+    let mut stream = GraphQLWebSocket::new(schema, input, WebSocketProtocols::GraphQLWS);
+
+    // Send GraphQL messages back through WebSocket
+    let mut ws_sender = ws_sender;
+    while let Some(msg) = stream.next().await {
+        let axum_msg = match msg {
+            WsMessage::Text(text) => Message::Text(text.into()),
+            WsMessage::Close(code, reason) => Message::Close(Some(axum::extract::ws::CloseFrame {
+                code,
+                reason: reason.into(),
+            })),
+        };
+
+        if ws_sender.send(axum_msg).await.is_err() {
+            break;
+        }
+    }
 }
 
 /// Gets schema from cache or builds it if not cached

api/src/graphql/mod.rs

···
 mod dataloaders;
 mod types;
 pub mod handler;
+pub mod pubsub;
 
 pub use schema_builder::build_graphql_schema;
-pub use handler::{graphql_handler, graphql_playground};
+pub use handler::{graphql_handler, graphql_playground, graphql_subscription_handler};
+pub use pubsub::{RecordUpdateEvent, RecordOperation, PUBSUB};

api/src/graphql/pubsub.rs

···
+//! PubSub infrastructure for broadcasting GraphQL subscription events
+//!
+//! This module provides a publish-subscribe mechanism for broadcasting record
+//! updates from the Jetstream consumer to active GraphQL subscriptions.
+
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::sync::Arc;
+use tokio::sync::{broadcast, RwLock};
+use tracing::{debug, info};
+
+/// Event broadcast when a record is created or updated
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct RecordUpdateEvent {
+    pub uri: String,
+    pub cid: String,
+    pub did: String,
+    pub collection: String,
+    pub value: serde_json::Value,
+    pub slice_uri: String,
+    pub indexed_at: String,
+    pub operation: RecordOperation,
+}
+
+/// Type of record operation
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+pub enum RecordOperation {
+    Create,
+    Update,
+    Delete,
+}
+
+
+/// PubSub manager for broadcasting events to subscribers
+///
+/// Each slice has its own broadcast channel to avoid cross-slice event leaking.
+/// Channels are created lazily when the first subscriber for a slice connects.
+pub struct GraphQLPubSub {
+    /// Map of slice_uri -> broadcast sender
+    /// Using broadcast channel allows multiple subscribers per slice
+    channels: Arc<RwLock<HashMap<String, broadcast::Sender<RecordUpdateEvent>>>>,
+    /// Channel capacity (number of events to buffer)
+    capacity: usize,
+}
+
+impl GraphQLPubSub {
+    /// Create a new PubSub manager
+    ///
+    /// # Arguments
+    /// * `capacity` - Number of events to buffer per slice (default: 1000)
+    pub fn new(capacity: usize) -> Self {
+        info!("Initializing GraphQL PubSub with capacity {}", capacity);
+        Self {
+            channels: Arc::new(RwLock::new(HashMap::new())),
+            capacity,
+        }
+    }
+
+    /// Publish an event to all subscribers of a slice
+    ///
+    /// If no subscribers exist, the event is dropped silently.
+    pub async fn publish(&self, event: RecordUpdateEvent) {
+        let slice_uri = event.slice_uri.clone();
+
+        let channels = self.channels.read().await;
+        if let Some(sender) = channels.get(&slice_uri) {
+            // Try to send, ignore if no active receivers
+            match sender.send(event.clone()) {
+                Ok(receiver_count) => {
+                    debug!(
+                        "Published {} event for {} to {} subscriber(s)",
+                        match event.operation {
+                            RecordOperation::Create => "CREATE",
+                            RecordOperation::Update => "UPDATE",
+                            RecordOperation::Delete => "DELETE",
+                        },
+                        event.collection,
+                        receiver_count
+                    );
+                }
+                Err(_) => {
+                    // No receivers, which is fine
+                    debug!("No active subscribers for slice {}", slice_uri);
+                }
+            }
+        }
+    }
+
+    /// Subscribe to events for a specific slice
+    ///
+    /// Returns a receiver that will receive all future events for the slice.
+    /// Creates a new broadcast channel if one doesn't exist yet.
+    pub async fn subscribe(&self, slice_uri: &str) -> broadcast::Receiver<RecordUpdateEvent> {
+        let mut channels = self.channels.write().await;
+
+        let sender = channels.entry(slice_uri.to_string()).or_insert_with(|| {
+            info!("Creating new broadcast channel for slice: {}", slice_uri);
+            let (tx, _) = broadcast::channel(self.capacity);
+            tx
+        });
+
+        sender.subscribe()
+    }
+
+    /// Get statistics about active channels and subscribers
+    pub async fn stats(&self) -> PubSubStats {
+        let channels = self.channels.read().await;
+        PubSubStats {
+            active_channels: channels.len(),
+            total_subscribers: channels.values().map(|s| s.receiver_count()).sum(),
+        }
+    }
+
+    /// Clean up channels with no subscribers
+    ///
+    /// Should be called periodically to prevent memory leaks
+    pub async fn cleanup_empty_channels(&self) {
+        let mut channels = self.channels.write().await;
+        let before_count = channels.len();
+
+        channels.retain(|slice_uri, sender| {
+            let has_subscribers = sender.receiver_count() > 0;
+            if !has_subscribers {
+                debug!("Removing empty broadcast channel for slice: {}", slice_uri);
+            }
+            has_subscribers
+        });
+
+        let removed = before_count - channels.len();
+        if removed > 0 {
+            info!("Cleaned up {} empty broadcast channel(s)", removed);
+        }
+    }
+}
+
+/// Statistics about the PubSub system
+#[derive(Debug, Clone)]
+pub struct PubSubStats {
+    pub active_channels: usize,
+    pub total_subscribers: usize,
+}
+
+impl Default for GraphQLPubSub {
+    fn default() -> Self {
+        Self::new(1000)
+    }
+}
+
+// Global PubSub instance
+// This is initialized once at application startup and shared across
+// the Jetstream consumer and GraphQL subscription handlers.
+lazy_static::lazy_static! {
+    pub static ref PUBSUB: GraphQLPubSub = GraphQLPubSub::default();
+}
+
+/// Start periodic cleanup task for empty channels
+pub fn start_cleanup_task() {
+    tokio::spawn(async {
+        let mut interval = tokio::time::interval(tokio::time::Duration::from_secs(300)); // Every 5 minutes
+        loop {
+            interval.tick().await;
+            PUBSUB.cleanup_empty_channels().await;
+
+            let stats = PUBSUB.stats().await;
+            info!(
+                "PubSub stats: {} active channels, {} total subscribers",
+                stats.active_channels, stats.total_subscribers
+            );
+        }
+    });
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_pubsub_broadcast() {
+        let pubsub = GraphQLPubSub::new(100);
+
+        // Subscribe to events
+        let mut rx = pubsub.subscribe("test://slice").await;
+
+        // Publish an event
+        let event = RecordUpdateEvent {
+            uri: "at://did:plc:test/app.test/123".to_string(),
+            cid: "bafytest".to_string(),
+            did: "did:plc:test".to_string(),
+            collection: "app.test".to_string(),
+            value: serde_json::json!({"text": "Hello"}),
+            slice_uri: "test://slice".to_string(),
+            indexed_at: "2024-01-01T00:00:00Z".to_string(),
+            operation: RecordOperation::Create,
+        };
+
+        pubsub.publish(event.clone()).await;
+
+        // Receive the event
+        let received = rx.recv().await.unwrap();
+        assert_eq!(received.uri, event.uri);
+        assert_eq!(received.collection, event.collection);
+    }
+
+    #[tokio::test]
+    async fn test_multiple_subscribers() {
+        let pubsub = GraphQLPubSub::new(100);
+
+        let mut rx1 = pubsub.subscribe("test://slice").await;
+        let mut rx2 = pubsub.subscribe("test://slice").await;
+
+        let event = RecordUpdateEvent {
+            uri: "at://did:plc:test/app.test/123".to_string(),
+            cid: "bafytest".to_string(),
+            did: "did:plc:test".to_string(),
+            collection: "app.test".to_string(),
+            value: serde_json::json!({"text": "Hello"}),
+            slice_uri: "test://slice".to_string(),
+            indexed_at: "2024-01-01T00:00:00Z".to_string(),
+            operation: RecordOperation::Create,
+        };
+
+        pubsub.publish(event.clone()).await;
+
+        // Both subscribers should receive the event
+        let received1 = rx1.recv().await.unwrap();
+        let received2 = rx2.recv().await.unwrap();
+
+        assert_eq!(received1.uri, event.uri);
+        assert_eq!(received2.uri, event.uri);
+    }
+
+    #[tokio::test]
+    async fn test_cleanup_empty_channels() {
+        let pubsub = GraphQLPubSub::new(100);
+
+        // Create a subscriber and drop it
+        {
+            let _rx = pubsub.subscribe("test://slice").await;
+            assert_eq!(pubsub.stats().await.active_channels, 1);
+        }
+
+        // Cleanup should remove the empty channel
+        pubsub.cleanup_empty_channels().await;
+        assert_eq!(pubsub.stats().await.active_channels, 0);
+    }
+}

api/src/graphql/schema_builder.rs

···
 //! This module generates GraphQL schemas at runtime based on lexicon definitions
 //! stored in the database, enabling flexible querying of slice records.
 
-use async_graphql::dynamic::{Field, FieldFuture, FieldValue, Object, Schema, Scalar, TypeRef, InputObject, InputValue, Enum, EnumItem};
+use async_graphql::dynamic::{Field, FieldFuture, FieldValue, Object, Schema, Scalar, TypeRef, InputObject, InputValue, Enum, EnumItem, Subscription, SubscriptionField, SubscriptionFieldFuture};
 use async_graphql::{Error, Value as GraphQLValue};
 use base64::engine::general_purpose;
 use base64::Engine;
···
 
 use crate::database::Database;
 use crate::graphql::types::{extract_collection_fields, extract_record_key, GraphQLField, GraphQLType};
+use crate::graphql::PUBSUB;
 
 /// Metadata about a collection for cross-referencing
 #[derive(Clone)]
···
     // Build Mutation type
     let mutation = create_mutation_type(database.clone(), slice_uri.clone());
 
+    // Build Subscription type with collection-specific subscriptions
+    let subscription = create_subscription_type(slice_uri.clone(), &lexicons);
+
     // Build and return the schema
-    let mut schema_builder = Schema::build(query.type_name(), Some(mutation.type_name()), None)
+    let mut schema_builder = Schema::build(query.type_name(), Some(mutation.type_name()), Some(subscription.type_name()))
         .register(query)
-        .register(mutation);
+        .register(mutation)
+        .register(subscription);
 
     // Register JSON scalar type for complex fields
     let json_scalar = Scalar::new("JSON");
···
     // Register PageInfo type
     let page_info_type = create_page_info_type();
     schema_builder = schema_builder.register(page_info_type);
+
+    // Register RecordUpdate type for subscriptions
+    let record_update_type = create_record_update_type();
+    schema_builder = schema_builder.register(record_update_type);
 
     // Register all object types
     for obj in objects_to_register {
···
         }
     }
 }
+
+/// Creates the RecordUpdate type for subscription events
+fn create_record_update_type() -> Object {
+    let mut record_update = Object::new("RecordUpdate");
+
+    record_update = record_update.field(Field::new("uri", TypeRef::named_nn(TypeRef::STRING), |ctx| {
+        FieldFuture::new(async move {
+            let value = ctx.parent_value.downcast_ref::<GraphQLValue>()
+                .ok_or_else(|| Error::new("Failed to downcast RecordUpdate"))?;
+            if let GraphQLValue::Object(obj) = value {
+                if let Some(uri) = obj.get("uri") {
+                    return Ok(Some(uri.clone()));
+                }
+            }
+            Ok(None)
+        })
+    }));
+
+    record_update = record_update.field(Field::new("cid", TypeRef::named_nn(TypeRef::STRING), |ctx| {
+        FieldFuture::new(async move {
+            let value = ctx.parent_value.downcast_ref::<GraphQLValue>()
+                .ok_or_else(|| Error::new("Failed to downcast RecordUpdate"))?;
+            if let GraphQLValue::Object(obj) = value {
+                if let Some(cid) = obj.get("cid") {
+                    return Ok(Some(cid.clone()));
+                }
+            }
+            Ok(None)
+        })
+    }));
+
+    record_update = record_update.field(Field::new("did", TypeRef::named_nn(TypeRef::STRING), |ctx| {
+        FieldFuture::new(async move {
+            let value = ctx.parent_value.downcast_ref::<GraphQLValue>()
+                .ok_or_else(|| Error::new("Failed to downcast RecordUpdate"))?;
+            if let GraphQLValue::Object(obj) = value {
+                if let Some(did) = obj.get("did") {
+                    return Ok(Some(did.clone()));
+                }
+            }
+            Ok(None)
+        })
+    }));
+
+    record_update = record_update.field(Field::new("collection", TypeRef::named_nn(TypeRef::STRING), |ctx| {
+        FieldFuture::new(async move {
+            let value = ctx.parent_value.downcast_ref::<GraphQLValue>()
+                .ok_or_else(|| Error::new("Failed to downcast RecordUpdate"))?;
+            if let GraphQLValue::Object(obj) = value {
+                if let Some(collection) = obj.get("collection") {
+                    return Ok(Some(collection.clone()));
+                }
+            }
+            Ok(None)
+        })
+    }));
+
+    record_update = record_update.field(Field::new("indexedAt", TypeRef::named_nn(TypeRef::STRING), |ctx| {
+        FieldFuture::new(async move {
+            let value = ctx.parent_value.downcast_ref::<GraphQLValue>()
+                .ok_or_else(|| Error::new("Failed to downcast RecordUpdate"))?;
+            if let GraphQLValue::Object(obj) = value {
+                if let Some(indexed_at) = obj.get("indexedAt") {
+                    return Ok(Some(indexed_at.clone()));
+                }
+            }
+            Ok(None)
+        })
+    }));
+
+    record_update = record_update.field(Field::new("operation", TypeRef::named_nn(TypeRef::STRING), |ctx| {
+        FieldFuture::new(async move {
+            let value = ctx.parent_value.downcast_ref::<GraphQLValue>()
+                .ok_or_else(|| Error::new("Failed to downcast RecordUpdate"))?;
+            if let GraphQLValue::Object(obj) = value {
+                if let Some(operation) = obj.get("operation") {
+                    return Ok(Some(operation.clone()));
+                }
+            }
+            Ok(None)
+        })
+    }));
+
+    record_update = record_update.field(Field::new("value", TypeRef::named_nn("JSON"), |ctx| {
+        FieldFuture::new(async move {
+            let value = ctx.parent_value.downcast_ref::<GraphQLValue>()
+                .ok_or_else(|| Error::new("Failed to downcast RecordUpdate"))?;
+            if let GraphQLValue::Object(obj) = value {
+                if let Some(val) = obj.get("value") {
+                    return Ok(Some(val.clone()));
+                }
+            }
+            Ok(None)
+        })
+    }));
+
+    record_update
+}
+
+/// Creates the Subscription root type with collection-specific subscriptions
+fn create_subscription_type(slice_uri: String, lexicons: &[serde_json::Value]) -> Subscription {
+    let mut subscription = Subscription::new("Subscription");
+
+    // For each record collection, create {collection}Created, {collection}Updated, {collection}Deleted subscriptions
+    for lexicon in lexicons {
+        let nsid = match lexicon.get("id").and_then(|n| n.as_str()) {
+            Some(n) => n,
+            None => continue,
+        };
+
+        let defs = match lexicon.get("defs") {
+            Some(d) => d,
+            None => continue,
+        };
+
+        // Only process record types (skip queries, procedures, etc.)
+        let is_record = defs
+            .get("main")
+            .and_then(|m| m.get("type"))
+            .and_then(|t| t.as_str())
+            == Some("record");
+
+        if !is_record {
+            continue;
+        }
+
+        let fields = extract_collection_fields(defs);
+        if fields.is_empty() {
+            continue;
+        }
+
+        let type_name = nsid_to_type_name(nsid);
+        let field_base_name = nsid_to_join_field_name(nsid);
+
+        // {collection}Created subscription
+        let created_field_name = format!("{}Created", field_base_name);
+        let slice_for_created = slice_uri.clone();
+        let nsid_for_created = nsid.to_string();
+        let type_name_for_created = type_name.clone();
+
+        subscription = subscription.field(SubscriptionField::new(
+            &created_field_name,
+            TypeRef::named_nn(&type_name_for_created),
+            move |_ctx| {
+                let slice_uri = slice_for_created.clone();
+                let collection = nsid_for_created.clone();
+
+                SubscriptionFieldFuture::new(async move {
+                    let mut receiver = PUBSUB.subscribe(&slice_uri).await;
+
+                    let stream = async_stream::stream! {
+                        while let Ok(event) = receiver.recv().await {
+                            // Filter by collection and operation
+                            if event.collection != collection || event.operation != crate::graphql::RecordOperation::Create {
+                                continue;
+                            }
+
+                            // Convert to RecordContainer and yield
+                            let indexed_record = crate::models::IndexedRecord {
+                                uri: event.uri,
+                                cid: event.cid,
+                                did: event.did,
+                                collection: event.collection,
+                                value: event.value,
+                                indexed_at: event.indexed_at,
+                            };
+                            let container = RecordContainer {
+                                record: indexed_record,
+                            };
+                            yield Ok(FieldValue::owned_any(container));
+                        }
+                    };
+
+                    Ok(stream)
+                })
+            },
+        )
+        .description(format!("Subscribe to {} record creation events", nsid)));
+
+        // {collection}Updated subscription
+        let updated_field_name = format!("{}Updated", field_base_name);
+        let slice_for_updated = slice_uri.clone();
+        let nsid_for_updated = nsid.to_string();
+        let type_name_for_updated = type_name.clone();
+
+        subscription = subscription.field(SubscriptionField::new(
+            &updated_field_name,
+            TypeRef::named_nn(&type_name_for_updated),
+            move |_ctx| {
+                let slice_uri = slice_for_updated.clone();
+                let collection = nsid_for_updated.clone();
+
+                SubscriptionFieldFuture::new(async move {
+                    let mut receiver = PUBSUB.subscribe(&slice_uri).await;
+
+                    let stream = async_stream::stream! {
+                        while let Ok(event) = receiver.recv().await {
+                            // Filter by collection and operation
+                            if event.collection != collection || event.operation != crate::graphql::RecordOperation::Update {
+                                continue;
+                            }
+
+                            // Convert to RecordContainer and yield
+                            let indexed_record = crate::models::IndexedRecord {
+                                uri: event.uri,
+                                cid: event.cid,
+                                did: event.did,
+                                collection: event.collection,
+                                value: event.value,
+                                indexed_at: event.indexed_at,
+                            };
+                            let container = RecordContainer {
+                                record: indexed_record,
+                            };
+                            yield Ok(FieldValue::owned_any(container));
+                        }
+                    };
+
+                    Ok(stream)
+                })
+            },
+        )
+        .description(format!("Subscribe to {} record update events", nsid)));
+
+        // {collection}Deleted subscription - returns just the URI string
+        let deleted_field_name = format!("{}Deleted", field_base_name);
+        let slice_for_deleted = slice_uri.clone();
+        let nsid_for_deleted = nsid.to_string();
+
+        subscription = subscription.field(SubscriptionField::new(
+            &deleted_field_name,
+            TypeRef::named_nn(TypeRef::STRING),
+            move |_ctx| {
+                let slice_uri = slice_for_deleted.clone();
+                let collection = nsid_for_deleted.clone();
+
+                SubscriptionFieldFuture::new(async move {
+                    let mut receiver = PUBSUB.subscribe(&slice_uri).await;
+
+                    let stream = async_stream::stream! {
+                        while let Ok(event) = receiver.recv().await {
+                            // Filter by collection and operation
+                            if event.collection != collection || event.operation != crate::graphql::RecordOperation::Delete {
+                                continue;
+                            }
+
+                            // For deletes, just return the URI
+                            yield Ok(FieldValue::value(GraphQLValue::String(event.uri)));
+                        }
+                    };
+
+                    Ok(stream)
+                })
+            },
+        )
+        .description(format!("Subscribe to {} record deletion events. Returns the URI of deleted records.", nsid)));
+    }
+
+    subscription
+}

api/src/jetstream.rs

···
 use crate::cache::{CacheBackend, CacheFactory, SliceCache};
 use crate::database::Database;
 use crate::errors::JetstreamError;
+use crate::graphql::{RecordOperation, RecordUpdateEvent, PUBSUB};
 use crate::jetstream_cursor::PostgresCursorHandler;
 use crate::logging::{LogLevel, Logger};
 use crate::models::{Actor, Record};
···
                                 })),
                                 Some(&slice_uri),
                             );
+
+                            // Broadcast to GraphQL subscribers
+                            let event = RecordUpdateEvent {
+                                uri: uri.clone(),
+                                cid: commit.cid.clone(),
+                                did: did.to_string(),
+                                collection: commit.collection.clone(),
+                                value: commit.record.clone(),
+                                slice_uri: slice_uri.clone(),
+                                indexed_at: record.indexed_at.to_rfc3339(),
+                                operation: if is_insert {
+                                    RecordOperation::Create
+                                } else {
+                                    RecordOperation::Update
+                                },
+                            };
+                            PUBSUB.publish(event).await;
                         }
                         Err(e) => {
                             let message = "Failed to insert/update record";
···
                                 })),
                                 Some(&slice_uri),
                             );
+
+                            // Broadcast to GraphQL subscribers
+                            let event = RecordUpdateEvent {
+                                uri: uri.clone(),
+                                cid: commit.cid.clone(),
+                                did: did.to_string(),
+                                collection: commit.collection.clone(),
+                                value: commit.record.clone(),
+                                slice_uri: slice_uri.clone(),
+                                indexed_at: record.indexed_at.to_rfc3339(),
+                                operation: if is_insert {
+                                    RecordOperation::Create
+                                } else {
+                                    RecordOperation::Update
+                                },
+                            };
+                            PUBSUB.publish(event).await;
                         }
                         Err(e) => {
                             let message = "Failed to insert/update record";
···
                             })),
                             Some(slice_uri),
                         );
+
+                        // Broadcast delete event to GraphQL subscribers
+                        let event = RecordUpdateEvent {
+                            uri: uri.clone(),
+                            cid: String::new(), // No CID for delete events
+                            did: did.to_string(),
+                            collection: commit.collection.clone(),
+                            value: serde_json::json!({}), // Empty value for deletes
+                            slice_uri: slice_uri.clone(),
+                            indexed_at: Utc::now().to_rfc3339(),
+                            operation: RecordOperation::Delete,
+                        };
+                        PUBSUB.publish(event).await;
                     }
 
                     // Check if actor should be cleaned up (no more records)

api/src/main.rs

···
     // Start log cleanup background task
     start_log_cleanup_task(pool.clone());
 
+    // Start GraphQL PubSub cleanup task
+    graphql::pubsub::start_cleanup_task();
+
     // Detect process type from environment (supports both PROCESS_TYPE and FLY_PROCESS_GROUP)
     let process_type = env::var("PROCESS_TYPE")
         .or_else(|_| env::var("FLY_PROCESS_GROUP"))
···
             "/xrpc/network.slices.slice.getSyncSummary",
             get(xrpc::network::slices::slice::get_sync_summary::handler),
         )
-        // GraphQL endpoint
+        // GraphQL endpoints
         .route(
             "/graphql",
             get(graphql::graphql_playground).post(graphql::graphql_handler),
+        )
+        .route(
+            "/graphql/ws",
+            get(graphql::graphql_subscription_handler),
         )
         // Dynamic collection-specific XRPC endpoints (wildcard routes must come last)
         .route(