Documentation
Start with the overview and how to run Araldo. The API is described by its OpenAPI contract; the decision records explain why it works the way it does.
Start
Reference
Decisions
- ADR 0001: Araldo is a distribution API for developers; callers bring the content
- ADR 0002: One module, one binary, Postgres only, a fixed layout
- ADR 0003: AGPL-3.0-or-later for the server; permissive licenses for clients
- ADR 0004: Orgs are the tenant boundary; brands group channels; four roles and optional approvals
- ADR 0005: A contract-first API with Stripe-style conventions
- ADR 0006: Every org has a test mode that can never post publicly
- ADR 0007: Passwords, passkeys and TOTP built in; MFA can be required per org
- ADR 0008: Secrets are envelope-encrypted per org; the master keys never touch the database
- ADR 0009: Platforms are adapters; developer app credentials live in the database
- ADR 0010: Templates are versioned Go text/templates with a JSON Schema and per-platform bodies
- ADR 0011: Publishing is an outbox with leases, and it never double-posts silently
- ADR 0012: Events are written in the same transaction; webhooks are signed and retried
- ADR 0013: Built-in encrypted backups that the server itself cannot read
- ADR 0014: OpenTelemetry and slog, with no secrets or unpublished content
- ADR 0015: A server-rendered dashboard embedded in the binary
- ADR 0016: Tag links with UTM parameters at render time; leave clicks to web analytics
- ADR 0017: Images are uploaded once, checked against every platform's rules, and stored in Postgres unless S3 is configured
- ADR 0018: Read each published post's engagement on a fixed schedule and keep every reading
- ADR 0019: The API manages everything a declarative tool needs; admin powers are explicit-only scopes
- ADR 0020: An MCP server in the binary, as a client of the public API
- ADR 0021: Channels connect with OAuth through an org's developer apps; images reach platforms by signed links
- ADR 0022: A post takes its publishing slot when it is approved, and posts can be moved
- ADR 0023: Paid promotion on any network, with spend that cannot exceed a cap
- ADR 0024: Newsletters are designed and scheduled in Araldo and sent by the email provider, which owns the list
- ADR 0025: Web analytics are provider adapters that report visits and signups by Araldo's own link tags
- ADR 0026: A brand's report is computed on demand from what Araldo already reads, one period at a time
- ADR 0027: Images too big for a platform are resized for it, and video is media stored in object storage
- ADR 0028: The CLI is an API client, modeled on `gh`; only server administration touches the database
- ADR 0029: Migrations work with the release still running, and a test enforces it
- ADR 0030: Install-wide developer apps, offered to every org beside its own
- ADR 0031: An operator API, org limits and status, and links out for accounts and billing
- ADR 0032: A request log, for the org's developers
- ADR 0033: OIDC single sign-on, by verified domain
- ADR 0034: Notifications, in the dashboard and by email