# Hex Reference Architecture

> '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". '

- Skill: `jeremylongshore/hex-reference-architecture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jeremylongshore/hex-reference-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jeremylongshore/hex-reference-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jeremylongshore (https://skillmd.com/u/jeremylongshore)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/jeremylongshore/hex-reference-architecture

---


# 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 |

## Resources

- [Hex API](https://learn.hex.tech/docs/api/api-overview)
- [Airflow Provider](https://github.com/hex-inc/airflow-provider-hex)
- [Orchestration Blog](https://hex.tech/blog/announcing-orchestration-public-api/)

---

**Source:** [`jeremylongshore/claude-code-plugins-plus-skills`](https://github.com/jeremylongshore/claude-code-plugins-plus-skills) → `plugins/saas-packs/hex-pack/skills/hex-reference-architecture/SKILL.md`