{"id":13879297,"url":"https://github.com/rails-engine/flow_core","last_synced_at":"2025-04-24T02:27:55.029Z","repository":{"id":41824259,"uuid":"241197004","full_name":"rails-engine/flow_core","owner":"rails-engine","description":"FlowCore is a Rails engine to help you build your automation or business process application.","archived":false,"fork":false,"pushed_at":"2024-09-27T08:02:02.000Z","size":928,"stargazers_count":179,"open_issues_count":13,"forks_count":22,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-30T06:06:44.631Z","etag":null,"topics":["automation","bpm","business-process","petri-net","rails-engine","ruby","ruby-on-rails","workflow-engine"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rails-engine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"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}},"created_at":"2020-02-17T20:04:51.000Z","updated_at":"2025-03-24T14:26:34.000Z","dependencies_parsed_at":"2023-02-12T01:16:06.230Z","dependency_job_id":"645cc359-cab8-4b09-98a7-a5fd458605c7","html_url":"https://github.com/rails-engine/flow_core","commit_stats":{"total_commits":56,"total_committers":2,"mean_commits":28.0,"dds":0.0535714285714286,"last_synced_commit":"1de99904476510b78f912fbf3bfd66d63ee1c245"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rails-engine%2Fflow_core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rails-engine%2Fflow_core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rails-engine%2Fflow_core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rails-engine%2Fflow_core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rails-engine","download_url":"https://codeload.github.com/rails-engine/flow_core/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250547369,"owners_count":21448480,"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","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":["automation","bpm","business-process","petri-net","rails-engine","ruby","ruby-on-rails","workflow-engine"],"created_at":"2024-08-06T08:02:16.553Z","updated_at":"2025-04-24T02:27:54.998Z","avatar_url":"https://github.com/rails-engine.png","language":"Ruby","readme":"Flow Core\n===\n\n\u003e FlowCore is ready for open reviewing, but it haven't tested in production yet,\n\u003e any help are most welcome, breaking change is acceptable.\n\n[中文介绍](README.zh-CN.md)\n\nFlowCore is a Rails engine to help you build your automation or business process application.\n\nFlowCore modeling workflow with WorkflowNet (a special case of PetriNet) theory which is a generalisation of automata theory such that the concept of concurrently occurring events can be expressed.\n\nYou should try FlowCore if you need:\n\n- Working on BPM, OA, CRM or other similar products\n- Working on Airflow-or-n8n-like automation product\n- Embeds in your Rails app, interact your codebase directly\n- User defined workflow\n- Jobs have dependent relationships, may running in different stages\n\n## Features\n\n### Support all databases which based on ActiveRecord\n\nAll persistent data are present as ActiveRecord model and not use any DB-specific feature.\n\n### Easy to extend \u0026 hack\n\nFlowCore basically followed best practice of Rails engine,\nyou can extend as [Rails Guides](https://guides.rubyonrails.org/engines.html#improving-engine-functionality) suggests.\n\nYour app-specific workflow triggers, and guards can be extended via [Single Table Inheritance](https://guides.rubyonrails.org/association_basics.html#single-table-inheritance)\n\nFlowCore also provides callbacks for triggers (which control behavior of a transition) covered whole task lifecycle.\n\n### Petri-net based\n\n[Petri-net](https://en.wikipedia.org/wiki/Petri_net) is a technique for description and analysis of concurrent systems.\n\nFlowCore choose its special type called [Workflow-net](http://mlwiki.org/index.php/Workflow_Nets) to expressing workflow.\n\nCompared to more popular activity-based workflow definitions (e.g BPMN),\nPetri-net has only few rules but could express very complex case.\n\nCheck [workflow patterns](http://workflowpatterns.com) to learn how to use Petri-net expressing workflows.\n\n### Basic workflow checking.\n\nA workflow should be verified first before running it.\n\nFlowCore provides the mechanism to help to prevent unexpected error on instance running\n\n\u003e This is the hard work and help wanted\n\u003e Workflow-net has [soundness](http://mlwiki.org/index.php/Workflow_Soundness) checking but I don't know how to implement it\n\n### Interfaces and abstractions to integrate your business\n\nFlowCore separate app-world and engine-world using interfaces and abstract classes,\nbasically you no need to know Workflow-net internal works.\n\n### Runtime error and suspend support\n\nFlowCore provides necessary columns and event callbacks for runtime error and suspend.\n\n### A DSL to simplify workflow creation\n\nFlowCore provides a powerful DSL for creating workflow.\n\n## Demo\n\n**You need to install Graphviz first**\n\nClone the repository.\n\n```sh\n$ git clone https://github.com/rails-engine/flow_core.git\n```\n\nChange directory\n\n```sh\n$ cd flow_core\n```\n\nRun bundler\n\n```sh\n$ bundle install\n```\n\nPreparing database\n\n```sh\n$ bin/rails db:migrate\n```\n\nImport sample workflow\n\n```sh\n$ bin/rails db:seed\n```\n\nBuild Script Core\n\n```sh\n$ bin/rails app:script_core:engine:build\n$ bin/rails app:script_core:engine:compile_lib\n```\n\nStart the Rails server\n\n```sh\n$ bin/rails s\n```\n\nOpen your browser, and visit `http://localhost:3000`\n\n## Design\n\nArchitecture:\n\n![Architecture](guides/assets/architecture.en.svg)\n\nBasic design based on [An activity based Workflow Engine for PHP By Tony Marston](https://www.tonymarston.net/php-mysql/workflow.html).\n\nSome notable:\n\n- Arc: The line to connecting a Place and a Transition\n- ArcGuard: The matcher to decide the arc is passable,\n            it's an base class that you can extend it for your own purpose.\n- Task: A stateful record to present current workflow instance work,\n        and can reference a `TaskExecutable` through Rails polymorphic-reference.\n        It finish means the transition is done and can moving on.\n- TaskExecutable: An interface for binding App task and FlowCore Task.\n- TransitionTrigger: It controls the behavior of a Transition,\n                     it's an base class that you can extend it for your own purpose,\n                     best place for implementing business.\n\n### Lifecycle of Task\n\n- `created` Task created by a Petri-net Token\n- `enabled` Transit to this stage when next transition requirement fulfilled\n    - Best chance to create app task (your custom task for business) in `TransitionTrigger#on_task_enabled`\n- `finished` Normal ending\n    - Require app task finished first (if bind)\n- `terminated` Task killed by instance (e.g Instance cancelled) or other race condition task\n\n![Life cycle of workflow instance](guides/assets/instance_lifecycle.en.svg)\n\n### Why \"core\"\n\nBecause it's not aim to \"out-of-box\",\nsome gem like Devise giving developer an out-of-box experience, that's awesome,\nbut on the other hand, it also introducing a very complex abstraction that may hard to understanding how it works,\nespecially when you attempting to customize it.\n\nI believe that the gem is tightly coupled with features that face to end users directly,\nso having a good customizability and easy to understanding are of the most concern,\nso I just wanna give you a domain framework that you can build your own that just fitting your need,\nand you shall have fully control and without any unnecessary abstraction.\n\n## TODO / Help wanted\n\n- Document\n- Test\n- Activity-based to Petri-net mapping that will possible to integrate to existing visual editors (with some modification),\n  see \u003chttps://www.researchgate.net/figure/The-mapping-between-BPMN-and-Petri-nets_tbl2_221250389\u003e for understanding.\n- More efficient and powerful workflow definition checking\n- Grammar and naming correction (I'm not English native-speaker)\n\n## Usage\n\n\u003e WIP\n\n## Requirement\n\n- Rails 6.0+\n- Ruby 2.5+\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem \"flow_core\"\n```\n\nOr you may want to include the gem directly from GitHub:\n\n```ruby\ngem 'flow_core', github: 'rails-engine/flow_core'\n```\n\nAnd then execute:\n\n```bash\n$ bundle\n```\n\nAnd then execute:\n\n```bash\n$ rails flow_core_engine:install:migrations\n```\n\nAnd then execute:\n\n```bash\n$ rails db:migrate\n```\n\n## References\n\n- [hooopo/petri_flow](https://github.com/hooopo/petri_flow) (my partner's version, we share the same basis)\n- \u003chttp://mlwiki.org/index.php/Petri_Nets\u003e\n- \u003chttps://www.tonymarston.net/php-mysql/workflow.html\u003e\n- \u003chttp://workflowpatterns.com/\u003e\n\n## Contributing\n\nBug report or pull request are welcome.\n\n### Make a pull request\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\nPlease write unit test with your code if necessary.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","funding_links":[],"categories":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frails-engine%2Fflow_core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frails-engine%2Fflow_core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frails-engine%2Fflow_core/lists"}