Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tiagostutz/demo-warehouse-software
A simple demo of a warehouse software with Typescript, PostgreSQL, Prisma, Golang, NextJS...
https://github.com/tiagostutz/demo-warehouse-software
golang jest nextjs postgresql prisma testing typescript
Last synced: 3 months ago
JSON representation
A simple demo of a warehouse software with Typescript, PostgreSQL, Prisma, Golang, NextJS...
- Host: GitHub
- URL: https://github.com/tiagostutz/demo-warehouse-software
- Owner: tiagostutz
- License: mit
- Created: 2021-07-11T12:03:22.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-06-15T17:59:22.000Z (over 1 year ago)
- Last Synced: 2024-11-02T14:51:34.428Z (3 months ago)
- Topics: golang, jest, nextjs, postgresql, prisma, testing, typescript
- Language: TypeScript
- Homepage:
- Size: 2.23 MB
- Stars: 5
- Watchers: 4
- Forks: 7
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/bancodobrasil/poppins)
## This project was made for first-time contributors and open source beginners
This project follows the [Poppins manifesto guidelines](https://github.com/bancodobrasil/poppins) as part of it's community principles and policies, focusing all the decisions and interactions on providing open source beginners mentorship with real and relevant experiences, respecting each learning pace, background experience, academic formation, questions, suggestions, doubts and opinion.
## Contribute now!
So, let's start contributing! **Open an issue asking for a task to be done by you**. A mentor/maintainer will come and provide a technical overview of the project and what are the possibles ways of contributing to the project. You will discuss the options and a suitable issue will be assigned or created to you.
That's it. Just make yourself at home and good luck!
# Demo Warehouse Software
A simple demo of a warehouse software with TypeScript, PostgreSQL, Prisma, Go, NextJS...
## Getting started
### Option 1
```bash
git clone https://github.com/tiagostutz/demo-warehouse-software
```
```bash
docker-compose up
```
Wait for the services to be ready and then populate the database with using the file watch:
```bash
cp assets/inventory.json local-data/incoming/article/
```
```bash
cp assets/products.json local-data/incoming/product/
```
```bash
cd web-app
yarn install
yarn build
yarn start
```
Open [http://localhost:3000](http://localhost:3000) on your Browser and check
### Option 2
1) Create this docker-compose.yml:
```yaml
version: "3.7"
services:
db:
image: tiagostutz/warehouse-demo-postgres:0.0.3
environment:
- POSTGRES_DB=demo-warehouse
- POSTGRES_PASSWORD=123456
- POSTGRES_INITDB_ARGS=--debug
ports:
- 5432:5432
api-backend:
image: tiagostutz/warehouse-demo-api-backend:0.0.3
ports:
- 4000:4000
environment:
- DATABASE_URL=postgres://postgres:123456@db:5432/demo-warehouse
database-updater:
image: tiagostutz/warehouse-demo-database-updater:0.0.3
volumes:
- ./local-data:/app/data
environment:
- LOG_LEVEL=debug
- WAREHOUSE_ARTICLE_ENDPOINT=http://api-backend:4000/article
- WAREHOUSE_PRODUCT_ENDPOINT=http://api-backend:4000/product
```
And bring it up:
```bash
docker-compose up
```
2) After all the services are up, check that the database is clean by executing:
```bash
curl http://localhost:4000/article
```
```bash
curl http://localhost:4000/product
```
They should return and empty array `[]` as the response.
3) Now let's put some Articles from the [inventory.json](assets/inventory.json) file. To do this, you need to copy this file to the folder the database auto-updater is watching for. Execute this:
```bash
cp assets/inventory.json local-data/incoming/article/
```
Check again the return of the API:
```bash
curl http://localhost:4000/article
```
4) Now let's put some Products from the [products.json](assets/products.json) file. To do this, you need to copy this file to the folder the database auto-updater is watching for. Execute this:
```bash
cp assets/products.json local-data/incoming/product/
```
Check again the return of the API:
```bash
curl http://localhost:4000/product
```
5) Let's get some details on the products created, like the quantity available based on the invetory stock:
```bash
curl http://localhost:4000/product/1
```
```bash
curl http://localhost:4000/product/2
```
If all went as expected, the `quantityAvailable` of this Product with **id=1** should be `2` and of the Product with **id=2** should be `1`.
6) Finally, let's update the inventory stock (reduce) simulating as if a second product was bought and let's check the quantity of the first:
```bash
curl --location --request POST 'http://localhost:4000/article/stock-update/by/product/2' \
--header 'Content-Type: application/json' \
--data-raw '{
"quantity": 1
}'
```
And let's check how the quantity available of the Products we have now:
```bash
curl http://localhost:4000/product/1
```
Product with **id=1** should have **quantityAvailable=1**
```bash
curl http://localhost:4000/product/2
```
Product with **id=2** should have **quantityAvailable=0**
## Overview of the Stack
* **Frontend:** NextJS with FaaS that makes the requests to the **API Backend**
* **API Backend**: Typescript application that uses **ExpressJS** to handle API routing, **Prisma** as ORM to access Database and **JEST** for testing.
* **Database Auto-updater**: Golang application that watches for files being placed on a given folder and starts a Pipeline that will end up making a request to the **API Backend** to create Article and Products read and converted from files
## Development Mode
To run each part individually in development mode, follow the steps bellow
### API Backend
To run api-backend in development mode, first clone this repo:
```bash
git clone https://github.com/tiagostutz/demo-warehouse-software.git
```
Bring the database up:
```bash
docker-compose up db
```
Then go to the [api-backend](api-backend) folder and run
```bash
yarn install
```
Run the tests:
```bash
yarn test
```
Start the API in development mode:
```bash
yarn run dev
```
### Database auto-updater
First, bring the database and the api-backend up (described in the previous session).
After that, run
```bash
go mod download
```
Then, to run the tests run:
```bash
go test ./...
```
## Evolution Stages
**Stage 1** (current implementation): no security, no load handling, no caching
**Stage 2** (goal of this project): security, load balancing one level (API Gateway), no caching
**Stage 3** (start production): security, load balancing one level (API Gateway), observability, caching
**Stage 4** (scaling to the cloud): security, load handling, caching, observability, database replica/shard, job scheduling with queues and workflow management
## Testing
There are two levels of tests: component/service/unit level and integration/API level test.
Running **API Backend** tests:
```bash
yarn run test
```
To run the **Database Auto-updater** integrated tests, you need the database and one instance of the API Backend up at **localhost:4000**, then run:
```bash
go test ./...
```
### API Backend
The tests here are at folders names `tests` and the files has a `.test.ts` suffix. To run the tests:
```bash
yarn run test
```
### Database Auto-updater
## Architecture overview and Design decisions
- Pros and cons
- Other possibilities
- Kong API Gateway
- Sidecar/Ambassador to hide from the Business Logic this complexity
### Observability
- Healthcheck
- `/health`
- `/ready`
- Prometheus Metrics:
- Database updater
- API Backend
- Grafana
### Prisma as an ORM (and why not GraphQL?)
What happens when running:
```bash
yarn install @prisma/client
```
The install command automatically invokes prisma generate for you which reads your Prisma schema and generates a version of Prisma Client that is tailored to your models.
Whenever you make changes to your Prisma schema in the future, you manually need to invoke `npx prisma generate` in order to accomodate the changes in your Prisma Client API.
- More at [https://www.prisma.io/docs/getting-started/setup-prisma/start-from-scratch/install-prisma-client-typescript-postgres/](https://www.prisma.io/docs/getting-started/setup-prisma/start-from-scratch/install-prisma-client-typescript-postgres/)
- Used the defaults of Prisma to generate a Database, but if the data modeling would be subject to a Data Administration process with data/terms dictionary, conventions, abbreviations and that kind of stuff, some additional configuration would be needed on the [schema.prisma](api-backend/schema.prisma) definition.
```bash
DATABASE_URL=postgres://postgres:123456@localhost:5432/demo-warehouse npx prisma migrate dev --name init
```
- **GraphQL**: definitely would be a good option, but there are some scenarios we need specific business logic that would need some code working. But for data fecthing and mutation to database, good one. The endpoints that need additional logic could expose those endpoints as regular APIs and use the GraphQL to fetch and mutate data.
- **Migration tool demo**:
- started with ON DELETE CASCADE for all FKs
- then ON DELETE RESTRICT for all FKs
- then ON DELETE RESTRICT for Article ON DELETE CASCADE for Product
```bash
DATABASE_URL=postgres://postgres:123456@localhost:5432/demo-warehouse npx prisma migrate dev --name init
```
### TypeScript mixed with pure JavaScript
If there's no domain involved or for a more integration and "flow setup" kind of code, go with vanilla JavaScript. If there's model, business logic or heavy componentization, go with TypeScript.
### Thoughts on scaling the solution
- Change the load from watching files to consuming a queue
- If a need for a more complex enrichment of the data, consider using a Workflow/pipeline orchestrator (like Netflix Conductor)
## Software Highlevel Spec
This software should hold **articles**, and the articles should contain:
- identification number
- name
- available stock
It should be possible to **load articles into the software from a file**, see the provided [inventory.json](inventory.json) sample file.
The warehouse software should also have **products**, products are made of different articles. Products should have:
- name
- price
- list of articles of which they are made from with a quantity
The products should also be **loaded from a file**, see the provided [products.json](products.json) sample file.
The warehouse should have at least the following functionality;
- Get all products and quantity of each that is available with the current inventory
- Remove(Sell) a product and update the inventory accordingly
## Awesome Poppins projects looking for contributors:
Here's a list of some more curated Poppins projects:
- [First Contributions Repository](https://github.com/firstcontributions/first-contributions): This project is designed to help beginners make their very first contributions to open source projects.
- [Contribute to this Project](https://github.com/Syknapse/Contribute-To-This-Project): This is for absolute beginners. If you know how to write and edit an anchor tag then you're ready to start contributing!
- [Contribute to open source](https://github.com/danthareja/contribute-to-open-source):
Learn the GitHub workflow by contributing code in a fun simulation project.
- [goodfirstissue.dev](https://github.com/deepsourcelabs/good-first-issue): goodfirstissue.dev has a list of project repositories with the `good first issue` tag. Project moderators add this tag to help beginners get involved with their projects.