Getting started

backd is an open-source (MIT), config-driven backend: one stateless Go service over MongoDB. You declare realms, databases and collections as files on disk (a JSON Schema per collection, optional indexes and access rules) and backd serves a schema-validated, queryable REST API for them, with built-in users and sessions, API keys, an admin API, and server-side functions for the logic clients can’t be trusted with.

Core concepts:

flowchart LR
    subgraph realm["realm — where you manage the data's security (realm.yaml)"]
        direction LR
        subgraph model["data model"]
            direction LR
            db["database
MongoDB {realm}__{database}"]
            col["collection
MongoDB collection"]
            doc["document
JSON + _meta.id · _meta.owner · _meta.org"]
            db --> col --> doc
        end
        subgraph features["features"]
            direction TB
            auth["users · sessions · API keys · organizations
one sign-in for the whole realm"]
            guards["schema.json validates · indexes.json · collection.yaml rules"]
            fn["functions — JS/TS
sync · jobs · cron · webhooks · triggers"]
            notif["email & push
realm templates, delivery functions"]
            rt["realtime
the changes a caller may read, streamed"]
        end
        guards -.guards.-> col
        rt -.streams.-> doc
        fn -.sends.-> notif
    end

• A realm is where you manage the data’s security — the authority everything inside shares. Users, sessions, API keys, organizations, email templates and secrets belong to one realm, so a realm can be a whole application, or a group of applications that share the same users and get single sign-on across their databases, or a part of an app you want apart by design (a public area next to a private one). Nothing crosses the boundary: the users of one realm never sign in to another, so one backd instance can safely serve several unrelated realms. realm.yaml holds the realm’s settings.
• A database groups a realm’s collections. Split them however it helps: main for the app’s data, another for notifications or logs. It is stored as the MongoDB database <realm>__<database>, so anything that speaks MongoDB sees the data laid out plainly.
• A collection holds documents of one shape. Its schema.json validates every write, indexes.json declares the indexes and collection.yaml says who may read, write or delete. It is stored as one MongoDB collection.
• A document is a JSON object in a collection: your fields, plus a server-owned _meta.id and _meta carrying timestamps, the owner, and the organization and team when they apply.
• Users, sessions, API keys and organizations belong to the realm: one sign-in reaches every database in it, with brute-force protection, invitations, a second factor and consents.
• Functions are JS/TS in isolated Deno processes — sync calls, background jobs, cron, webhooks and triggers — for the logic clients can’t be trusted with.
• Email and push use the realm’s templates and send through delivery functions you write.
• Realtime streams each caller the changes their rules let them read.

On disk, it is a tree of folders. A realm is a folder with a realm.yaml; every folder in it is a database, except _realm, which holds what the realm shows and configures (emails, pages, push and consent texts, app configuration) rather than data:

config/                         CONFIG_DIR
└── shop/                       a realm
    ├── realm.yaml              its settings: users, roles, sign-in, email, storage
    ├── _realm/                 email, pages, push, consents, compliance, config
    └── main/                   a database
        ├── orders/             a collection
        │   ├── schema.json     what a document may contain
        │   ├── indexes.json    its indexes
        │   └── collection.yaml who may read and write, files, triggers
        └── _functions/         server-side functions

Data model explains each file.

Who reads what#

The documentation has three sections, one per role. Pick yours and stay in it: each links to the others only where you need them.

Something not working? Troubleshooting lists the messages you are most likely to meet and what they mean.

What you get#

The documentation home lists the features, and Is backd for you? says what it does not do. This page is only the concepts above.

Where to go next#