initial commit

docs/rfc/frontend-generator.md

@@ -0,0 +1,42 @@
+# Code generation for a React frontend
+
+Our system is build on a Fact Graph and a Flow. The Facts have no awareness of presentation concerns, while the Flow encapsulates ordering and grouping of questions, along with pointers to human language translations of user-facing questions.
+
+### Tom's suggestions:
+
+
+Facts will have some properties:  
+- A way of getting graph specified validation into the system
+- A way of referring to other constraining facts (charitable deduction for marital status)
+- A name or identifier for being found and focused later
+
+This tends to indicate that there should be some version of the fact graph in memory on the client side.
+
+Each page will also need to have some properties:
+- A series of templates for different page styles and layouts -- how will people know which to use?
+- Well defined results for front and back actions
+- The ability to jump to an arbitrary page (maybe by fact alone)
+- A post action that sends the current state to the server
+- Analytics
+
+Because of the well ordered nature of the flow, and the need to be able to identify where facts are, we should use something like an FSM flow for pages.  The actions above represent transitions to other states. 
+
+
+Page Information Singleton:
+There can only ever be one of these in the system.  The page information singleton contains the generated configuration that the front end understands.  This configuration contains things like the IDs and friendly names, a dictionary of <fact name, page> so that individual facts can be found.  
+
+Page Manager FSM:
+Each page is some data about what to display and how.  It has a view template that lays out the page, zero or more fact templates that are applied to that template, a defined forward action, a defined back action, and ID for the page, and a friendly name for the URL.  As the user works their way through the flow, the page manager will pull the information about which page to display from the Page Information Singleton
+
+
+The implication here is that an external system generates the React frontend system.  We start with a template react frontend that has the css and some of the basic tools in it.  This external system then generates all of the pages, the frontend configuration for the page information singleton, and there are probably a few other pieces.  Most of the fuzz is around the review step and how that will look in an autogenerated system.  What I don't think will look good is if we just link directly back to the page in the flow without some indication that you are in the review process.  I would also want the forward and back to go back to the review section and not start you into the flow again.
+
+Testing:
+We should be able to, in an automated way, run through the entire frontend application and verify that all of the paths work, all of the validators work, all of the constraints work, and that the product produces correct results.
+
+Questions:
+Will a page ever need alternate layouts?  I am imagining a review section in which we may want forward and backward to work completely differently, and for the site to maybe look a bit different.
+
+Should the site be generated on some other backend or should it kind of generate itself?  I can imagine, if the need for multiple templates happens, that it would be nice to have a system that can dynamically generate itself.  I can see massive problems with it too (like testing completeness).
+
+