https://fernandezvara.github.io/backd/docs/development/Recent content in Development on backdHugoen-ushttps://fernandezvara.github.io/backd/docs/development/architecture/Mon, 01 Jan 0001 00:00:00 +0000https://fernandezvara.github.io/backd/docs/development/architecture/<p><code>backd</code> is a single stateless Go service. Apart from the registry built at startup, all state lives in MongoDB, so several identical instances can run side by side.</p> <pre tabindex="0"><code>CONFIG_DIR ──load──▶ registry ──▶ provisioner ──▶ MongoDB │ ▲ HTTP ──▶ handlers ──────┴──▶ storage.Repository ───┘ </code></pre><h2 id="layers">Layers<a class="hd-anchor" href="#layers" aria-hidden="true">#</a> </h2> <table> <thead> <tr> <th>Package</th> <th>Role</th> </tr> </thead> <tbody> <tr> <td><code>internal/settings</code></td> <td>Environment variables → <code>Settings</code></td> </tr> <tr> <td><code>internal/registry</code></td> <td>Immutable realm → database → collection tree, with realm settings (<code>realm.yaml</code>), compiled schemas and field index</td> </tr> <tr> <td><code>internal/templates</code></td> <td>Embedded starter files written by <code>backd template</code></td> </tr> <tr> <td><code>internal/rules</code></td> <td>Compiles the <code>rules:</code> of <code>collection.yaml</code>: expr-lang rules and runs the static checks (guards, roles, fields, <code>now</code>, read rules as filters)</td> </tr> <tr> <td><code>internal/auth</code></td> <td>Storage-neutral identity model (users, identities, sessions), password policy, argon2id hashing with a concurrency cap, sign-up, login and session handling; persistence behind <code>auth.Store</code> (in-memory fake in <code>internal/auth/authtest</code>)</td> </tr> <tr> <td><code>internal/query</code></td> <td>Parses the list query language into <code>storage.Condition</code>s, checking every field and value against the schema</td> </tr> <tr> <td><code>internal/storage</code></td> <td>Backend-neutral <code>Repository</code> interface, <code>Document</code>/<code>Query</code>/<code>Page</code>/<code>Condition</code>/<code>Filter</code> types, <code>Fetch</code> (single reads under a read rule), and the errors <code>ErrNotFound</code>, <code>ErrVersionMismatch</code>, <code>ErrConflict</code> and <code>ErrUnavailable</code></td> </tr> <tr> <td><code>internal/httpapi</code></td> <td>Router, middleware, error envelope, document, <code>/_auth</code> and <code>/_admin</code> handlers, CORS</td> </tr> <tr> <td><code>internal/jsonnum</code></td> <td>Normalizes JSON numbers to int64 or float64</td> </tr> <tr> <td><code>internal/mongodb</code></td> <td>Everything MongoDB-specific: connection, validator translation, provisioner (including realm system databases), <code>Repository</code> and <code>auth.Store</code> implementations</td> </tr> </tbody> </table> <p>No MongoDB driver types cross the <code>storage</code> interface. Another document store (for example Amazon DocumentDB) can be added as a new implementation without touching handlers or validation.</p>https://fernandezvara.github.io/backd/docs/development/contract/Mon, 01 Jan 0001 00:00:00 +0000https://fernandezvara.github.io/backd/docs/development/contract/<p><code>api/openapi.yaml</code> is the contract of the HTTP API, in OpenAPI 3.1. Clients, such as the <a href="../../clients/js/">JavaScript client</a>, are written against it, so the server must never drift from it.</p> <h2 id="what-it-covers">What it covers<a class="hd-anchor" href="#what-it-covers" aria-hidden="true">#</a> </h2> <ul> <li>Every route: health probes, <code>/_auth</code>, <code>/_admin</code> and the generic document routes.</li> <li>Every status an operation documents explicitly, plus a <code>default</code> for errors that can happen anywhere (<code>404</code> for an unknown realm, <code>413</code>, <code>415</code>, <code>500</code>, <code>503</code>).</li> <li>Response bodies, including the error envelope and its closed list of <code>code</code> values.</li> <li>Response headers clients rely on: <code>ETag</code>, <code>Location</code>, <code>Retry-After</code>, <code>WWW-Authenticate</code>, <code>X-Request-ID</code>, and <code>Cache-Control: no-store</code> on account data.</li> <li>Documents as open objects. Their fields depend on each collection&rsquo;s <code>schema.json</code>, but <code>id</code> and <code>_meta</code> are described exactly.</li> </ul> <h2 id="how-its-enforced">How it&rsquo;s enforced<a class="hd-anchor" href="#how-its-enforced" aria-hidden="true">#</a> </h2> <p>Two checks keep the spec honest, and both run in CI.</p>