Architecture and stored data ​

Orloi captures new activity from the Airtable scope you select, processes it into readable history and derived outputs, and writes those layers to your customer-owned Postgres database.

Your Postgres database is the durable system of record for Orloi output. The dashboard, BI tools, and read-only agent workflows read from the same stored history.

Architecture and trust boundaries ​

flowchart LR
  subgraph airtable["Your Airtable"]
    source["Selected scope"]
  end

  subgraph control["Orloi"]
    capture["Capture new activity"]
  end

  subgraph customer["Your Postgres"]
    raw["Raw activity"]
    readable["Readable activity"]
    derived["Metrics, reports, alerts, and process outputs"]
  end

  ai["Optional configured AI provider"]
  readers["Dashboard, BI, and read-only agents"]

  source --> capture --> raw --> readable --> derived
  readable --> readers
  derived --> readers
  derived -. feature context .-> ai -. result .-> derived

Text alternative: Orloi captures activity from the Airtable scope you select, stores raw activity, creates readable activity and derived outputs in your Postgres database, and makes those layers available to the dashboard, BI tools, and read-only agents. If you enable an AI feature, Orloi sends the required feature context to the configured provider and stores the result in your database.

Your Postgres database remains the system of record for Orloi output. The operating database credential is used for setup, upgrades, and writes; BI tools and agents should use their own restricted read-only role. See Privacy and trust boundary and Use Orloi with AI agents for technical access guidance.

Raw activity ​

Raw activity preserves close-to-source Airtable changes for the selected base and configured scope. It includes the source details needed to understand what changed, such as table, field, and record identifiers, timestamps, action or source information where available, and payload details for the change.

Raw activity is the source-proximate layer for audit, debugging, search, and the derived views below. It is stored in the dedicated orloi schema in your Postgres database.

Readable activity ​

Readable activity is assembled from related raw changes. This compacted history can collapse noisy updates, prefer names over opaque IDs where available, summarize long additions or removals, and make database changes easier for people and downstream tools to interpret.

The distinction is practical: raw activity answers what Orloi received; readable activity answers what those changes mean as a usable history.

Metrics, reports, alerts, and process outputs ​

Orloi derives additional layers from the captured history:

  • Metrics — saved definitions and computed values for operational questions such as new, completed, reopened, stalled, or handed-off work. See Metrics for interpretation of definitions and early history.
  • Reports — daily or weekly operational summaries that can be viewed later, emailed, and inspected from the dashboard.
  • Alerts and signals — findings and patterns that identify where to investigate.
  • Process outputs — process facts, variants, and other dashboard-facing summaries derived from the changelog.

These outputs make the dashboard useful without replacing the underlying raw or readable history.

Optional AI path ​

AI features can use stored operational history to generate reports, summaries, and interpretation. AI is optional: capture, readable history, and deterministic metrics remain useful when AI features are disabled.

When enabled, Orloi sends the context required for the selected feature to its configured provider and stores the resulting insight in your Postgres database. Review Privacy and responsible use before enabling AI for sensitive work.

Capture boundaries ​

Raw activity contains only new activity from the selected tables and fields after activation. Activity outside that scope is not retained, and Orloi does not backfill or reconstruct earlier Airtable history. Capture is asynchronous, so a source change can arrive before its raw event or a derived dashboard, report, or metric reflects it.

The detail depends on what Airtable supplies. Deletion activity may show that a record was deleted without providing its former field values. Linked and computed values, attachment metadata, and source or actor context may be present when included in the payload; collaborator identity is not guaranteed.

Views, interfaces, comments, automation definitions and logs, and attachment files are outside this changelog. Attachment files are not downloaded. Orloi does not modify your existing application tables or write back to Airtable.

Read the stored data ​

Use Data reference for table families, columns, compatibility notes, sensitivity, and schema-version checks. Use the SQL and BI cookbook for bounded queries, BI patterns, investigation, and export guidance.

For detailed data lineage, freshness stages, failure boundaries, and operator checks, see Data lineage and freshness. For raw-event cleanup, see Raw-event retention.