{"id":28150612,"url":"https://github.com/flow-storm/flow-storm-flowbook-plugin","last_synced_at":"2025-07-05T01:02:05.722Z","repository":{"id":285969735,"uuid":"959938031","full_name":"flow-storm/flow-storm-flowbook-plugin","owner":"flow-storm","description":"A FlowStorm plugin for timelines serialization/replaying","archived":false,"fork":false,"pushed_at":"2025-04-17T15:23:52.000Z","size":794,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-14T02:06:33.474Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flow-storm.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2025-04-03T15:39:46.000Z","updated_at":"2025-05-04T08:22:03.000Z","dependencies_parsed_at":"2025-04-03T16:37:03.385Z","dependency_job_id":"58b0100b-68a2-4109-9948-4c158f534691","html_url":"https://github.com/flow-storm/flow-storm-flowbook-plugin","commit_stats":null,"previous_names":["flow-storm/flow-storm-serde-plugin","flow-storm/flow-storm-flowbook-plugin"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/flow-storm/flow-storm-flowbook-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flow-storm%2Fflow-storm-flowbook-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flow-storm%2Fflow-storm-flowbook-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flow-storm%2Fflow-storm-flowbook-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flow-storm%2Fflow-storm-flowbook-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flow-storm","download_url":"https://codeload.github.com/flow-storm/flow-storm-flowbook-plugin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flow-storm%2Fflow-storm-flowbook-plugin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259812603,"owners_count":22915167,"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":[],"created_at":"2025-05-15T03:14:13.491Z","updated_at":"2025-07-05T01:02:05.683Z","avatar_url":"https://github.com/flow-storm.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FlowStorm flowbook plugin\n\n![demo](./images/plugin-demo-0.png)\n![demo](./images/plugin-demo-1.png)\n\nThe flowbook plugin allows you to store and replay your flows with an optional \"flowbook\", which\nis a notebook that supports links to your recordings you can use to explain a flow.\n\n**Note: this is still in a experimental phase!**\n**Requires FlowStorm \u003e= 4.4.0**\n\n# Setup\n\nIn your deps.edn (same can be done with lein profiles) create an alias like \n\n```clojure\n{...\n :aliases\n {...\n  :fs-flowbook-plugin\n  {:extra-deps {com.github.flow-storm/flow-storm-flowbook-plugin {:mvn/version \"1.0.0-alpha\"}} ;; check for the latest here\n   :jvm-opts [\"-Dflowstorm.plugins.namespaces.flowbookPlugin=flow-storm.plugins.flowbook.all\"]}}}\n```\n[![Clojars Project](https://img.shields.io/clojars/v/com.github.flow-storm/flow-storm-flowbook-plugin.svg)](https://clojars.org/com.github.flow-storm/flow-storm-flowbook-plugin) \n\nThen, in your projects, just make sure you start your repl with the `:fs-flowbook-plugin` alias.\n\n# Usage\n\n## Saving flows\n\nSaving your flows is pretty straight forward. Go to the `Flowbook` plugin tab and click `Save flowbook`. \nA dialog should popup asking for a .edn file to save it in. You don't need it but it is probably better to \ncreate a folder per flowbook, since saving will create more than one file.\n\nFor saving the flows, this plugin needs to serialize all your values, which is not always possible, so\ncheck out the next section for the current strategy.\n\nLet's say you are saving your flows in my-flows.edn, the action of saving the flowbook will create :\n\n    - the main my-flows.edn file which points to the rest of the files\n    - my-flows-values.ser, a serialization of all the values involved in the flows\n    - my-flows-forms.ser, a serialization of all the source code forms needed\n    - my-flows-flowbook.html, which is the notebook you can edit\n    - for each thread(timeline) my-flows-flow-[FLOW_ID]-thread[THREAD_ID]-timeline.ser, containing the tracing\n    - [optionally] a my-flows-flow-[FLOW_ID]-total-order-timeline.ser per flow if your flows contain one.\n    \nAll your bookmarks will also be saved. If there are any bookmarks, anchors will be automatically added to the \nmy-flows-flowbook.html file.\n\nWhen serialization is done you will get a report of all the classes that couldn't be serialized, so if you are interested,\nyou can extend datafy on them.\n\n### Serialization\n\nThe current value serialization strategy is to datafy everything and only store value representations made of clojure data.\nFor this, it will pre-walk all values, calling datafy recursively. If datafy returns clojure data, it will be used, if not\na placeholder (a clojure map) with the object-id and class-name will take its place.\n\nYou can extend datafy by extending the `flow-storm.plugins.flowbook.runtime/Datafiable`. Notice this is not the \n`clojure.core.protocols/Datafiable`, the reason behind this being, in some cases the Clojure one is probably already being used on other applications \nwith a different, maybe conflicting purpose. If that is not the case, you can extend the plugin's Datafiable to just call the Clojure's one.\n\n## Creating a flowbook\n\nA flowbook is a regular `.html` file you can edit to describe/explain your flows. The only special thing about it is that you\ncan call `gotoLocation.invoke(FLOW_ID,THREAD_ID,IDX)` to make FlowStorm jump to that point in time if it is being rendered\ninside the flowbook viewer.\n\nYou can work with your file using your browser, or you can open it with the plugin which has a refresh mechanism (see next section).\n\n## Replaying flows and loading a flowbook\n\nReplaying your flows is straight forward. Head to the `Flowbooks` plugin tab and click on `Load flowbook`. It\nshould bring up a file selector for .edn files. After selecting your flowbook, it should replay them, and enable\na button that allows you to open the flowbook visualizer.\n\nSince the serialized values are just clojure data, your flows should be\nable to replay in any runtime, just needing FlowStorm and the Flowbook plugin as dependencies.\n\n## Examples\n\nThere is a flowbook example [here](example-flowbooks/) if you want to try.\nIf you are going to try it, it is also recommended to run with the [web plugin](https://github.com/flow-storm/flow-storm-web-plugin).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflow-storm%2Fflow-storm-flowbook-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflow-storm%2Fflow-storm-flowbook-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflow-storm%2Fflow-storm-flowbook-plugin/lists"}