This is an initial readme, here you can find the project's goals, and some features are not yet fully available.
⤴️ index- 📗 About
- 💻 Run the project
- 📰 API Documentation
- ✅ Tests
- 🪲 Debug
- ☔ Event Storming
- 📊 Diagrams
- 🚥 HATEOAS HAL
- 🕵️ Observability
- 🧠 ADR - Architecture Decision Records
- 👏 Best Practices
- 🧰 Tools
- 🔢 Versions
- 🤖 Use of AI
This project aims to address the needs of cataloging cinema halls, movies, and sessions on a cinema ticket e-commerce website. It is part of a broader study of the mentioned e-commerce called CineTicket. However, its responsibility as microservices is to register, maintain, and provide session and seat data.
This is a Golang version of the mentioned service. Swagger Docs, Flow Diagrams, Entity-Relationship Diagrams (DER), and Event Storming provide more context to the service's scenario.
The objective of this system is to maintain a high level of maturity with a consistent RESTful API, along with the possibility of caching and a robust logging system.
In the current branch, you will find the "happy path" for creating addresses, cinema rooms, movies, and posters. Log handling, observability, and testing will be developed in future branches.
Create a copy of the 'SAMPLE.env' file with the name '.env' and run the 'docker compose up' command (according to your 'docker compose' version) in the project's root directory:
$ docker compose build
$ docker compose up✍️ Note:
Troubleshoting: Error response from daemon: listen tcp4 0.0.0.0:5432: bind: address already in use It's not uncommon, while running tests and other applications concurrently with Postgres, to encounter a port collision caused by the container/image. You should stop the relevant container, and if the issue persists, use the following commands:
sudo lsof -i -P -n | grep 5432 sudo kill -9 <process id>as seen in this Stack Overflow question with other possible solutions.
Below is a screenshot of the latest documentation, which can be accessed here on http://localhost:8080/swagger/index.html with the project running locally. For now, only the happy path is functional; new iterations will add observability, testing, and other components.
Generate Docs: You need to have Golang and the project installed locally to run the following command in the project's root directory:
swag init --generalInfo cmd/api/main.go --exclude ./web,./tools -o ./apiIn the project root directory, and without running all Docker Compose dependencies, execute the following commands:
$ docker compose up postgres-catalogo -d
$ go test -vThe Output:
This project is a simple CRUD with a two-tier architecture. Unit tests don't make sense in this scenario. An integration test is the best approach. At the moment, only the "happy path" for success is covered. I plan to increase the test coverage in the future to include corner cases.
✍️ Note:
It is necessary to have Go 1.21.1 or GVM with this version installed on the machine because tests runs locally.
Integration tests running on github action:
Upon successful completion of tests, the CI generates a Docker Hub registry:
To set secret password Docker Hub from GitHub repository used in CI:
repository settings -> security -> Secrets and Variables -> Actions -> New Repository Secret -> PASSWORD_DOCKER_HUB
Using VSCode as a code editor with the following configuration in the .vscode/launch.json file:
{
"version": "0.2.0",
"configurations": [
{
"name": "Launch CineCatalogo",
"type": "go",
"request": "launch",
"mode": "debug",
"program": "${workspaceFolder}/cmd/api/main.go",
"cwd": "${workspaceFolder}",
"trace": "verbose",
},
{
"name": "Test CineCatalogo",
"type": "go",
"request": "launch",
"mode": "test",
"program":"${workspaceFolder}/main_routes_integration_successful_test.go",
"trace": "verbose",
}
]
}Alter the .env configuration for DATABASE_HOST and API_HOST to localhost and localhost:8080 respectively to enable local debugging.
...
API_HOST=localhost:8080 # catalogo-api | localhost:8080
...
DATABASE_HOST=localhost # postgres-catalogo | localhostIn the project root directory, and without running all Docker Compose dependencies, execute the following commands:
$ docker compose up postgres-catalogo -dDistribute breakpoints at code points of interest, and in `Run and Debug` click on `Launch Cinecatalogo`. Access the API via the browser to initiate your debugging process:
To run debugging on test routines, select and click on the "Test CineCatalogo" option in `Run and Debug`. To enable debugging in test mode, no changes are required in the `.env` file, as these environment variable values are initialized within the test suite itself:
See VisualStudio Go Debugging for more configuration details
✍️ Notes:
- It is necessary to have Go 1.21.1 or GVM with this version installed on the machine because debugging runs locally.
- Revert
.envto its original values to executedocker compose upand restore the correct system behavior.
In November 2023, we conducted event modeling for this project and other parts of CineTicket (Thanx for the help, marciovmartins). We held an extensive remote Event Storming session with the goal of mapping events, commands, aggregates, and their relationships.
You can follow part of our findings on YouTube in PT-BR.
At the moment, we are abstracting the authentication flow and the ticket purchase flow.
Flow Diagram:
graph LR
subgraph USER FLOW
F([Logged Admin])
F --> MAD(Maintain Addresses)
F --> MFI(Maintain Films)
F --> MSE(Maintain Sessions)
F --> MRO(Maintain Cinemas)
end
subgraph Catalog Microsservice
TIC[Tickets]
MFI --> FIL[Films]
MRO --> ROO[Cinemas]
MSE --> SEA[Seats]
MAD --> ADR[Adresses]
MSE --> SES[Sessions]
end
%% Create associations between steps
TIC -->|Associate| SES
SEA -->|Associate| TIC
SEA -->|Associate| ROO
ROO -->|Associate| ADR
FIL -->|Associate| SES
SES -->|Associate| ROO
DER:
erDiagram
movies {
int id
UUID uuid
string name
string description
int age_rating
boolean subtitled
boolean published
string poster
}
posters {
int id
UUID uuid
int movie_id
string name
string contentType
string alternative_text
string path
}
sessions {
int id
UUID uuid
int film_id
int theater_id
string description
date date
timestamptz start_time
timestamptz end_time
string time
}
cinemas {
int id
int address_id
UUID uuid
string name
string description
int capacity
}
seats {
int id
UUID uuid
int theater_id
string code
}
tickets {
int id
UUID uuid
int session_id
int seat_id
}
addresses {
int id
UUID uuid
string country
string state
string telephone
string description
string postal_code
string name
}
movies ||--o{ sessions : has
movies ||--|| posters : has
sessions ||--|| cinemas : occurs
cinemas ||--|{ seats : has
sessions ||--|{ tickets : has
seats ||--|{ tickets : has
cinemas ||--|| addresses : located
The API is being developed following RESTful guidelines at maturity level 4 for educational purposes. Hal Explores can be used to navigate and validate consistency with the specification by simply accessing a local tests URL http://localhost:4200/#uri=http://localhost:8080/v1/ with the application running. See the Hypertext Application Language for more details .
Local URLs:
- Prometheus - http://localhost:9090/
- Grafana - http://localhost:3000/ (user/pwd: admin - admin | admin - 12345)
The volume data is not shared in this repository. To use the 'catalogo-api' project dashboard, it will be necessary create a Datasource aiming your prometheus URL http://prometheus-ticket:9090 and import the corresponding JSON on `scripts/grafana-dashboards/dash-catalogo-api.json` into your local Grafana after the proper installation of the project:
The JSON file is located in scripts/grafana-dashboards
- 0001: Record architecture decisions
- 0002: Gin, Gorm and Postegres in two tier architecture
- 0003: Prometheus Libs To Instrumentation
- 0004: Integration Tests "Happy Path"
- Conventional Commits
- Keep a Changelog
- ADR - Architecture Decision Records
- Event Storming
- Miro Diagrams
- Mermaid Diagrams
- Swagger
- RESTful
- HATEOAS
- High Rest Maturity Model
- Observability with:
-
Language:
-
Framework & Libs:
-
Infra & Technologies
Version tags are being created manually as studies progress with notable improvements in the project. Each feature is developed on a separate branch, and when completed, a tag is generated and merged into the master branch.
For more information, please refer to the Version History
The header figures on this page were created with the help of artificial intelligence and a minimum of retouching and construction in Gimp 
The following prompts were used, in PT-BR, for creation in Bing IA:
Gopher Cinema Director
"Gopher simbolo da linguagem golang azul em cores cartoon chapadas como diretor de cinema, sentado em uma cadeira caracteristica, segurando uma camera e com uma claquete no chão"(sic)AI also helped in some research in this study by being used as a support tool; however, arts and development are, above all, human creative activities. Value people!
Hire artists for commercial or more elaborate projects and Learn Ingenuity!