Integrations Architecture

This article explains how PlaneConnection connects with external services, the data flow patterns used, and the architectural decisions behind the integration framework.

​

Integration philosophy

PlaneConnection integrates with industry-standard aviation software across flight planning, accounting, maintenance, fuel management, communications, and CRM. The integration architecture follows three principles:

1. Bidirectional where possible. Data flows in both directions to avoid manual re-entry. Trips created in PlaneConnection appear in ForeFlight; payments recorded in QuickBooks sync back.
2. Operator-controlled. Admins choose which integrations to enable, which data types to sync, and how frequently. No integration activates without explicit configuration.
3. Resilient to failures. Sync failures are logged and retried. Temporary outages in a third-party service do not block operations in PlaneConnection.

​

Integration categories

​

Data flow patterns

​

OAuth-based integrations

QuickBooks and Stripe use OAuth 2.0 for authorization. The flow:

1. Admin clicks Connect in PlaneConnection.
2. PlaneConnection redirects to the provider’s authorization page.
3. The provider authenticates the user and grants access.
4. PlaneConnection receives an access token and refresh token.
5. Tokens are stored encrypted and refreshed automatically before expiry.

OAuth tokens are scoped to the minimum required permissions. Token refresh happens transparently without admin intervention.

​

API key integrations

ForeFlight, TaxxAll, and most maintenance integrations use API keys. The admin provides the key during setup, and PlaneConnection uses it for all subsequent API calls.

​

Webhook integrations

Webhooks provide real-time event delivery. PlaneConnection supports both:

• Outbound webhooks — PlaneConnection pushes events to external systems (configurable per event type).
• Inbound webhooks — external systems push data to PlaneConnection (e.g., Avinode marketplace events).

Outbound webhook payloads are signed with HMAC-SHA256 using a shared secret configured during setup.

​

Sync architecture

​

Scheduled sync

Most integrations use scheduled sync with configurable frequency:

​

Conflict resolution

When bidirectional sync creates conflicting records:

1. Last-write wins for most data types. The most recently updated record takes precedence.
2. Manual resolution for financial data. Conflicting invoice or payment records are flagged for admin review.
3. Append-only for safety data. Safety reports and events are never overwritten by external sync.

​

Error handling

Sync errors are handled with retry logic:

​

Integration settings locations

Integrations are configured in two locations depending on the module: This separation reflects the different permission requirements: ops integrations require the Admin role, safety integrations require the Safety Manager role, and billing requires the Owner or Admin role.

​

Data privacy and integrations

Integration data handling follows PlaneConnection’s data privacy framework:

• Minimum data transfer. Only the data types enabled by the admin are synced.
• No PII in webhooks. Outbound webhook payloads use internal IDs, not personally identifiable information.
• Encrypted at rest. API keys, OAuth tokens, and webhook secrets are encrypted in the database.
• Audit trail. All sync operations are logged with timestamps, record counts, and error details.

For the complete privacy framework, see Data Privacy.

​

Related