name: hex-reference-architecture description: 'Implement Hex reference architecture with best-practice project layout.

Use when designing new Hex integrations, reviewing project structure,

or establishing architecture standards for Hex applications.

Trigger with phrases like "hex architecture", "hex best practices",

"hex project structure", "how to organize hex", "hex layout".

' allowed-tools: Read, Grep version: 1.0.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• hex
• data
• analytics compatibility: Designed for Claude Code

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

Resources

• Hex API
• Airflow Provider
• Orchestration Blog