overview introduction

The Adama Programming Guide

I built Adama because I wanted to make board games online and everything about the existing stack made me want to scream. What came out of that frustration is a programming language and runtime that collapses the entire backend -- database, server, real-time sync, privacy enforcement -- into a single living document.

What is Adama?

At heart, Adama fuses three ideas that normally live in separate zip codes:

  1. A Reactive Spreadsheet - Like Excel, values automatically update when their dependencies change
  2. A Built-in Database - Tables, records, and queries are language primitives
  3. A Real-time Webserver - Every document is automatically accessible via WebSocket and HTTP

Think of it as infrastructure that brings people together. Multiplayer games, collaborative editors, real-time dashboards -- anywhere you need multiple humans looking at shared state without losing their minds (or yours) managing synchronization.

Learning Paths

Pick based on where you are:

New to Adama?

Start here to build the mental model:

  1. What is Adama? - The mental model
  2. Philosophy - Why Adama exists
  3. How It Works - Architecture overview

Ready to Build?

Jump in and get your hands dirty:

  1. Installation - Get set up
  2. Five-Minute Tour - See Adama in action
  3. First Application - Build something real

Learning the Language?

Work through it systematically:

  1. Language Fundamentals - Syntax basics
  2. Types - The type system
  3. Records and Messages - Data structures
  4. Tables and Queries - Built-in database
  5. Formulas - Reactive programming
  6. Privacy - Access control
  7. Channels - Client communication
  8. State Machines - Async workflows

Core Principles

Privacy First

Every field in Adama has a visibility modifier. Privacy isn't something you bolt on after the fact and hope you didn't miss a spot -- it's enforced at compile time. Each connected client sees only what they're authorized to see. Period.

Reactive by Default

When state changes, all dependent computations update automatically. Connected clients receive only the deltas. No polling. No manual invalidation. No "did I forget to notify someone?"

Durable Execution

State machines in Adama survive server restarts. If a document is waiting for user input when the server crashes, it resumes exactly where it left off. The await can span days -- that's not a bug, it's the whole point.

Single Point of Truth

Each Adama document is authoritative. There's no caching layer to invalidate, no replica to sync. The document IS the truth. This sounds simple, but it eliminates an absurd number of consistency bugs.

Example: A Simple Counter

Here's what Adama looks like:

// A public counter visible to all connected clients
public int count = 0;

// Allow anyone to connect
@connected {
  return true;
}

// A message type for increment requests
message Increment { }

// A channel that handles increment messages
channel increment(Increment msg) {
  count++;
}

This document:

  • Persists the counter value automatically
  • Syncs to all connected clients in real-time
  • Validates messages at compile time
  • Handles any number of concurrent users

That's the whole backend. No database setup, no WebSocket boilerplate, no state synchronization code. Just the logic.

Getting Help

  • GitHub Issues: Report bugs or request features
  • Source Code: Explore the implementation
  • Examples: Study working applications

Dive in with What is Adama?

Next Foundations