Goggle

A free word game!

Development

Requirements

Go
Node.js
Yarn
- npm install -g yarn
(Optional) Terraform v0.14.6
- Only required if you plan on working on infrastructure.
(Optional) AWS CLI
- Only required if you plan on deploying the backend or client to production.

Quick Start

We use make for easy-to-run shortcuts. Each shortcut will print out the commands it runs, if you're curious.

Run the backend. The backend listens on http://localhost:8081 and ws://localhost:8082.
```
$ make run-backend
```
In a second terminal, run the client. This serves the web client on http://localhost:5000, which you can open in a web browser.
```
$ make run-client
```
Tip: By default, the client runs against the local backend API server. To run against the production API, run this instead:
```
$ PROD_API=1 make run-client
```

Everything should be running. You can work on the client code and it will hot-reload in your browser at http://localhost:5000. The backend code doesn't hot-reload, so you'll need to re-run make run-backend after making changes.

About the Stack

Backend

The backend is written in Go and consists of a REST API and a websocket API. The REST API is the main API. The websocket API is used to push realtime data to connected clients.

When running the backend locally these APIs are listening on ports 8081 and 8082; however in production the backend is deployed to AWS Lambda functions, fronted by an AWS API Gateway. That is why the ./backend/cmd/httpbackend command, which is used to run the local server, looks so different from ./backend/cmd/restapi and ./backend/cmd/wsapi, because the latter two are Lambda functions.

The REST API code lives in the ./backend/restapi project directory, and the websocket API code lives in ./backend/wsapi.

The primary backend library to know is Gin.

After making changes to the REST API code, run make gen-tsclient to regenerate the Typescript client and models.

Client

The client is written in Svelte, which is a component-based Javascript library that is known for producing small Javascript builds and requiring very little boilerplate code.

The ./client project directory is a typical Node.js project structure.

We use the Typescript language for code and Less for styles.

References

go-swagger

The ./backend/wsapi code is annotated using go-swagger annotations to aid Typescript client code generation.

materialify

Documentation for the Svelte Materialify CSS framework, which is based on Material Design.

Deployment

Deployment to production happens automatically inside GitHub Actions on pushes to the main branch.

You can also deploy to production by running make deploy. This requires AWS credentials in a "goggle" named profile. See how to set up a profile here.

$ make deploy

Using the APIs

Try the REST API.

$ curl http://localhost:8081/hello
{"message":"Sorry, no games here."}

Try the websocket API.

$ npm install -g wscat  # Install this once if you do not have it
$ wscat -c ws://localhost:8082
Connected (press CTRL+C to quit)
> hello
< Sorry, no games here either!

Production APIs