Mike Gerwitz

Activist for User Freedom

aboutsummaryrefslogtreecommitdiffstats
blob: 7d197e32c87eba564a0726d02f79a7740bd3bf4f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
@c  This document is part of the Liza Data Collection Framework manual.
@c  Copyright (C) 2017 LoVullo Associates, Inc.
@c
@c    Permission is granted to copy, distribute and/or modify this document
@c    under the terms of the GNU Free Documentation License, Version 1.3
@c    or any later version published by the Free Software Foundation;
@c    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
@c    Texts.  A copy of the license is included in the section entitled ``GNU
@c    Free Documentation License''.

@node Design
@chapter Design & Architecture

@notice{
  N.B. This document may reference features that are not yet
    present in Liza; they will be moved into this repository in time.}

Liza is fundamentally a data collection framework@mdash{
  }a fancy form for collecting, validating, and lightly processing
  user data.

The main components of the system are:

@table @strong
  @cindex Assertions
  @item Assertions
  Basic validations against bucket data,
    producing errors and manipulating control flow.
  Invokes triggers to manipulate the UI and document.
  Assertions are compiled from Program sources.
  @xref{Assertions}.

  @cindex Bucket
  @item Bucket
  The key/value store into which all document data are stored.
  Supports staging and rollback of data,
    processing deltas,
    and provides hooks that drive the rest of the system.
  @xref{Bucket}.

  @cindex Calculated Value
  @item Calculated Values
  A small sub-system for calculating bucket values from other values.

  @cindex Client
  @item Client
  Basic logic for navigating between steps,
    prompting for user actions,
    display help text and basic document data,
    communicate with server,
    etc.
  @xref{Client}.

  @cindex Developer Dialog
  @item Developer Dialog
  Renders information about the system for debugging the client.
  Can monitor the bucket, assertions, classification results, and
    provides other useful features.

  @cindex Predicate
  @item Predicate System
  Processes classification data from external classifiers to determine
    applicability of specific questions.
  These data are used to determine what assertions are performed,
    what questions and groups display,
    and more.

  @cindex Program
  @item Program
  Internal representation of the Program with delegation of events to
    the assertion system.
  Contains compiled representation of all steps, groups, questions,
    assertions, metadata, and others.
  @xref{Program}.

  @cindex Program, User Interface
  @cindex User Interface, Program
  @item Program UI
  Rendering of elements specific to Programs,
    such as steps, groups, and questions.
  This is the equivalent of an HTML form.
  Directly monitors the bucket to perform UI updates.
  @xref{Program UI}.

  @cindex Program, XML
  @item Program XML
  The source code for a Program, in XML format.
  @xref{Program XML}.

  @cindex Server
  @item Server
  Provides REST API for serving Programs; saving data;
    revalidating, filtering, and recalculating data;
    and other types of processing.
  Code is shared with the client,
    ensuring identical behavior for appropriate behaviors.

  @cindex Type Validation
  @cindex Validation, Type
  @item Type Validation
  Validates and formats bucket values for specific field (question)
    types.
  For example, a date field must be in a recognized date format,
    and will be normalized for display.
  @xref{Validation}.
@end table

More information about each can be found in their respective section.


@menu
* Assertions::
* Bucket::
* Client::
* Program::
* Program UI::
* Program XML::
* Validation::
@end menu



@node Assertions
@section Assertions
@maintenance{
  Assertions are compiled from the Program XML (@pxref{Program XML}).
  Rather than using a library,
    it compiles a mess of largely duplicate code inline.
  This system needs to be @emph{replaced},
    not modified.

  A replacement can either be in the form of a library (removing most
    if not all code generation from the Program XML compiler),
      or possibly compile into classifications and use the classification
      system.
  @emph{The latter option is preferred,
          and would be more powerful with less maintenance.}}

@helpwanted



@node Bucket
@section Bucket
@helpwanted

@menu
* Value Assignment:Bucket Assignment.  Writing data to the Bucket.
@end menu


@c TODO
@node Bucket Assignment
@subsection Bucket Value Assignment
@helpwanted



@node Client
@section Client
@maintenance{
  The client is largely managed by a single class,
    @srcref{src/client/Client.js, Client},
    which has grown out of control.
  @code{Client} mediates essentially the entire system.
  Code is to be extracted out of this class as it is touched.}

@helpwanted

@menu
* Error Handling::
@end menu


@node Error Handling
@subsection Error Handling

@maintenance{
  The complexity of this system and integration into legacy
    layers has caused maintenance trouble in the past.
  Each of the error checking layers need to be integrated
    to reduce complexity.}

@cindex Error
@cindex Failure
There are three layers of error checking:@footnote{
  Primarily for legacy reasons.
  They are being consolodated as the system is touched.}

@enumerate
  @item Required field checking@mdash{
    }whether all required questions have been answered.
  @item Type Validation@mdash{
    }verify that questions contain valid data according to their
    declared type. @ref{Validation}.
  @item Assertions@mdash{
    }arbitrary checks on data.
    @ref{Assertions}.
@end enumerate

@cindex Required Field
@cindex Field, Required
@cindex Field, Fixed
@cindex Error, Fixed
@cindex Error, Required
@cindex Fixed, Error
Required fields fail serially@mdash{
  }the system will notify the user of the required field,
    and direct him/her to it (usually through scrolling).
A field is marked as @dfn{fixed} according to the rules
  in @ref{Managing Error State}.


