Architecture

PullPush is a universal, agent-native integration runtime. Teams and AI agents can build, edit, test, and publish connectors, mappings, transformations, and workflows. AI helps at build time; the runtime stays predictable, observable, and safe — no LLM in the hot path.

The 4 layers

1. Universal connector layer — Connect to any system with an API, webhook, file export, database, or custom endpoint.
2. AI build layer — Use the built-in AI agent to generate or modify connectors, mappings, and transform logic.
3. Deterministic runtime layer — Run syncs through a predictable runtime with idempotency, retries, ordering, rate limits, circuit breakers, DLQ, replay protection, and audit logs.
4. Safety layer — Preview changes, run in shadow mode, compare output, reconcile state, and only go live when the flow is safe.

Canonical data model

The canonical model is the hub between any two systems:

Source A ──→ Canonical ──→ Destination X
Source B ──→ Canonical ──→ Destination Y
Source C ──→ Canonical ──→ Destination Z

Every connector maps its native data structure to canonical types (stocklevel, order, product, etc.). This means adding a new source automatically works with every existing destination — and vice versa.

Pipeline stages

1. Ingest

ingestEvent() is a single transactional operation:

• Writes the event to the database
• Writes to the outbox table
• Enqueues the job for processing

All three happen in one database transaction — if any fails, nothing is committed.

2. Poll

Each connection has a distributed lock. The poller:

• Acquires the lock (preventing duplicate processing)
• Fetches pending events from the outbox
• Groups them by flow and canonical key
• Hands them to the delivery stage

3. Deliver

Delivery enforces per-key ordering: events for the same SKU or order ID are processed sequentially, even under high concurrency. This prevents race conditions where an older stock value overwrites a newer one.

Reliability features at this stage:

• Circuit breaker — automatic backoff when the destination API is failing
• 10x exponential retry — increasing delays between retry attempts
• Idempotent delivery — duplicate events are safely deduplicated
• Dead-letter queue — events that exhaust all retries are stored for investigation

Connector types

All three types produce canonical events and consume canonical payloads — the pipeline doesn't know or care which type created the connector.

Technology stack

• Language: TypeScript (monorepo with pnpm + Turborepo)
• Framework: Next.js 15 (App Router, React 19)
• Database: PostgreSQL 16
• Cache/Queue: Redis 7 + BullMQ
• ORM: Prisma
• Auth: better-auth
• Reverse proxy: Caddy (TLS)
• Process management: systemd
• AI tools: 43 MCP tools with 137 integration actions across 16 domain routers