From 0c496299a026d69719b04fc58d3e947a588c5fea Mon Sep 17 00:00:00 2001
From: Mike Gerwitz <gerwitzm@lovullo.com>
Date: Wed, 15 Mar 2017 15:31:09 -0400
Subject: [PATCH] design.texi: Add initial component descriptions

---
 doc/Makefile.am |  2 +
 doc/design.texi | 98 +++++++++++++++++++++++++++++++++++++++++++++++++
 doc/liza.texi   | 12 +++++-
 doc/macros.texi | 22 +++++++++++
 4 files changed, 132 insertions(+), 2 deletions(-)
 create mode 100644 doc/design.texi
 create mode 100644 doc/macros.texi

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 6c8843b..503b988 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -19,3 +19,5 @@
 ##
 
 info_TEXINFOS = liza.texi
+liza_TEXINFOS = design.texi macros.texi
+
diff --git a/doc/design.texi b/doc/design.texi
new file mode 100644
index 0000000..3de2be8
--- /dev/null
+++ b/doc/design.texi
@@ -0,0 +1,98 @@
+@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
+
+@emph{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 Assertion
+  @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.
+
+  @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.
+
+  @cindex Calculated Value
+  @item Calculated Values
+  A small sub-system for calculating bucket values from other values.
+
+  @cindex Client
+  @item Client Interface
+  Basic logic for navigating between steps,
+    prompting for user actions,
+    display help text and basic document data,
+    communicate with server,
+    etc.
+
+  @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.
+
+  @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.
+
+  @cindex Program, XML
+  @item Program XML
+  The source code for a program, in XML format.
+
+  @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.
+@end table
diff --git a/doc/liza.texi b/doc/liza.texi
index f0a3855..c0d5c1d 100644
--- a/doc/liza.texi
+++ b/doc/liza.texi
@@ -52,13 +52,21 @@ Free Documentation License''.
 @top Main
 @end ifnottex
 
-@c This is where @menu will go
+@menu
+* Design and Architecture:Design.  Design and structure of framework
+* Concept Index::
+@end menu
 
 @ifnottex
 
 @insertcopying
 @end ifnottex
 
-@c This is where the includes will go.
+@include macros.texi
+@include design.texi
+
+@node Concept Index
+@unnumbered Concept Index
+@printindex cp
 
 @bye
diff --git a/doc/macros.texi b/doc/macros.texi
new file mode 100644
index 0000000..0224276
--- /dev/null
+++ b/doc/macros.texi
@@ -0,0 +1,22 @@
+@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''.
+
+@c insert appropriate em dash for mode
+@iftex
+@macro mdash{}
+---
+@end macro
+@end iftex
+
+@ifnottex
+@macro mdash{}
+—
+@end macro
+@end ifnottex