diff --git a/.adr-dir b/.adr-dir new file mode 100644 index 0000000000000000000000000000000000000000..da5cac6b7725d9176c84aa24cc7ca0dee594d645 --- /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 0000000000000000000000000000000000000000..193d3bfd32e4592de7467cfbf4780066a006aa59 --- /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 0000000000000000000000000000000000000000..220b7a9ffe85458d35f7e75984c5aaa9e8e154e2 --- /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 0000000000000000000000000000000000000000..e25568731dc030475478291eae97c37545acbecb --- /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 0000000000000000000000000000000000000000..1a35387ed9871d1b43dcdd0fa37bd3313db6fb33 --- /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 0000000000000000000000000000000000000000..ef2e02c90ab8f6035ba1f47a14cfee9a55c28365 --- /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 0000000000000000000000000000000000000000..64413d8a4ef10c61770e931d4112ac83e3bad217 --- /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 0000000000000000000000000000000000000000..168e13f97f0118a352515da99c6bf1e7d924b3f5 --- /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 0000000000000000000000000000000000000000..830ad0be74da73c5e92cfdf570c4bba4a81b60d0 --- /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 0000000000000000000000000000000000000000..a8943d30031d8d4d5d8e26150cb028976e863625 --- /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.