1 files changed, 111 insertions, 0 deletions

diff --git a/architecture.mdwn b/architecture.mdwn
new file mode 100644
index 0000000..fccf309
--- /dev/null
+++ b/architecture.mdwn
@@ -0,0 +1,111 @@
+[[!meta title="Architecture"]]
+
+[[!toc ]]
+
+# Architecture overview
+
+## Assumptions
+
+The architecture has been designed under the following assumptions:
+
+* Privacy is important, and should be the default. People should only
+  have access to the information they are authorized to access.
+
+* Members should be able to see their own information, without having
+  to go through the Effi membership register admin.
+
+* It's not practical to have every member have a password.
+  Authentication can be done by sending the member a unique,
+  single-use link when they want to log in.
+
+## Components
+
+[[!img arch.png]]
+
+Effireg consists of four main components:
+
+* **effiapi** provides a RESTful HTTP API for managing the membership
+  data, and for doing things with or to the data. All operations go
+  via the API.
+
+* **effiweb** provides the frontend for the web application to use the
+  membership register. It renders HTML to the user, is accesses via a
+  web browser, and generally is the user-visible part of Effireg.
+
+* **Qvisqve** provides authentication of end-users (the members, and
+  admins). It lets users log in, and keeps track of what each user is
+  allowed to do.
+
+* **Muck-POC** stores the actual membership register data, and
+  controls access to it, based on access tokens from Qvisqve.
+
+## Authentication
+
+[OpenID Connect]: https://openid.net/specs/openid-connect-core-1_0.html
+[OAuth2]: https://oauth.net/2/
+
+End-users are authenticated using the [OpenID Connect][] protocol,
+specifically the authorization code flow. In this flow, Qvisqve
+provides cryptographically signed access tokens, which identify the
+user and specify a list of things the user may do. The signature
+guarantees the token comes from Qvisqve.
+
+Non-interactive API clients are authenticated using the [OAuth2][]
+protocol, specifically using client credential grants. This also
+provides an access token, similar to the one from end-user
+authentication.
+
+# Data model
+
+The membership register stores data as "resources" in Muck-POC. Each
+resource is a JSON object. The following types of objects are
+supported:
+
+* **subject** represents a person who is allowed to use the register;
+  it it used to identify the user for authentication
+* **password** stores the encrypted password for a subject
+* **memb** represets a subject's membership in Effi
+
+### Subject resource
+
+A subject resource has the following fields:
+
+* `username` — the username of the subject; this can change, the
+  subject is identified by the resource identifier in the register,
+  not by the username
+
+The subject resource does not have any data that isn't needed for
+end-user identification. Effiapi manages and Qvisqve uses the subject
+resource.
+
+### Password resource
+
+A password resource has the following fields:
+
+* `subject_id` — resource id of the subject whose password this
+  is
+* `version` — version of the password resource (identifies
+  algorithm); must be 1
+* `hash` — the password, encrypted with the scrypt algorithm
+* `salt` — a random string to prevent dictionary attacks
+* `key_len` — parameter for scrypt
+* `N` — parameter for scrypt
+* `r` — parameter for scrypt
+* `p` — parameter for scrypt
+
+Effiapi manages and Qvisqve uses the password resource.
+
+### Member resource (memb)
+
+A membership resource has the following fields:
+
+* `subject-id` — the resource id of the subject resource for
+  the member
+* `fullname` — the full name of the member
+* `primary-email` — the primary email address for the member
+  (and currently the only one)
+* `years-paid` — list of integers for the years for which the
+  member has paid their membership
+
+Effiapi manages and uses the memb resource. Effiweb renders it for the
+user.