@@ 7,11 7,61 @@
@s Introduction
-This program implements a **rules engine** for Tamerlane, the Card
-Game Server. It provides a working version of the game Bid Whist, as
+This program implements a **rules engine** for Tamerlane, the card
+game server. It provides a working version of the game Bid Whist, as
well as an example implementation of a realistically complex rules
engine.
+@s About This Document
+
+This is a **literate program** which describes the full implementation
+of a rules engine for Tamerlane. In it is contained all the source
+code required to compile and run a web server which implements
+Tamerlane's API contract.
+
+This code is written using the [Literate][literate] program, which takes a
+literate source document and renders the document you are reading, as
+well as the source files needed to compile the program.
+
+[literate]: http://literate.zbyedidia.webfactional.com/
+
+The language that I've implemented this software in is [Janet][janet],
+a lightweight lisp. To thoroughly understand the implementation it
+might be good to know Janet, or at least a language like Clojure or
+Scheme. To be able to follow along and understand what you need to
+implement in order to write your *own* rules engine (which is the
+purpose of this document), you don't need to know Janet. You just need
+to understand some basic Lisp control forms like `let` and `defn`, and
+to understand how to read an s-expression.
+
+[janet]: https://janet-lang.org/
+
+You should be able to read this document front-to-back, like a
+book. I've tried to focus on the concepts that are central to the
+function of the Tamerlane rules engine concept. Therefore, the bulk of
+this document is concerned with writing the business logic that
+defines the rules to the game Bid Whist. Also important is
+understanding the specifics of the endpoints and HTTP methods that are
+expected by Tamerlane.
+
+Other implementation details are handled in appendices at the end of
+the document. I've tried to make the code as readable and effective as
+possible, but it should be less crucial to this document's purpose as
+a guide for writing a games engine for Tamerlane.
+
+@s Bid Whist
+
+The game of Bid Whist is, as its name suggests, a descendent of the
+old English game of Whist, and a cousin of the game Bridge.
+
+A full copy of the rules are available at
+[Pagat](https://www.pagat.com/auctionwhist/bidwhist.html). I've tried
+to reproduce them faithfully and completely; one notable exception is
+that I've opted to allow the auction to go around until all players
+have passed instead of having it go exactly once around the table.
+
+## The Tamerlane Arhitecture
+
@s Rules Engine Architecture
Here's a simplified sequence diagram illustrating how a player
@@ 1182,6 1232,8 @@ is still very much in development.
In Janet, the standard web framework is [Joy][]; we'll define an
extremely simple API using that library.
+[joy]: https://joyframework.com/
+
--- main.janet
(import json)
(import init)