{"id":46569136,"url":"https://github.com/proophboard/cody-engine","last_synced_at":"2026-03-07T08:03:36.352Z","repository":{"id":163675751,"uuid":"637107115","full_name":"proophboard/cody-engine","owner":"proophboard","description":"Event Modeling meets prototyping","archived":false,"fork":false,"pushed_at":"2026-02-27T22:28:00.000Z","size":6320,"stargazers_count":15,"open_issues_count":18,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-28T03:34:47.244Z","etag":null,"topics":["cody","lowcode-engine","node-js","proophboard","prototyping","typescript"],"latest_commit_sha":null,"homepage":"https://wiki.prooph-board.com/cody_engine/introduction.html","language":"TypeScript","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/proophboard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-05-06T14:28:19.000Z","updated_at":"2026-02-27T22:28:04.000Z","dependencies_parsed_at":"2024-04-09T15:05:17.889Z","dependency_job_id":"3ca80020-9a6f-4b2a-9603-77ce49d0f55a","html_url":"https://github.com/proophboard/cody-engine","commit_stats":null,"previous_names":[],"tags_count":69,"template":false,"template_full_name":null,"purl":"pkg:github/proophboard/cody-engine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proophboard%2Fcody-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proophboard%2Fcody-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proophboard%2Fcody-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proophboard%2Fcody-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/proophboard","download_url":"https://codeload.github.com/proophboard/cody-engine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proophboard%2Fcody-engine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30209797,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T05:23:27.321Z","status":"ssl_error","status_checked_at":"2026-03-07T05:00:17.256Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cody","lowcode-engine","node-js","proophboard","prototyping","typescript"],"created_at":"2026-03-07T08:03:35.805Z","updated_at":"2026-03-07T08:03:36.342Z","avatar_url":"https://github.com/proophboard.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CodyEngine\n\nA batteries-included, highly opinionated fullstack to develop event-sourced backends and task-based UIs with NodeJS and React.\n\nCody Engine is the go-to stack at prooph software. We share our tooling as open source for everyone to look into, use yourself, and modify as you see fit (MIT licensed).\n\nThe stack integrates with an Even Model designed on [https://prooph-board.com](https://prooph-board.com). You can run playshots vibe coded with [https://vibe-cody.ai](https://vibe-cody.ai) and/or use the integrated [Cody Server](https://wiki.prooph-board.com/cody/introduction.html) to generate working code from the Event Model on prooph board.\n\nThe stack allows a seamless development workflow from #nocode to #procode and everything in-between. \n\n## Installation \n\n```\ngit clone https://github.com/proophboard/cody-engine.git my-app\ncd my-app\nnpm install\n```\n\n## Start system\n\n`npm run serve`\n\nThis will start:\n\n- NodeJS backend (API + biz logic) on: [http://localhost:4100](http://localhost:4100)\n- Webpack Dev Server + API Proxy serving React Frontend on: [http://localhost:4200](http://localhost:4200)\n- Cody Server on default port: [http://localhost:3311](http://localhost:3311)\n\n## Push to your own repo\n\nIf you want to keep a connection to the upstream repo `cody-engine` you can do:\n\n```\ngit remote rename origin cody-engine\ngit remote add origin my-app-repo\n```\n\n*This allows you to still pull changes like Cody bugfixes or new features with `git pull cody-engine main`*\n\nOtherwise, just delete the `.git` folder in the project root and start with a fresh `git init`\n\n## Prototype Mode\n\nBy default, Cody Engine runs in a prototyping mode. This means, that the app is not secured by authentication and data is\nonly written to json files located in the `data` directory.\n\nThe mode can be changed so that Cody Engine connects to a `Postgres` database and uses the authentication server `Keycloak`.\n\n## Run with docker\n\nYou can also run Keycloak auth server, Postgres DB and Minio S3 object storage in a local docker stack.\nThis is similar to the production stack.\n\nHere are the steps to switch from prototype mode to \"production-stack\" mode.\n\n### Environment\n\u003e cp .env.dist .env\n\n### Install network\n\u003e docker network create cody\n\n### Update hosts\n\n\u003esudo vim /etc/hosts\n\n```\n127.0.0.1   cody.local \n127.0.0.1   app.cody.local\n127.0.0.1   pgadmin.cody.local \n127.0.0.1   s3.cody.local \n127.0.0.1   s3admin.cody.local \n127.0.0.1   auth.cody.local \n127.0.0.1   socket.cody.local \n```\n\n### Switch Cody Engine mode\n\nThe `.env` file sets `CODY_ENV=localdocker` so that `packages/be/src/environments/environment.localdocker.ts` configuration is used.\nThis switches the backend to `production-stack` mode.\n\nFor the frontend you need to switch the mode by hand in `packages/fe/src/environments/environment.ts`:\n\n```ts\nexport const environment = {\n    production: false,\n    appName: 'Cody',\n    mode: 'production-stack' as CodyEngineMode,\n    // ...\n};\n```\n\n### Configure Keycloak Public Key\n\n1. Log into the Keycloak Admin UI.\n2. Switch to the `App` realm.\n3. Go to `Realm Settings -\u003e Keys`.\n4. Click on the `Public key` button of the `RS256` key.\n5. Copy the public key into the `.env` file to `KC_PUBLIC_KEY=...`\n\n### Run Cody Infrastructure\n\n\u003e docker-compose up -d\n\n### Prepare Database\n\n`npx nx run be:preparedb`\n\n### Import Filesystem DB\n\nIf you switch from filesystem db to Postgres, you can import the data from the filesystem using:\n\n`npx nx run be:importfsdb`\n\n_Run prepare database before the import to ensure that all tables exist._\n\n_If you want to rerun the import, make sure to empty the database before._\n\n### Import Cody Playshot\n\nExport a playshot from prooph board and place it into: `data/playshot.json`\n\nThen run:\n\n`npm run import-playshot`\n\n### Access local services\n\n| service        | user     | password   | link                                                                     |\n|----------------|----------|------------|--------------------------------------------------------------------------|\n| Keycloak Admin | admin    | password   | [https://auth.cody.local/auth/admin](https://auth.cody.local/auth/admin) |\n| pgadmin        | postgres | password   | [https://pgadmin.cody.local](https://pgadmin.cody.local)                 |\n| minio          | minio    | miniominio | [https://s3admin.cody.local](https://s3admin.cody.local)                 |\n\n### Test Users\n\nThe Keycloak realm `App` is set up with a test user. If you have more personas defined in your prototype, you can add\nthem to the realm config and import the users into keycloak.\n\n_See realm config in `env/docker/keycloak/import/app-realm.json`_\n\n| email             | password | role                 |\n|-------------------|----------|----------------------|\n| anyone@cody.local | dev      | Anyone               |\n\n#### User Attributes\n\nAdditional user attributes need to be mapped in Keycloak so that they are included in the JWT.\n1. Goto `client scopes -\u003e profile -\u003e mappers -\u003e Add Mapper -\u003e By configuration`. \n2. Pick `User Attribute` from the list.\n3. Fill out the form. Set token claim name to `attributes.[your_attribute_name]`\n4. Turn on `multivalued` if a user can have multiple values set for an attribute.\n\n#### User Roles\n\nMake sure to register user roles in `shared/src/lib/types/core/user/user-role.ts`. _Done by Cody if you pass a role sticky to Cody._\n\n## Production Build\n\nCody Engine works with packages insight a mono repo. The packages you'll likely deploy to production are:\n\n- `packages/be`\n- `packages/fe`\n- `packages/shared`\n\nThe shared package is used in the frontend as well as in the backend. Cody generates most of the type classes and interfaces (e.g. for commands, queries, events, value objects)\ninto this shared package. Frontend and Backend include the shared package in their respective builds.\n\n### Backend Build\n\n`npx nx build be` -\u003e builds into `dist/packages/be`\n\nYou can also build a docker image with:\n\n`npx nx run be:docker-build`\n\n### Frontend Build\n\n`npx nx build fe` -\u003e builds into `dist/packages/fe`\n\n_For Staging_\n\n`npx nx build fe --configuration=staging`\n\nYou can also build a docker image to serve the frontend build via Nginx with:\n\n`npx nx run fe:docker-build`\n\n_For Staging_\n\n`npx nx run fe:docker-build --configuration=staging`\n\n## Extension Points\n\nCody will generate fully working source code for frontend and backend. However, low code has limitations. \nAt some point you'll hit a use case that can't be handled without some custom development be it in the frontend or backend.\nTherefor, Cody Engine ships with many extension points to let you override code generated behavior.\n\nYou'll find `extensions` directories in all main packages (fe, be, shared) with files to guide you how to inject your own logic.\nAs long as you only modify or add files in the `extensions` directories, you should be able to pull updates from the `cody-engine` upstream repository.\n\n### Example\n\nLet's say you want to override a handler function for a specific command. You can add your custom command handler to:\n`packages/be/src/extensions/command-handlers.ts`\n\n```ts\nimport {CommandHandlerRegistry} from \"@event-engine/infrastructure/commandHandling\";\nimport {handleCommandWithCustomHandler} from \"@server/extensions/command-handlers/handle-command-with-custom-handler\"\n\nexport const commandHandlerExtensions: CommandHandlerRegistry = {\n  'MyService.CommandWithCustomHandler': handleCommandWithCustomHander,\n};\n```\n\n*Please Note: Every extension registry file (like the one shown in the example above) uses a specific registry type (e.g. CommandHandlerRegistry). Check the type, to learn how to add custom functions. TypeScript should complain, if you're missing something.*\n\n### Theming\n\nTheming is based on [material-ui](https://mui.com/material-ui/customization/theming/).\n\nYou'll find a theme file in `packages/fe/src/extensions/app/layout/theme.ts`\n\n**Please Note: Changing the layout itself is not yet supported. If you want to change the layout structure (different sidebar, topbar, ...), you need to change the respective files directly. This might conflict with future updates of Cody Engine, especially when we add support for custom layouts, but it's the only way for now. Sorry :(**\n\n## Testing\n\nRun tests of all 3 main packages in parallel:\n\n```shell\nnpm run test\n```\n\n### Backend Testing\n\n```shell\nnpm run test-be\n```\n\n### Frontend Testing\n\n```shell\nnpm run test-fe\n```\n\n### Shared Library Testing\n\n```shell\nnpm run test-shared\n```\n\n## Republish Events\n\nUseful during development to test new policies or trigger events in production again\n\n```shell\nnpx nx run be:republish --eventid \u003cEventId\u003e\n```\n\n## Trigger Projection with event\n\nUseful during development to test new projections or trigger events in production again\n\n```shell\nnpx nx run be:project --eventid \u003cEventId\u003e --name \u003cProjectionName\u003e\n```\n\n`--name` is optional and defaults to: \"read_model\"\n\n## Contribution\n\nThis repository is a skeleton for a Cody Engine app that has batteries included. This means, that Cody will\ngenerate source code directly into the cloned repository and that designers and developers can add custom designs and logic, too.\n\nWhen you want to contribute changes to the skeleton itself, you have to make sure to not submit any generated or customized code.\nTherefor, we've prepared a terminal command that will set up a contribution environment with:\n\n- an example domain, so that the skeleton is filled with some functionality\n- .gitignore files that hide them self and the example domain from being committed\n- changes in some registry files\n\n`npm run prepare-contribution`\n\n*Please Note: If you add a new registry file that should be included in the skeleton, please use the file extension `.ts.cetmpl`. \nA script will turn that template into a normal TS file on server start up. \nAsk a maintainer for help, if you're not sure how to do it!*\n\n## Understand this workspace\n\nRun `nx graph` to see a diagram of the dependencies of the projects.\n\n## Batteries Included\n\nThe Cody Engine app skeleton makes use of a bunch of awesome open source libraries. Here is a list of the most important ones, so that you can find their documentation quickly:\n\n### Backend\n\n- [Express](https://expressjs.com/): Fast, unopinionated, minimalist web framework for Node.js\n- CQRS/Event Sourcing implementation is inspired by [prooph components](https://getprooph.org/), [Event Engine](https://event-engine.github.io/) and [MartenDB](https://martendb.io/)\n- [Jexl](https://github.com/TomFrost/jexl): Powerful context-based expression parser and evaluator\n\n### Frontend\n- [React](https://react.dev/): The library for web and native user interfaces\n- [MUI](https://mui.com/): Move faster with intuitive React UI tools\n- [react-jsonschema-form](https://rjsf-team.github.io/react-jsonschema-form/docs/): A simple React component capable of building HTML forms out of a JSON schema\n\n### Lowcode\n\n- [prooph board Cody](https://wiki.prooph-board.com/cody/Cody-Server.html): Cody is a HTTP server that receives requests from prooph board to turn an event model into working code\n- [Nx Generators](https://nx.dev/plugin-features/use-code-generators): Generators provide a way to automate many tasks you regularly perform as part of your development workflow\n- [ts-morph](https://ts-morph.com/): Setup, navigation, and manipulation of the TypeScript AST made simple\n\n## Further help\n\nVisit the [Nx Documentation](https://nx.dev) to learn more.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproophboard%2Fcody-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fproophboard%2Fcody-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproophboard%2Fcody-engine/lists"}