{"id":26658980,"url":"https://github.com/trustbit/bfkata","last_synced_at":"2025-09-15T12:08:17.709Z","repository":{"id":64298957,"uuid":"567758638","full_name":"trustbit/bfkata","owner":"trustbit","description":"Software kata for DDD and Event Sourcing","archived":false,"fork":false,"pushed_at":"2023-02-01T10:07:30.000Z","size":910,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-06-20T08:47:21.283Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/trustbit.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}},"created_at":"2022-11-18T14:06:51.000Z","updated_at":"2022-11-18T16:54:50.000Z","dependencies_parsed_at":"2023-02-17T04:16:13.319Z","dependency_job_id":null,"html_url":"https://github.com/trustbit/bfkata","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trustbit%2Fbfkata","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trustbit%2Fbfkata/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trustbit%2Fbfkata/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trustbit%2Fbfkata/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trustbit","download_url":"https://codeload.github.com/trustbit/bfkata/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245440514,"owners_count":20615633,"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-03-25T10:17:28.228Z","updated_at":"2025-03-25T10:17:28.748Z","avatar_url":"https://github.com/trustbit.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Black Friday Kata\n\n\nStatus: stabilizing the domain internally at Trustbit. Not for public use, yet.\n\n## Short Story\n\nThis is a scaffolding for **DDD and Event Sourcing Kata** from Trustbit. It is about inventory management.\n\n1. Grab protobuf [protobuf definition](api/api.proto) for a small inventory-management server.\n2. Generate events and API from that definition for your language. Implement your first method.\n3. Install bfkata binary for your platform from [releases](https://github.com/trustbit/bfkata/releases) (or run go code from this repo)\n4. Run `bfkata test` to verify that [behaviors](specs/bundle.txt) are implemented correctly\n5. (Future) Run `bfkata stress` to see how code performs under high load\n\n![](doc/picture.png)\n\n\n## Long Story\n\nAt Trustbit, we want to make it easy to do a domain-modeling kata with event sourcing in a language of your choice. This is good for learning, sharing, and pushing the state of the art. If you are interested, **please follow along**!\n\nWe have picked inventory-management domain, because it brings some interesting behaviors and fault scenarios.\n\nTo streamline kata, we took the liberty of:\n\n- Defining the API - it is as minimal as possible\n- Defining event contracts\n- Writing them down in Google proto3 syntax - so that you can scaffold implementation in a language of your choice\n- Writing event-driven specs (tests)\n- Bundling these specs in a cross-platform spec runner\n\nIn other worlds:\n- [api/api.proto](api/api.proto) - defines contracts for API and events;\n- [specs/bundle.txt](specs/bundle.txt) - contains tests that define desired behaviors;\n- bfkata binary (this project) - tests any implementation.\n\nThis kata is solvable without much code. We went ahead and did it ourselves, as a part of Learning \u0026 Sharing at Trustbit.\n\nIf you want to play with a slighly different API or behaviors, you could easily do so by forking the project and changing API/specs according to your needs.\n\n## Inventory vs Spec APIs\n\nThere are two sets of APIs  implement:\n\n- Inventory service - the real service with methods like \"add location\" and \"reserve (inventory)\"\n- Spec service - special service to run specs remotely.\n\n\n### 1. Inventory API\n\nInventory API is as simple as we could get it. It has methods:\n\n- AddLocations \n- AddProducts \n- ListLocations\n- MoveLocation\n- UpdateInventory\n- GetLocInventory\n- Reserve\n\nThere are following domain events:\n\n- LocationAdded\n- LocationMoved\n- ProductAdded\n- InventoryUpdated\n- Reserved\n\nYou can find full definition in [api/api.proto](api/api.proto).\n\n### 2. Spec API\n\nThis API has two methods:\n\n- About - to return info about the implementation\n- Spec - to execute a single event-driven spec against this endpoint. `bfkata` will use it to verify all behaviors.\n\n\n## Event-Driven Specs\n\nEvent-driven specs look like this:\n\n```\nmove locations\n------------------------------------------\nGIVEN:\n  LocationAdded id:1  name:\"Warehouse\"\n  LocationAdded id:2  name:\"Container\"\nWHEN:\n  MoveLocationReq id:2  newParent:1\nTHEN:\n  MoveLocationResp \nEVENTS:\n  LocationMoved id:2  newParent:\n```\n\nThey are bundled as text file in [specs/bundle.txt](specs/bundle.txt).\n\nIf you want to play with your own specs, just copy `bundle.txt` someplace, modify and pass to `bfkata test` as `file` argument.\n\n# Running bfkata\n\nThe easiest way to run bfkata is by downloading the latest release for your platform from [Releases](https://github.com/trustbit/bfkata/releases)\n\n## With go 1.19 as package\n\nIf you have go 1.19 installed on your system (install 1.19, it has generics!), then:\n\n```bash\n\ngo install github.com/trustbit/bfkata@latest\n\n# prints:\n# go: downloading github.com/trustbit/bfkata v1.0.5\n\nbfkata  \n\n# bfkata - test scaffolding for Black Friday kata. Commands:\n#\n#  api       - print bundled contracts\n#  specs     - print bundled test specs\n#  test      - run test suite aginst a provided gRPC endpoint\n```\n\n## From source code\n\nClone this repository then run:\n\n```bash\ngo run *.go\n\n# bfkata - test scaffolding for Black Friday kata. Commands:\n#\n#  api       - print bundled contracts\n#  specs     - print bundled test specs\n#  test      - run test suite aginst a provided gRPC endpoint\n```\n\n\n## From binary\n\nnot implemented yet. Ping Rinat (@abdullin on Twitter) to setup proper releases :)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrustbit%2Fbfkata","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrustbit%2Fbfkata","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrustbit%2Fbfkata/lists"}