Part IX: Advanced Topics#

At this point you know the language, you know the runtime, and you've probably built something that works. Now comes the part where you make it work well -- or at least understand what's happening underneath so you can reason about why it's slow, why it's not syncing the way you expected, or why your document is eating memory like it's Thanksgiving.

What's In Here#

These chapters go past the basics and into the machinery. Some of this is "how to make things faster" and some of it is "what is the platform doing when you're not looking." Both matter.

1. Performance Optimization#

The practical stuff -- how to size documents, when to index, how formulas actually get evaluated, and when to split one document into many. I've made most of these mistakes myself, so at least the advice is earned.

• Graph Indexing for Relationships - Use assoc/join/traverse to avoid table scans
• Document Sizing - How to right-size your documents
• Query Optimization - Making the most of indexes and query patterns
• Formula Complexity - Understanding lazy evaluation trade-offs
• Memory Management - Working within resource constraints
• Concurrent Connections - Handling many simultaneous users
• When to Split Documents - Architectural decisions for scale

Read: Performance Optimization

2. Graph Indexing#

This one's fun. Precomputed, reactive indexes across tables using assoc, join, and traverse. It turns what would be O(n) table scans into direct lookups, and the indexes update themselves incrementally as data changes.

• Associations and Joins - Declare relationships and feed edges from tables
• Traverse Operator - Follow precomputed graphs in queries
• Nested Table Joins - Cross-table indexing through records with nested tables
• Conditional Edges - Dynamic enable/disable with @maybe
• Practical Patterns - Memberships, tagging, bidirectional relationships

Read: Graph Indexing

3. The Delta Protocol#

How Adama synchronizes state to clients. This is the protocol that makes real-time work -- computing minimal JSON diffs per viewer, accounting for privacy, and shipping them over WebSockets. You can build a lot without understanding the internals here, but when things get weird, this chapter is where you'll end up.

• Delta Concepts - How change detection works
• Message Format - The structure of delta payloads
• Privacy Filtering - Per-viewer delta computation
• Efficient Sync - Minimizing bandwidth usage
• Client Integration - Applying deltas in your application
• Debugging Techniques - Troubleshooting synchronization issues

Read: The Delta Protocol

4. Agentic Behavior Reference#

Everything the platform does on its own, without anyone asking. State machine auto-execution, cron jobs, reactive propagation, document sleep/wake, garbage collection, AI agent tool loops, capacity management -- all the autonomous stuff that makes Adama a living system rather than a passive data store.

• Document-Level Autonomy - State machine auto-execution, cron jobs, reactive propagation, delta sync, message queue drain, service result delivery, replication, AI agent tool loops
• Platform-Level Autonomy - Document sleep/wake cycles, garbage collection, space deletion, dead node detection, storage reporting
• Cluster-Level Autonomy - Gossip protocol, routing table updates, capacity management, load shedding, Prometheus target generation

Read: Agentic Behavior Reference

5. External Integration with Replication#

Documents can't query each other -- that's by design. But you still need leaderboards, search, directories. The replication engine watches expressions inside documents, detects changes via content hashing, and pushes creates/updates/deletes to external services with automatic retry. It's how document isolation coexists with cross-document needs.

• Replication Engine - Automatic change detection, create/update/delete lifecycle with retry
• Cross-Document Indexes - Push data to MySQL for leaderboards, search, and directories
• Record-Level Replication - Per-row sync from tables to external systems
• Integration Patterns - Global directories, analytics pipelines, billing sync

Read: External Integration with Replication

When You'll Want This#

You'll end up here when:

• Your application needs to handle real load and you're wondering where the bottlenecks are
• You have relationship-heavy data and table scans are killing you
• You need cross-document queries (leaderboards, search, directories) and the document-per-entity model feels constraining
• You need to push data into external systems -- databases, billing, analytics
• Something's not syncing right and you need to understand the delta protocol to figure out why
• You want to know what background work the platform is doing so nothing surprises you in production
• You're designing the architecture for something real and need to think about document boundaries

Prerequisites#

Before getting into this, you should be comfortable with:

• Tables, records, and queries (from the Language section)
• Formulas and reactive computation
• Privacy policies and viewer-dependent data
• Basic state machine concepts

If any of those feel shaky, go back to the Language Reference first. This section assumes you've got the fundamentals down.

The architecture makes certain patterns naturally cheap:

• Delta-based sync means large documents with small changes are cheap
• Lazy formulas mean unused computations cost nothing
• Indexed queries mean large tables can be queried efficiently
• Graph indexing means cross-table relationships resolve without scanning
• Replication means document isolation doesn't prevent cross-document queries
• Document isolation means horizontal scaling is straightforward

Start with Performance Optimization and go from there.