{"id":31040435,"url":"https://github.com/ccarvalho-eng/helix","last_synced_at":"2025-09-14T08:40:36.214Z","repository":{"id":312145221,"uuid":"1046196918","full_name":"ccarvalho-eng/helix","owner":"ccarvalho-eng","description":"AI agent flows blueprinting","archived":false,"fork":false,"pushed_at":"2025-09-13T06:12:50.000Z","size":717,"stargazers_count":2,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-13T08:23:13.589Z","etag":null,"topics":["ai-agents","ai-agents-framework","airflow","diagramming","diagramming-library","elixir","phoenix-framework","reactjs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ccarvalho-eng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-28T10:32:04.000Z","updated_at":"2025-09-13T06:12:54.000Z","dependencies_parsed_at":"2025-09-05T08:16:06.549Z","dependency_job_id":null,"html_url":"https://github.com/ccarvalho-eng/helix","commit_stats":null,"previous_names":["ccarvalho-eng/helix"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/ccarvalho-eng/helix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccarvalho-eng%2Fhelix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccarvalho-eng%2Fhelix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccarvalho-eng%2Fhelix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccarvalho-eng%2Fhelix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ccarvalho-eng","download_url":"https://codeload.github.com/ccarvalho-eng/helix/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ccarvalho-eng%2Fhelix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275081662,"owners_count":25402336,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-14T02:00:10.474Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-agents-framework","airflow","diagramming","diagramming-library","elixir","phoenix-framework","reactjs"],"created_at":"2025-09-14T08:40:34.525Z","updated_at":"2025-09-14T08:40:36.204Z","avatar_url":"https://github.com/ccarvalho-eng.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🧬 Helix\n\n**Visual AI Agent Workflow Designer**\n\n_Plan, design, and visualize complex multi-agent workflows with a clean drag-and-drop interface._\n\n[![GitHub release](https://img.shields.io/github/v/release/ccarvalho-eng/helix?style=for-the-badge)](https://github.com/ccarvalho-eng/helix/releases)\n[![CI](https://img.shields.io/github/actions/workflow/status/ccarvalho-eng/helix/ci.yml?style=for-the-badge\u0026logo=github-actions)](https://github.com/ccarvalho-eng/helix/actions/workflows/ci.yml)\n[![E2E Tests](https://img.shields.io/github/actions/workflow/status/ccarvalho-eng/helix/nightly-e2e-tests.yml?style=for-the-badge\u0026logo=playwright\u0026label=E2E)](https://github.com/ccarvalho-eng/helix/actions/workflows/nightly-e2e-tests.yml)\n[![codecov](https://img.shields.io/codecov/c/github/ccarvalho-eng/helix?style=for-the-badge\u0026logo=codecov)](https://codecov.io/gh/ccarvalho-eng/helix)\n[![Security](https://img.shields.io/github/actions/workflow/status/ccarvalho-eng/helix/security.yml?style=for-the-badge\u0026logo=security\u0026label=Security)](https://github.com/ccarvalho-eng/helix/actions/workflows/security.yml)\n\n[Features](#-features) • [Getting Started](#-getting-started) • [Architecture](#-architecture) • [Contributing](#-contributing)\n\n---\n\n\u003c/div\u003e\n\n## 🎯 Overview\n\nHelix is a **visual workflow designer for AI agents and multi-agent systems**.\nBuild complex workflows through an intuitive node editor with collaboration, templates, and real-time updates.\n\n\u003e **Note**: Workflows are for **planning \u0026 design only** — not executable yet.\n\n---\n\n## ✨ Features\n\n- **Visual Workflow Design**\n  Drag-and-drop interface with customizable nodes, connections, minimap, and properties panel.\n- **Collaboration**\n  Real-time multi-user editing via Phoenix Channels with last-write-wins synchronization.\n- **Modern UI/UX**\n  Light/dark themes, responsive design, Tailwind styling, robust error boundaries.\n- **Workflow Management**\n  Save, load, duplicate flows, with metadata and local persistence.\n\n---\n\n## 🚀 Getting Started\n\n### Requirements\n\n- Elixir **1.17+**\n- Erlang/OTP **26+**\n- Node.js **18+**\n- PostgreSQL **14+**\n\n### Installation\n\n```bash\n# Clone\ngit clone https://github.com/ccarvalho-eng/helix.git\ncd helix\n\n# Setup\nmix setup\n\n# Start\nmix phx.server\n```\n\nOpen: [http://localhost:4000](http://localhost:4000)\n\n### Development\n\n```bash\n# Tests\nmix test\nnpm test\n\n# Code quality\nmix credo --strict\nnpm run lint  # Must pass with --max-warnings 0\nnpm run typecheck\n\n# E2E tests\nnpm run test:e2e\n\n# Formatting\nmix format\nnpm run prettier\n```\n\n---\n\n## 🛠 Tech Stack\n\n| Layer                 | Stack                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Backend**           | ![Elixir](https://img.shields.io/badge/Elixir-4B275F?logo=elixir\u0026logoColor=white\u0026style=for-the-badge) ![Phoenix](https://img.shields.io/badge/Phoenix-E95420?logo=phoenixframework\u0026logoColor=white\u0026style=for-the-badge) ![PostgreSQL](https://img.shields.io/badge/PostgreSQL-316192?logo=postgresql\u0026logoColor=white\u0026style=for-the-badge)                                                                                                                                                                                         |\n| **Frontend**          | ![React](https://img.shields.io/badge/React-20232A?logo=react\u0026logoColor=61DAFB\u0026style=for-the-badge) ![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript\u0026logoColor=white\u0026style=for-the-badge) ![TailwindCSS](https://img.shields.io/badge/Tailwind_CSS-06B6D4?logo=tailwindcss\u0026logoColor=white\u0026style=for-the-badge) ![Lucide Icons](https://img.shields.io/badge/Lucide-000000?logo=lucide\u0026logoColor=white\u0026style=for-the-badge)                                                                           |\n| **Testing \u0026 Quality** | ![ExUnit](https://img.shields.io/badge/ExUnit-4B275F?logo=elixir\u0026logoColor=white\u0026style=for-the-badge) ![Jest](https://img.shields.io/badge/Jest-C21325?logo=jest\u0026logoColor=white\u0026style=for-the-badge) ![Playwright](https://img.shields.io/badge/Playwright-2EAD33?logo=playwright\u0026logoColor=white\u0026style=for-the-badge) ![Credo](https://img.shields.io/badge/Credo-4B275F?logo=elixir\u0026logoColor=white\u0026style=for-the-badge) ![ESLint](https://img.shields.io/badge/ESLint-4B32C3?logo=eslint\u0026logoColor=white\u0026style=for-the-badge) |\n\n---\n\n## 🏗 Architecture\n\n### System Overview\n\n```mermaid\n%%{init: {'theme':'neutral'}}%%\ngraph TB\n    subgraph \"Client Side\"\n        UA[User A Browser]\n        UB[User B Browser]\n        FEA[React Frontend\u003cbr/\u003eReact Flow + TypeScript]\n        FEB[React Frontend\u003cbr/\u003eReact Flow + TypeScript]\n        LSA[Local Storage\u003cbr/\u003eFlow Data]\n        LSB[Local Storage\u003cbr/\u003eFlow Data]\n\n        UA --\u003e FEA\n        UB --\u003e FEB\n        FEA --\u003e LSA\n        FEB --\u003e LSB\n    end\n\n    subgraph \"Network Layer\"\n        WSA[WebSocket Connection A]\n        WSB[WebSocket Connection B]\n        HTTP[HTTP/REST Requests]\n\n        FEA -.-\u003e|flow_change events| WSA\n        FEB -.-\u003e|flow_change events| WSB\n        WSA -.-\u003e|flow_update events| FEA\n        WSB -.-\u003e|flow_update events| FEB\n        FEA --\u003e|CRUD operations| HTTP\n        FEB --\u003e|CRUD operations| HTTP\n    end\n\n    subgraph \"Phoenix Server\"\n        US[UserSocket\u003cbr/\u003eWebSocket Handler]\n        FC[FlowChannel\u003cbr/\u003ePhoenix Channel]\n        FSM[FlowSessionManager\u003cbr/\u003eGenServer State]\n        PUB[Phoenix.PubSub\u003cbr/\u003eMessage Broadcasting]\n        API[REST API\u003cbr/\u003eFlow CRUD]\n\n        WSA --\u003e US\n        WSB --\u003e US\n        US --\u003e FC\n        FC \u003c--\u003e FSM\n        FSM --\u003e PUB\n        PUB --\u003e FC\n        HTTP --\u003e API\n    end\n\n    subgraph \"Data Layer\"\n        PG[(PostgreSQL\u003cbr/\u003eDatabase)]\n        API --\u003e PG\n    end\n\n    classDef client fill:#e3f2fd,stroke:#1976d2,color:#000\n    classDef network fill:#f3e5f5,stroke:#7b1fa2,color:#000\n    classDef server fill:#e8f5e8,stroke:#388e3c,color:#000\n    classDef database fill:#fff3e0,stroke:#f57c00,color:#000\n    classDef realtime fill:#ffebee,stroke:#d32f2f,color:#000\n\n    class UA,UB,FEA,FEB,LSA,LSB client\n    class WSA,WSB,HTTP network\n    class US,API server\n    class FC,FSM,PUB realtime\n    class PG database\n```\n\n### Real-Time Collaboration Flow\n\n```mermaid\n%%{init: {'theme':'neutral'}}%%\nsequenceDiagram\n    participant UA as 👤 User A\n    participant FA as 🖥️ Frontend A\n    participant WS as 🌐 WebSocket\n    participant FC as 📡 FlowChannel\n    participant FSM as 🧠 FlowSessionManager\n    participant PUB as 📢 Phoenix.PubSub\n    participant FB as 🖥️ Frontend B\n    participant UB as 👤 User B\n\n    UA-\u003e\u003eFA: ✏️ Create/Edit Node\n    FA-\u003e\u003eFA: 💾 Update Local State\n    Note over FA: Debounced (500ms)\n    FA-\u003e\u003eWS: 📤 Send flow_change event\n    WS-\u003e\u003eFC: 📥 Receive flow_change\n    FC-\u003e\u003eFSM: 🚀 broadcast_flow_change()\n    FSM-\u003e\u003eFSM: ⏰ Update last_activity\n    FSM-\u003e\u003ePUB: 📡 Phoenix.PubSub.broadcast\n    PUB-\u003e\u003eFC: 📢 {:flow_change, data}\n    FC-\u003e\u003eWS: 📤 Send flow_update\n    WS-\u003e\u003eFB: 📥 Receive flow_update\n    FB-\u003e\u003eFB: 🔄 Apply remote changes\n    FB-\u003e\u003eUB: ✨ Visual update appears\n\n    Note over FSM: 📋 Manages client sessions\u003cbr/\u003e⏰ Updates activity timestamps\u003cbr/\u003e❌ No conflict resolution\n    Note over PUB: 🚀 Handles message broadcasting\u003cbr/\u003e📡 Topic: \"flow:#{flow_id}\"\n```\n\n### WebSocket Conflict Resolution\n\n```mermaid\n%%{init: {'theme':'neutral'}}%%\nflowchart TD\n    A[Client A: flow_change] --\u003e B{Connection Status}\n    A2[Client B: flow_change\u003cbr/\u003e⚡ Concurrent Event] --\u003e B2{Connection Status}\n\n    B --\u003e|Connected| C[FlowChannel handles A]\n    B --\u003e|Disconnected| D[❌ Event Lost\u003cbr/\u003eNo Queuing]\n\n    B2 --\u003e|Connected| C2[FlowChannel handles B]\n    B2 --\u003e|Disconnected| D2[❌ Event Lost\u003cbr/\u003eNo Queuing]\n\n    C --\u003e E[FlowSessionManager.broadcast_flow_change]\n    C2 --\u003e E2[FlowSessionManager.broadcast_flow_change]\n\n    E --\u003e F{Active Session?}\n    E2 --\u003e F2{Active Session?}\n\n    F --\u003e|Yes| G[✅ Broadcast A to all clients\u003cbr/\u003eLast-Write-Wins]\n    F --\u003e|No| H[⚠️ Log: No session found]\n\n    F2 --\u003e|Yes| G2[✅ Broadcast B to all clients\u003cbr/\u003e⚡ Overwrites A's changes]\n    F2 --\u003e|No| H2[⚠️ Log: No session found]\n\n    G --\u003e I[Phoenix.PubSub broadcast]\n    G2 --\u003e I2[Phoenix.PubSub broadcast]\n    H --\u003e K[❌ Changes discarded]\n    H2 --\u003e K2[❌ Changes discarded]\n\n    I --\u003e J[All clients receive A]\n    I2 --\u003e J2[All clients receive B\u003cbr/\u003e🔄 Conflicts possible]\n\n    J --\u003e L[Frontend applies A]\n    J2 --\u003e L2[Frontend applies B\u003cbr/\u003eMay overwrite A]\n\n    subgraph \"Connection Handling\"\n        M[Connection Lost] --\u003e N{Reconnection?}\n        N --\u003e|Success| O[Auto-rejoin channel\u003cbr/\u003e🔄 No state sync]\n        N --\u003e|Failed| P[Exponential backoff]\n        P --\u003e Q{Max attempts\u003cbr/\u003e10 retries?}\n        Q --\u003e|No| R[Wait + retry]\n        Q --\u003e|Yes| S[❌ Give up]\n        R --\u003e N\n        O --\u003e T[Resume sending events]\n    end\n\n    classDef error fill:#ffebee,stroke:#d32f2f,color:#000\n    classDef success fill:#e8f5e8,stroke:#388e3c,color:#000\n    classDef warning fill:#fff3e0,stroke:#f57c00,color:#000\n    classDef conflict fill:#f3e5f5,stroke:#7b1fa2,color:#000\n    classDef info fill:#e3f2fd,stroke:#1976d2,color:#000\n\n    class D,D2,H,H2,K,K2,S error\n    class G,G2,I,I2,O,T success\n    class P,R warning\n    class A2,G2,I2,J2,L2 conflict\n    class F,F2,N,Q info\n```\n\n**Conflict Resolution Strategy:**\n\n- ❌ **No validation**: All changes are accepted and broadcasted immediately\n- ⚡ **Last-Write-Wins**: Concurrent changes overwrite each other\n- 📡 **No queuing**: Disconnected events are lost (not queued for later)\n- 🔄 **No state sync**: Reconnected clients don't get missed changes\n- ⚠️ **Session-based**: Only active sessions (with connected clients) receive broadcasts\n\n- Real-time collaboration through WebSockets + Phoenix Channels\n- React Flow for node-based workflow design\n- GenServer-based session management with last-write-wins synchronization\n- RESTful API for workflow CRUD\n\n---\n\n## 🤝 Contributing\n\n1. Fork \u0026 branch (`git checkout -b feature/amazing-feature`)\n2. Add changes + tests\n3. Run full test suite (`npm run test:all \u0026\u0026 mix test`)\n4. Commit using [Conventional Commits](https://conventionalcommits.org/)\n5. Open a pull request\n\nSee [Contributing Guide](CONTRIBUTING.md) for details.\n\n---\n\n## 📝 License\n\nApache 2.0 — see [LICENSE](LICENSE).\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n⭐ If you find Helix useful, [give it a star](https://github.com/ccarvalho-eng/helix/stargazers).\n\nBuilt with ❤️ for the AI community.\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fccarvalho-eng%2Fhelix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fccarvalho-eng%2Fhelix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fccarvalho-eng%2Fhelix/lists"}