Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/msolorio/allocation-service
Backend API for allocating customer orders to batches of stock in a warehouse.
https://github.com/msolorio/allocation-service
Last synced: 5 days ago
JSON representation
Backend API for allocating customer orders to batches of stock in a warehouse.
- Host: GitHub
- URL: https://github.com/msolorio/allocation-service
- Owner: msolorio
- License: apache-2.0
- Created: 2024-07-19T01:06:31.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2024-08-23T03:20:44.000Z (4 months ago)
- Last Synced: 2024-08-23T22:33:38.794Z (4 months ago)
- Language: TypeScript
- Homepage:
- Size: 1.42 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Allocation Service
[![TypeScript version][ts-badge]][typescript-5-4] [![Node.js version][nodejs-badge]][nodejs] [![Build Status - GitHub Actions][gha-badge]][gha-ci]
Backend API for allocating customer orders to batches of stock in a warehouse.
### Stack
- Node.js
- TypeScript
- PostgreSQL
- Express.js
- Prisma ORM
- Jest
- Docker
- Github Actions
---
### Architecture
The 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.
---
For 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.
---
A few patterns are used to aid dependency inversion.
**Repository** - an abstraction around data access. Handles syncing between the domain model and the ORM.
**Unit of Work** - an abstraction around transactions and atomicity.
**Service Layer** - the entrypoint for injecting I/O and defines the application's use cases.
**Domain Model** - an object module of the business domain free of dependencies on data access.
**Data Mapper** - handles conversion between domain objects and db objects.
**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.
### Todo
- Add consistency boundary with optimistic concurrency
-- invariant: a batch's available quantity must be greater than or equal to zero
### Setup
Install docker and then run
```sh
git clone [email protected]:msolorio/allocation-service.git
cd allocation-service
make build
make up
make migrate
make test
```
### Make Scripts
- `make build` - Build docker container
- `make up` - Start app and TypeScript
- `make down` - Remove containers
- `make logs` - Show container logs
- `make test` - Run tests
- `make migrate` - Run db migrations
- `make run ` - Run a command in the container
[ts-badge]: https://img.shields.io/badge/TypeScript-5.4-blue.svg
[typescript-5-4]: https://devblogs.microsoft.com/typescript/announcing-typescript-5-4/
[nodejs-badge]: https://img.shields.io/badge/Node.js-=%2020.16.0-blue.svg
[nodejs]: https://nodejs.org/dist/v20.16/docs/api/
[gha-badge]: https://github.com/jsynowiec/node-typescript-boilerplate/actions/workflows/nodejs.yml/badge.svg
[gha-ci]: https://github.com/jsynowiec/node-typescript-boilerplate/actions/workflows/nodejs.yml