{"id":23209314,"url":"https://github.com/msolorio/allocation-service","last_synced_at":"2025-04-05T12:10:32.603Z","repository":{"id":250807376,"uuid":"830772335","full_name":"msolorio/allocation-service","owner":"msolorio","description":"Backend API for allocating customer orders to batches of stock in a warehouse using patterns from domain driven design.","archived":false,"fork":false,"pushed_at":"2024-10-08T20:32:23.000Z","size":1496,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-10T22:52:22.918Z","etag":null,"topics":[],"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/msolorio.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}},"created_at":"2024-07-19T01:06:31.000Z","updated_at":"2025-01-13T00:38:54.000Z","dependencies_parsed_at":"2024-12-18T18:16:02.908Z","dependency_job_id":"3be4b97c-837e-4150-805a-56fde6d15c5b","html_url":"https://github.com/msolorio/allocation-service","commit_stats":null,"previous_names":["msolorio/allocation-service"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msolorio%2Fallocation-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msolorio%2Fallocation-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msolorio%2Fallocation-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msolorio%2Fallocation-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/msolorio","download_url":"https://codeload.github.com/msolorio/allocation-service/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247332609,"owners_count":20921853,"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":"2024-12-18T18:15:59.005Z","updated_at":"2025-04-05T12:10:32.574Z","avatar_url":"https://github.com/msolorio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Allocation Service\n\n[![TypeScript version][ts-badge]][typescript-5-4] [![Node.js version][nodejs-badge]][nodejs] [![Build Status - GitHub Actions][gha-badge]][gha-ci]\n\nBackend API for allocating customer orders to batches of stock in a warehouse.\n\n### Stack\n- Node.js\n- TypeScript\n- PostgreSQL\n- Express.js\n- Prisma ORM\n- Jest\n- Docker\n- Github Actions\n\n---\n\n### Architecture\n\nThe application uses the [dependency inversion principle](https://en.wikipedia.org/wiki/Dependency_inversion_principle), and creates abstractions around I/O and injects them. This allows us to pass a fake I/O to the service layer for testing the application \"edge-to-edge\" with fast, in-memory unit tests.\n\n![in-memory-implementation](README_assets/in-memory-implementation.png)\n\n---\n\nFor real-world and E2E testing, the service layer is passed real I/O that talks to a database. Because we have already exhaustively tested the service layer with fast, in-memory tests, less slow E2E tests are needed. We can achieve a healthy testing pyramid with high coverage.\n\n![e2e-implementation](README_assets/e2e-implementation.png)\n\n---\n\nA few patterns are used to aid dependency inversion.\n\n**Repository** - an abstraction around data access. Handles syncing between the domain model and the ORM.\u003cbr\u003e\n**Unit of Work** - an abstraction around transactions and atomicity.\u003cbr\u003e\n**Service Layer** - the entrypoint for injecting I/O and defines the application's use cases.\u003cbr\u003e\n**Domain Model** - an object module of the business domain free of dependencies on data access.\u003cbr\u003e\n**Data Mapper** - handles conversion between domain objects and db objects.\u003cbr\u003e\n\n**Trade-offs** - Each pattern adds indirection and congintive load and wouldn't be necessary in a simple application. You could, for example, still achieve dependency inversion and abstracting I/O with only a simple repository and a service layer.\n\n### Todo\n- Add consistency boundary with optimistic concurrency\n-- invariant: a batch's available quantity must be greater than or equal to zero\n\n### Setup\nInstall docker and then run\n\n```sh\ngit clone git@github.com:msolorio/allocation-service.git\ncd allocation-service\nmake build\nmake up\nmake migrate\nmake test\n```\n\n### Make Scripts\n\n- `make build` - Build docker container\n- `make up` - Start app and TypeScript\n- `make down` - Remove containers\n- `make logs` - Show container logs\n- `make test` - Run tests\n- `make migrate` - Run db migrations\n- `make run \u003ccommand\u003e` - Run a command in the container\n\n[ts-badge]: https://img.shields.io/badge/TypeScript-5.4-blue.svg\n[typescript-5-4]: https://devblogs.microsoft.com/typescript/announcing-typescript-5-4/\n[nodejs-badge]: https://img.shields.io/badge/Node.js-=%2020.16.0-blue.svg\n[nodejs]: https://nodejs.org/dist/v20.16/docs/api/\n[gha-badge]: https://github.com/jsynowiec/node-typescript-boilerplate/actions/workflows/nodejs.yml/badge.svg\n[gha-ci]: https://github.com/jsynowiec/node-typescript-boilerplate/actions/workflows/nodejs.yml\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsolorio%2Fallocation-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmsolorio%2Fallocation-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsolorio%2Fallocation-service/lists"}