> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.orbitdev.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Audience Engine Architecture: Data Flow and Trust Boundaries

> How Orbit Audience Engine routes requests from React surfaces through Supabase to PostgreSQL functions and the advertising-api Edge Function with deterministic policy enforcement.

Orbit Audience Engine is a privacy boundary around advertising, not a user-data export product. React surfaces call Supabase with the user's existing authenticated session. High-trust work, including delivery, charging, redirects, and conversions, runs inside PostgreSQL functions or the `advertising-api` Edge Function.

## Data flow

The flow moves from consent through classification to impression, redirect, and optional conversion. Each stage enforces a specific trust boundary.

```mermaid theme={"dark"}
flowchart LR
    A[React surface] -->|authenticated session| B[Supabase Data API]
    B --> C[Consent check]
    C --> D[Minimized event classification]
    D --> E[Sensitive-category filter]
    E --> F[Decaying interest score]
    F --> G[Minimum-size segment]
    G --> H[Approved campaign auction]
    H --> I[Rendered impression]
    I --> J[Safe redirect]
    J --> K[Optional idempotent conversion]
    K --> L[Aggregate advertiser reporting]
```

## Trust boundaries

React surfaces never perform high-trust operations. The browser role is limited to reading approved, aggregated results. Any operation that charges an advertiser, selects an ad, or processes a click must run inside the database or the Edge Function.

| Layer | Responsibility | Trust level |
| - | - | - |
| React surface | Render UI, collect consent, emit minimized events | Low |
| Supabase Data API | Authenticated session routing | Medium |
| PostgreSQL functions | `select_ad`, billing RPCs, interest scoring | High |
| `advertising-api` Edge Function | Click validation, redirect, conversion ingestion | High |

## Policy helpers

`src/lib/audience-engine.ts` contains shared deterministic policy helpers. These utilities standardize how the system evaluates consent, schedule, targeting, budget, and frequency caps. They are imported by both database functions and the Edge Function so policy behavior stays consistent across surfaces.

## Ad selection enforcement

`select_ad` enforces the full policy set inside the database:

* Plan eligibility (ad-supported plans only)
* Consent state (personalized or non-personalized)
* Campaign schedule, approval, and budget
* Targeting rules (country, device, placement)
* Frequency caps (daily and weekly per user)
* Segment qualification (for personalized campaigns)

A row lock protects the winning campaign during selection to prevent race conditions in spend accounting.

## Advertiser access rules

Advertisers can read their own organization resources, such as campaigns, creatives, and balances. They cannot select user interests or event rows. Identifiable tables have no advertiser-facing policies.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.