# README
Questionmate
Questionmate is a library and API for building configurable online surveys. Surveys are modeled in a YAML based DSL:
questions:
- id: 1
text: Which programming languages does the system use?
type: single
options:
- value: 1
text: modern (e.g. go, Rust, Swift)
targets:
- sustainability: 3
- value: 2
text: standard (e.g. Java, C/C++, JavaScript, Php, Ruby)
targets:
- sustainability: 2
- value: 4
text: expiring (Cobol, Delphi)
targets:
- sustainability: 1
A survey consists of a list of questions. A question consists of its id (1), it's text, a type (single or multi) and a list of options (modern, ...). An option can have one or more targets (sustainability) associated with a credit value (3).
Credits
Users can select one or more of the question's options, depending on the question type. A selected option pays into its associated targets. For instance, option 1 modern pays 3 credits into the target sustainability.
Question order
Questions are served in a natural order defined by their ids, thus question 2 follows question 1.
Assessment
At the end of answering a survey an assessment of the given answers can be requested. An assessment consists of a list of targets each associated with its resulting score, modeled by the following go types:
type Target struct {
Text string
Score int
Rating string
}
type Assessment struct {
Targets []Target
}
A targets score is calculated by adding up all credits configured for the target based on the given answer set, e.g. if question 1 pays 3 credits into sustainability and question 5 pays 1 credits into sustainability the target will get an overall score of 4.
A target might contain an optional rating description that explains or assesses the meaning of a targets score.
API
POST http://questionmate.tullo.net/{questionnaire}/questions
Returns the next question according to the answers the user has given so far contained in the request body as follows:
{
"answers": [
{
"question_id": 1,
"value": 1
}
]
}
HTTP/1.1 200 Ok
{
"id": 2,
"text": "How often do incidents occur without first changing the software?",
"type": "single",
"options": [
{
"value": 1,
"text": "almost never",
"targets": {
"robustness": {
"value": 10
}
}
}
]
}
POST http://questionmate.tullo.net/{questionnaire}/assessment
Returns the assessment of the answers contained in the request body as follows:
{
"answers": [
{
"question_id": 1,
"value": 1
}
]
}
HTTP/1.1 200 Ok
{
"targets": [
{
"text": "robustness",
"score": 3,
"rating": "Your software isn't very robust. You have to fix it soon."
},
{
"text": "sustainability",
"score": 7,
"rating": "Your software is sustainable enough."
}
]
}
Architecture
Questionmate's design is based on hexagonal architecture ideas. Thus, it focuses on its domain model and rules but makes no assumptions about how this model is used within a specific context, e.g. the web.
Instead of forcing programmers to use Questionmate within a specific context examples are given about how to use the library wrapped as REST services deployed to AWS lambda.
Domain Model
Questionnaire --> *Question --> *Option --> *Target
1 1 *
| | |
| | |
Answer --------/ Assessment
A Questionnaire consists of many Questions. A question has many options, whereby each options represents a possibe answer. Each option has many targets to which this option pays.
An answer models a user's answer to a question, thus the answer's values must match one of the option values of its question.