From 01876d22b816e69e1a6fdb7bbe1ec1ce0f4a630d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Bedna=C5=99=C3=ADk?= <jan.bednarik@gmail.com> Date: Fri, 15 Dec 2017 22:51:24 +0100 Subject: [PATCH] Document architecture design decisions. --- .adr-dir | 1 + .../0001-record-architecture-decisions.md | 22 ++++++++++++++ ...2-use-elasticsearch-for-fulltext-search.md | 27 +++++++++++++++++ .../0003-just-api-without-frontend.md | 22 ++++++++++++++ .../decisions/0004-graphql-api.md | 30 +++++++++++++++++++ docs/architecture/decisions/0005-python.md | 29 ++++++++++++++++++ docs/architecture/decisions/0006-use-flask.md | 21 +++++++++++++ .../0007-adopt-graphql-relay-specification.md | 24 +++++++++++++++ docs/architecture/decisions/0008-pytest.md | 20 +++++++++++++ docs/architecture/decisions/0009-openid.md | 23 ++++++++++++++ 10 files changed, 219 insertions(+) create mode 100644 .adr-dir create mode 100644 docs/architecture/decisions/0001-record-architecture-decisions.md create mode 100644 docs/architecture/decisions/0002-use-elasticsearch-for-fulltext-search.md create mode 100644 docs/architecture/decisions/0003-just-api-without-frontend.md create mode 100644 docs/architecture/decisions/0004-graphql-api.md create mode 100644 docs/architecture/decisions/0005-python.md create mode 100644 docs/architecture/decisions/0006-use-flask.md create mode 100644 docs/architecture/decisions/0007-adopt-graphql-relay-specification.md create mode 100644 docs/architecture/decisions/0008-pytest.md create mode 100644 docs/architecture/decisions/0009-openid.md diff --git a/.adr-dir b/.adr-dir new file mode 100644 index 0000000..da5cac6 --- /dev/null +++ b/.adr-dir @@ -0,0 +1 @@ +docs/architecture/decisions diff --git a/docs/architecture/decisions/0001-record-architecture-decisions.md b/docs/architecture/decisions/0001-record-architecture-decisions.md new file mode 100644 index 0000000..193d3bf --- /dev/null +++ b/docs/architecture/decisions/0001-record-architecture-decisions.md @@ -0,0 +1,22 @@ +# 1. Record architecture decisions + +Date: 2017-11-11 + +## Status + +Accepted + +## Context + +We need to record the architectural decisions made on this project. + +## Decision + +We will use Architecture Decision Records, as described by Michael Nygard in +this article: +http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions + +## Consequences + +See Michael Nygard's article, linked above. For a lightweight ADR toolset, see +Nat Pryce's _adr-tools_ at https://github.com/npryce/adr-tools. diff --git a/docs/architecture/decisions/0002-use-elasticsearch-for-fulltext-search.md b/docs/architecture/decisions/0002-use-elasticsearch-for-fulltext-search.md new file mode 100644 index 0000000..220b7a9 --- /dev/null +++ b/docs/architecture/decisions/0002-use-elasticsearch-for-fulltext-search.md @@ -0,0 +1,27 @@ +# 2. Use Elasticsearch for fulltext search + +Date: 2017-11-11 + +## Status + +Accepted + +## Context + +We need a database with fulltext search capable of searching in various +languages especially in Czech. + +## Decision + +We will use Elasticsearch. It's well known database with great fulltext search +capabilities based on Apache Lucene. It has also aggregations, highlighting of +results, and many other useful features. + +We will use it as database for all data so we have just one database in the +system. + +## Consequences + +* Great fulltext in any language. +* Some extra work on application level with management of database relations, + because Elasticsearch is not relational database. diff --git a/docs/architecture/decisions/0003-just-api-without-frontend.md b/docs/architecture/decisions/0003-just-api-without-frontend.md new file mode 100644 index 0000000..e255687 --- /dev/null +++ b/docs/architecture/decisions/0003-just-api-without-frontend.md @@ -0,0 +1,22 @@ +# 3. Just API without frontend + +Date: 2017-11-11 + +## Status + +Accepted + +## Context + +Open Lobby must have open stable API. + +## Decision + +Open Lobby will be server just with an API based on API First design. Frontend +will be written as separate application (web based, mobile, ...). This will +ensure that there is a working API for anything that frontend application(s) +will do. + +## Consequences + +Extra work with API layer capable of everything. diff --git a/docs/architecture/decisions/0004-graphql-api.md b/docs/architecture/decisions/0004-graphql-api.md new file mode 100644 index 0000000..1a35387 --- /dev/null +++ b/docs/architecture/decisions/0004-graphql-api.md @@ -0,0 +1,30 @@ +# 4. GraphQL API + +Date: 2017-11-11 + +## Status + +Accepted + +## Context + +Open Lobby Server will be written in API First design. Frontend applications +will be based on it's API. + +## Decision + +We will use GraphQL as API standard. From other options like REST and Graph API +it's the most client friendly approach. GraphQL query language is easy to use, +validated and self documenting. + +GraphQL allows clients to get everything they need in one request without any +overhead of not needed data. That is very important for mobile frontends. + +GraphiQL tool also provides easy way for developers to inspect and try API. So +it's easy to adopt by frontend applications developers or other API users. + +## Consequences + +* Clients can use API effectively. +* GraphiQL tool for free. +* Saves a lot of time of writing API documentation. diff --git a/docs/architecture/decisions/0005-python.md b/docs/architecture/decisions/0005-python.md new file mode 100644 index 0000000..ef2e02c --- /dev/null +++ b/docs/architecture/decisions/0005-python.md @@ -0,0 +1,29 @@ +# 5. Python + +Date: 2017-11-11 + +## Status + +Accepted + +## Context + +We need to choose main programming language for this project. + +## Decision + +I'm now fluent in writing Python and JavaScript. Both languages are widely used +these days and may attract developers to join this project. + +Python is more mature with more stable libs for writing server side code and +testing. JS may have better libraries for writing GraphQL APIs because +GraphQL originated in JS ecosystem. + +I'm doing this in free time and for fun. I want to focus on project's features +and not to waste a time with poorly designed language lacking mature and +stable libraries. So for obvious reasons I'm choosing Python. + +## Consequences + +* Some people will love this decision. +* Some people will hate this decision. diff --git a/docs/architecture/decisions/0006-use-flask.md b/docs/architecture/decisions/0006-use-flask.md new file mode 100644 index 0000000..64413d8 --- /dev/null +++ b/docs/architecture/decisions/0006-use-flask.md @@ -0,0 +1,21 @@ +# 6. Use Flask + +Date: 2017-11-11 + +## Status + +Accepted + +## Context + +We need to choose webserver. + +## Decision + +We will use Flask. Server should be simple - pretty much just with a GraphQL +endpoint and GraphiQL. + +## Consequences + +Flask has "no batteries included" so we will have to rely on third-party libs +if we want to extend server later. diff --git a/docs/architecture/decisions/0007-adopt-graphql-relay-specification.md b/docs/architecture/decisions/0007-adopt-graphql-relay-specification.md new file mode 100644 index 0000000..168e13f --- /dev/null +++ b/docs/architecture/decisions/0007-adopt-graphql-relay-specification.md @@ -0,0 +1,24 @@ +# 7. Adopt GraphQL Relay specification + +Date: 2017-11-11 + +## Status + +Accepted + +## Context + +We need to make API friendly for clients and design pagination. + +## Decision + +We will adopt GraphQL Relay specification. It solves pagination so we don't +have to reinvent a wheel. It has handy Node interface for re-fetching objects. +It has a way to define inputs in mutations. + +Graphene lib has good support for creating API following Relay specifications. + +## Consequences + +* It will be easy to write SPA in JavaScript because it has Relay client lib. +* It may require some extra work to fulfill Relay specification. diff --git a/docs/architecture/decisions/0008-pytest.md b/docs/architecture/decisions/0008-pytest.md new file mode 100644 index 0000000..830ad0b --- /dev/null +++ b/docs/architecture/decisions/0008-pytest.md @@ -0,0 +1,20 @@ +# 8. Pytest + +Date: 2017-11-11 + +## Status + +Accepted + +## Context + +We need to choose framework for tests. + +## Decision + +We will use Pytest. It's much more Pythonic and simplier to use than Unittest +from standrd library. + +## Consequences + +Writing tests will be easy and fun. diff --git a/docs/architecture/decisions/0009-openid.md b/docs/architecture/decisions/0009-openid.md new file mode 100644 index 0000000..a8943d3 --- /dev/null +++ b/docs/architecture/decisions/0009-openid.md @@ -0,0 +1,23 @@ +# 9. OpenID + +Date: 2017-11-11 + +## Status + +Accepted + +## Context + +We need an authentication mechanism for users. It must be secure and +frontend application independent. + +## Decision + +We will use OpenID Connect. Open Lobby Server will provide all the hard stuff +for a frontend applications. Ideally over the GraphQL API. + +## Consequences + +* We can create a user account simply on the first successful login. +* We don't have to verify user's email and to deal with situations like a lost +password. -- GitLab