Challenges: flow, architecture and tooling

[joeljuca]

Dsafio provides coding challenges that let people practice their programming skills. We must discuss and decide about the flow our users will be using, how the architecture will look like, as well as the tooling used to test users' solutions.

Flow

Initial setup

1. User installs Dsafio CLI: npm i -g dsafio
2. User runs a dsafio command or subcommand for the first time
3. dsafio detects a new environment, starts the setup wizard and:
   1. setup user data
   2. download the challenge registry
   3. setup working directory
   4. download the first challenge

The loop

1. User codes a solution that passes all tests
2. User runs dsafio test to run tests and:
   • returns to step 1 on failure
   • receives a congratulatory message that suggests him/her to download the next challenge
3. User run dsafio next and it
   1. uses the registry data to identify the next challenge
   2. download the next challenge and setup the working directory

Architecture

I'm looking at GitHub API v3 and thinking in a way to keep just a static registry of challenges as a Git repository. Since we will not be storing user information during the alpha stage the registry can be just a static JSON file present in a GitHub repository.

The Repository Contents methods allow the recovery of specific files from a given repository. With this capability we could:

• load a static registry of challenges (e.g.: registry.json)
• download specific challenges described in the registry (e.g.: challenges/hello-world)
• build the challenges track based on the order of disposal in the registry
• keep the user progress locally

It could solve the back-end needs in a very sophisticated way. GitHub as back-end = 🤘😎

Tooling

We can start with Mocha as unit testing tool but suggestions are welcome. We are prioritizing smaller download sizes and friendly output messages, but we still have a lot to discuss and learn on this matter.

[joeljuca]

Thoughts about the structure of the challenges repository:

1. we'll need a central registry of all challenges (a registry.json on root?)
2. we'll also need a metadata file for each challenge (challenge.json?)
3. a challenge description file (readme.md?)
4. a challenge test suite (<challenge-name>.test.js?)
5. a starter file (index.js? <challenge-name>.js?)

This way, the challenge repository would look like this:

registry.json
challenges/
  <challenge-name>/
    challenge.json
    readme.md
    index.js
    <challenge-name>.test.js

FYI: it looks a lot like the Exercism directory structure for exercises.

[joeljuca]

Maybe we should adopt test.js as test file name instead of <challenge-name>.test.js. This way we'll have a pattern to follow, and it seems even better.

[joeljuca]

Insights after discussions off-GitHub:

1. the challenge.json is not necessary; we should use registry.json for all metadata
2. the test file should be always test.js

The challenge repository would now look like this:

registry.json
challenges/
  <challenge-name>/
    readme.md
    index.js
    test.js

[joeljuca]

Something I haven't been discussing in this issue is how challenge data will be stored in users' environments. I messed up the issue tracker with multiple separated issues about specific topics, but centralizing everything here will keep the context of the discussion. So, I'll be reporting decisions taken from other issues over here.

[joeljuca]

On #19 we discussed how we should store data in users' environments (mostly their computers and laptops). We'll rely on the XDG Base Dir spec.