@menu
* Managing Error State::  Determining when failures should be marked as ``fixed''
@end menu


@node Managing Error State
@subsubsection Managing Error State

@cindex Failure Stack
@cindex Error Stack
Each failure caused by assertions is associated with a
  @dfn{failure stack}.
The stack represents the trail of assertions that have run,
  containing the ids of all values asserted against.
When any field or classification changes that is represented on the
  failure stack,
    the failure for the failed field associated with that failure stack
    is cleared.

@exnotice{
  If an assertion for some question @var{foo} first checked the value
    of bucket field @var{bar},
    and within its failure checked the value @var{c:predicate},
    the failure stack would contain both of those ids.
  If either @var{bar} or the @var{predicate} classification changed,
   the question @var{foo} would have its error cleared.}

Error state is managed by
  @srcref{src/validate/ValidStateMonitor.js, ValidStateMonitor}.


@node Program
@section Program
@maintenance{
  The @code{Program} class was one of the first prototypes created,
    and has evolved poorly with the rest of the system.
  It is the base class for all compiled programs,
    and it glues together too many other systems with a terrible
    API and little to no encapsulation.

  With that said, it is one of the least touched classes (thus its
    state); developers rarely have the need to touch @code{Program}.}

@mvnotice{
  The core @code{Program} class that causes maintenance concerns needs
    to be added to Liza.
  It is currently mocked as necessary in test cases.}


@cindex Program
The @dfn{Program} is a declarative representation of an entire system.
It is the highest level of abstraction from a data perspective.
The user observes and interacts with a Program using the
  @ref{Program UI,,Program@tie{}UI}.

@cindex Program, XML
Programs contain a lot of metadata that is not in a convenience
  human-readable (or modifiable) format,
    some of which are redundant.
Programs are ideally compiled from a @ref{Program XML,,Program@tie{}XML}
  document.



@node Program UI
@section Program UI

@cindex Program, User Interface
@cindex User Interface, Program
The @dfn{Program UI} renders a @ref{Program} as a form.

@cindex Step
@cindex Group
At the highest level,
  steps are rendered in a tab-like manner,
  above the main form content.
A step contains groups,
  which in turn contain elements such as questions.
Groups are delimited in some manner defined by their style
  (@pxref{Group Styles}).

@cindex Question
@cindex Question, Value Formatting
@cindex Bucket, Updating
Questions are rendered as form fields.
Any time the respective @ref{Bucket} field is changed,
  the form field is updated to reflect those changes,
    after having first been formatted with the appropriate validator
    (@pxref{Formatting Values}).
When a question is changed by the user,
  the value is expected to be propagated to the Bucket
  (@pxref{Bucket Assignment}).

@cindex Navigation Bar
@cindex User Interface, Navigation Bar
@cindex User Interface, Button Navigation
Navigation between steps can be done via the
  @dfn{Navigation Bar} above the step@tie{}content,
  or using ``Go@tie{}Back'' and ``Continue'' buttons at the foot of the
  step@tie{}content.

@cindex Sidebar
A @dfn{Sidebar} is rendered adjacent to the step content.
It displays the name of the Program,
  as well as configurable metadata (usually through the @samp{sidebar}
  node of the @ref{Program XML,,Program@tie{}XML}).
It also displays question help text (also configured through the XML)
  and any error messages (@pxref{Error Handling}).

@menu
* Group Styles:: Different ways of displaying groups of questions to
                 the user.
@end menu


@node Group Styles
@subsection Group Styles

@cindex Group, Styling
Groups support a number of @dfn{group styles} that determine how
  they are delimited from other groups;
  how the elements they contain are rendered and laid out;
  and how multiple indexes are displayed, added, and removed.

@multitable @columnfractions 0.15 0.65 0.10 0.10
  @headitem Name @tab Description @tab Multi-Index? @tab Add/Remove Index?

  @item @samp{default}
  @tab
  Groups are unstyled by default@mdash{
    }they render elements as flat fields like a traditional form.
  Only the first index of elements is rendered.
  @tab@center N
  @tab@center N

  @item @samp{collapsetable}
  @tab
  Renders element label in the leftmost column like @samp{sidetable}.
  Indexes are groups of rows delimited by headings,
    which collapse the respective group of rows when clicked.
  @tab@center Y
  @tab@center Add

  @item @samp{sidetable}
  @tab
  Renders elements as rows with label in the leftmost column rather
    than the top row.
  Each index is rendered as a column.
  @tab@center Y
  @tab@center Add

  @item @samp{tabbedblock}
  @tab
  Each group is rendered as a block,
    with each index rendered as a tab to the right of it.
  Clicking a tab toggles the body content to the associated index.
  Elements are rendered within the box.
  @tab@center Y
  @tab@center N

  @item @samp{tabbed}
  @tab
  Like @samp{default},
    but each index has a tab at the top of the group.
  Clicking a tab toggles the body content to the associated index.
  @tab@center Y
  @tab@center Y

  @item @samp{table}
  @tab
  A vanilla table with elements as columns,
    their labels across the top row.
  Each index is rendered in its own row.
  @tab@center Y
  @tab@center Y
@end multitable



@node Program XML
@section Program XML
@helpwanted


@node Validation
@section Validation
@helpwanted

@menu
* Formatting Values::
@end menu


@node Formatting Values
@subsection Formatting Values

@cindex Question
@cindex Question, Value Formatting
@helpwanted