carddeck

Go REST API for playing cards

Prerequisites

Go (1.22.X). You may use gvm to manage multiple go version.
Docker, for running dependencies
make (optional, most unix already have this)
Postgres (alternatively if you want to install the dependencies in local)

How to Run (Unix)

Build the application

Executing following command to build the application

go build . -o carddeck

(alternatively)
make build

Copy .env.sample to .env file

Copy .env.sample file to .env file, change the value if needed. The default value provided is already working with docker compose setup.

cp .env.sample .env

Spin up dependencies

Run docker compose to spin up dependencies

docker compose up -d

Run the application

Execute following command to run the application. The application will be available in localhost:8080 by default.

.\carddeck

(alternatively#1) 
make run

(alternatively#2, if you don't want to build the app) 
go run . server

Shutting down dependencies

docker compose down

Project Structure

cmd/: This directory contains entrypoint for each binary available by this project. Though for this project, I'd like to use single entrypoint using cobra CLI. Hence, there is no cmd folder and the entrypoint is located in the root dir (main.go).
bin/: This directory contains executable scripts or binary files. These scripts are usually meant to be run directly from the command line.
config/: Configuration files for the project reside here. This may include environment-specific configurations, settings, or any other configuration needed by the project.
db/: Database related files or scripts are stored here. This may include database schema definitions, migration scripts, or seed data.
docs/: Documentation related to the project is placed here. This could include user manuals, API documentation, architecture diagrams, or any other relevant documentation.
modules/: This directory contains the business usecases, repository, handler grouped by module.
modules/{module_name}.go: The "builder" / "glue" code that expose the module to outside world.
modules/{module_name}/entity/: Contains the reusable entity for that module. Typically can be used across modules.
modules/{module_name}/internal/rest/: Contains rest related driver code. Typically your REST API Handler.
modules/{module_name}/internal/service/: Contains usecases for this module. It contains business logic.
modules/{module_name}/repository/: Contains driver code to communicate with external parties or dependencies. Typically for your database, cache, and cloud services.
test/: This directory contains mock code generated by script.

API Blueprint

You can access localhost:8081/swagger/ to see available APIs.

Possible Improvement

Docker run for each step in makefile is expensive as they require us to install all the dependencies all over again for each run.
DrawCards API takes n number of cards and return them to client. If the server crashed or the client close connection, we might found condition where those n cards are gone and untrackable. The current deck then become unplayable.
- Introduces new entity called card_stack or card_pile. They are basically just like deck, can store cards, and have operations such as DrawCards too.
- DrawCards operation takes n cards and move it to destination stack / pile. This way, cards are always persisted somewhere.
- Above system mapped to various card games:
  - Blackjack. 1 Deck, n-number of card stacks for players. 1 card stack for dealer. Whenever DrawCards called, it will move card to one of those card stack.
  - Solitaire/Klondike. 1 Deck, 7 card stacks (for card column), 4 card stacks for the goal. 1 card stack temporary pile for players to put cards.
  - Poker. 1 Deck, n-number of card stacks for players. 1 card stack for the dealer.
State management for each game are outside of carddeck API usecases.

raymondwongso/carddeck