/PoSS

Point of Sale System

Primary LanguageJava

YAPoSS - Yet Another Point of Sale System (by Spaghetti ninjas)

Tooling

Build tool: Gradle

IDE: IntelliJ IDEA CE (it's free btw)

Java version: OpenJDK 17

Others useful tools:

Building & Running

You must have gradle and docker installed.

All Dockerfiles simply copy the .jar files, since building inside takes way too long. To run project:

  1. gradle bootJar - creates .jar for each project.
  2. docker compose build - builds docker images.
  3. docker compose up - runs the whole project.

For your convenience: gradle bootJar && docker compose build && docker compose up

By default api-gateway should be available on localhost:8080, see Taken ports for other services.

Single service

Native

Run a service locally with gradle <PROJECT_NAME>:bootRun,

For example: gradle api-gateway:bootRun

Note

api-gateway needs service hostnames and ports set, at the time this documentation is written, all services have proper defaults set for native development and with docker.

These can be overwritten with SPRING_APPLICATION_JSON environment variable. Example: SPRING_APPLICATION_JSON='{"customerService":{"hostname":"localhost","port":8081}}' gradle api-gateway:bootRun.

Docker

If you want to run an individual service in docker do this from project root:

  1. docker build --tag FOO:BAR -f SERVICE_DIR/Dockerfile .
  2. docker run -p <PORT_ON_YOUR_SIDE>:<PORT_ON_DOCKER_SIDE> FOO:BAR

For example:

  1. docker build --tag yaposs:customer-service -f customer-service/Dockerfile .
  2. docker run -p 8081:8081 yaposs:customer-service

Warning

Running api-gateway this way is unsupported (I don't have the time to configure a third way of running it, but you can try to make it happen and open a PR).

Development guidelines

To save us all some headache please make the default port of each service a different one. This doesn't really matter when running with docker, but causes problems when running multiple services natively.

Taken ports

Currently, these ports are taken:

Service Port
Customer service 8081
API Gateway 8080

E2E Tests

All tests assume to be in init state, i.e. there are no entities. Therefore, all tests should clean up after themselves, deleting all entities they have created.

If you did some manual testing, you can run: curl 'http://localhost:8080/api/<SOME_ENDPOINT>' | jq -r '.[].id' | xargs -I % curl -X DELETE localhost:8080/api/Staff/% to wipe all entities.

For example: curl 'http://localhost:8080/api/Staff' | jq -r '.[].id' | xargs -I % curl -X DELETE localhost:8080/api/Staff/%.

Note

The previous command requires jq to be installed.

Testing

There are some unit tests, run them with: gradle PROJECT_NAME:test.

E2E testing is done with Hurl. To run them all simply hurl tests/*.hurl.

Warning

As mentioned, some tests may fail because they did not expect there to be additional entities. See Development Guidelines/E2E Tests for more detail.

Project generation

This project was generated from a swagger/OpenApi yaml conf file.

Note

You shouldn't need to do these steps, to edit the project edit the generated protobuf files. I'm just documenting the steps.

Warning

Changing contract.yaml won't update pos.proto or generated java DTO classes.

If you want to replicate the project setup here's the instructions:

  1. Generate the project with https://start.spring.io.
  2. Install Go
  3. convert contract.yaml to swagger spec v2 (this one is a little involved)
  4. Serve contract.yaml on a http server this should do (Just run sfz .)
  5. Use this converter by running api-spec-converter --from=openapi_3 --to=swagger_2 --syntax=yaml http://127.0.0.1:[PORT]/contract.yaml > contractV2.yaml
  6. Set up openapi2proto
  7. Generate a .proto file: openapi2proto -spec contractV2.yaml -out src/main/proto/dtos.proto -skip-rpcs