Igroteka

This is the backend API for my gaming backlog app. I use it on a daily basis to keep track of video games I played/want to play/playing now. It uses IGDB, howlongtobeat.com and opencritic.com as data sources. You can read more about this project on my personal website.

Prerequisites

• twitch API client id for IGDB API
• Opencritic API key
• elixir
• postgres

Run locally

Add config/dev.secret.exs file with the following contents:

import Config

config :skaro, :igdb,
  client_id: "your_twitch_client_id",
  client_secret: "your_twitch_client_secret"

config :skaro, :opencritic, api_key: "your_opencritic_rapidapi_key"

config :skaro, Skaro.Repo,
  username: "your_postgres_user",
  password: "your_postgres_user_password",

Run the following commands to setup dependencies and create the database:

mix deps.get
mix ecto.setup

Run server:

mix phx.server

Verify that it is running by navigating to http://localhost:4000 in your browser: if you see message "Welcome to skaro" then it's running.

After that you can setup and run frontend app. To use it navigate to http://localhost:3000 and login with [email protected]/12345678. Have fun testing the app!

Run tests

mix test

Lint

mix credo --strict

Deployment

I run the app on fly.io. See the Fly.io documentation on running an Elixir application here. The release configuration is in the fly.toml.

TLDR: perform first deploy by running fly launch and subsequent deploys by running fly deploy.

CI

This repository uses GitHub Actions to deploy from master branch. The main.yml file defines the single workflow (for now) - fly.io deployment.

How do we model gaming backlog

TODO: move this to hexdocs.

Phoenix contexts are used to model different domains that exist in this app.

Accounts

Authentication and user management.

Models:

• User - root aggregate of this context, represents an application's user.

Function modules:

• Users - CRUD actions to manage users.
• Sessions - authentication code.

Core

In Igroteka "Core" means "everything related to Game that is our core domain".

Models:

• Game - root aggregate, represents a video game.
• Company - represents a gamedev company (might be developer or publisher or both).
• Platform - platform where the game was released at some point in time (for example PlayStation 2 or NES).
• Genre - genre(s) that game belongs to (Action, RPG, etc).
• Theme - theme of the game.
• Image - screenshot or poster for the game.
• Video - video about this game on external resource (YouTube).
• Franchise - franchise the game belongs to (eg. Zelda, Mario, God of War).
• ExternalLink - link to some external resource (for example official website, twitter account).

Function modules:

• Core - functions that find and return games using IGDB services.

Backlog

This context deals with user's backlog - all the games that user wants to play or played in the past or playing right now. Backlog context revolves around the concept of "Entry" that represents a single game in user's backlog.

The most important attribute of Entry is status which can be one of the following:

• wishlist - games that user would like to buy
• backlog - games that user owns but did not play yet
• playing - games that user plays right now
• beaten - games that user played and considers to be "done"

Models:

• Entry - root aggregate, represents a single game in user's backlog.
• AvailablePlatform - an additional model that represents a platform where the game from the given backlog entry was released. This model exists because we need to provide a way for the user to select on which platform they are going to play this game.

Function modules:

• Entries - CRUD operations for Backlog context.

Playthrough

Playthrough context deals with data on what would it take to beat the game.

Models:

• PlaythroughTime - connected to Game, represents hours one needs to beat the game in one of the playstyles (Main Quest / Main + Side Quests / Completionist).

Interfaces:

• Remote - defines behaviour for any service that fetches playthrough data from external provider.

Function modules:

• Playthrough - fetches from remote and stores playthrough data.

Reviews

Reviews context works with critics scores and reviews for games.

Models:

• Rating - represents median critics score and samples of critics reviews.

Interfaces:

• Remote - defines behaviour for services that fetch reviews from external provider.

Function modules:

• Reviews - fetches from remote and stores scores and reviews data.

IGDB

This context encapsulates code that talks to IGDB API. NOTE: Not a domain context as it doesn't have any models.

Function modules:

• IGDB - calls IGDB API and parses the JSON response to produce Core models.
• Token - fetches API token from Twitch.

Howlongtobeat

This context has functions that scrape and parse howlongtobeat.com pages. NOTE: Not a domain context as it doesn't have any models.

Function modules:

• Howlongtobeat - context facade, implements Remote interface from Playthrough context.
• Client - retrieves and parses information from https://howlongtobeat.com.

Opencritic

This context provides a way to work with Opencritic API. NOTE: Not a domain context as it doesn't have any models.

Function models:

• Opencritic - context facade, implements Remote interface from Reviews context.
• Client - calls Opencritic API and parses the response.
• Mapper - provides transformations for Opencritic data.

API

This app provides REST-like API for a frontend application. The following endpoints are provided:

SessionController

POST /sessions - creates session from email and password provided in body; returns JWT token.

UserController

GET /current_user - returns user info based on authentication header

GET /users/{id} - returns user info by ID

PUT /users/{id} - updates user's info

PUT /users/{id}/update_password - changes user's password

GameController

GET /games - filters and returns a list of games from IGDB (possible filters are: by developer, by publisher, by search term, new games, top games overall, top games by year)

GET /games/{id} - returns game's info from IGDB by game ID

BacklogEntryController

This resource manages backlog entries aka games that are in your backlog.

GET /backlog_entries - filters backlog entries for current user

GET /backlog_entries/{id} - returns backlog entry

POST /backlog_entries - adds the game to the backlog

PUT /backlog_entries/{id} - updates backlog entry

DELETE /backlog_entries/{id} - removes the game from the user's backlog

BacklogFilterController

GET /backlog_filters - returns filters view model for user's backlog (available release years and platforms for example)

ScreenshotController

GET /screenshots - returns a list of screenshots for a given game

PlaythroughTimeController

GET /playthrough_times/{game_id} - returns info on how long is the game to play

ReviewController

GET /reviews/{game_id} - returns critics rating and reviews for the game

CompanyController

GET /companies/{id} - returns information about game development company (developer or publisher)