Hex Reference Architecture
Architecture
┌────────────────────────────────────────┐
│ Orchestration Layer │
│ (Airflow, Dagster, GitHub Actions, │
│ Cron, Custom API) │
├────────────────────────────────────────┤
│ Hex API Client │
│ (Run, Poll, Cancel, List) │
├────────────────────────────────────────┤
│ Hex Platform │
│ ┌──────────┐ ┌───────────────────┐ │
│ │ Projects │ │ Data Connections │ │
│ │ (SQL, │ │ (Snowflake, │ │
│ │ Python, │ │ BigQuery, │ │
│ │ R) │ │ Postgres, etc.) │ │
│ └──────────┘ └───────────────────┘ │
└────────────────────────────────────────┘
Project Structure
hex-orchestrator/
├── src/hex/
│ ├── client.ts # API client
│ ├── orchestrator.ts # Pipeline runner
│ ├── scheduler.ts # Cron-based triggers
│ └── types.ts # TypeScript interfaces
├── src/notify/
│ └── slack.ts # Completion notifications
├── tests/
├── config/
│ └── pipelines.json # Pipeline definitions
└── .env.example
Integration Patterns
| Pattern | When | Tool |
|---|---|---|
| CI-triggered refresh | On deploy | GitHub Actions |
| Scheduled pipeline | Daily/weekly reports | Cron, Airflow |
| On-demand run | User-triggered analysis | API endpoint |
| Orchestrated pipeline | Multi-step ETL | Airflow, Dagster |