diff --git a/.gitbook/assets/grafik.png b/.gitbook/assets/grafik.png new file mode 100644 index 000000000..dab3eef27 Binary files /dev/null and b/.gitbook/assets/grafik.png differ diff --git a/.gitbook/assets/graphql-playground.png b/.gitbook/assets/graphql-playground.png new file mode 100644 index 000000000..32396a577 Binary files /dev/null and b/.gitbook/assets/graphql-playground.png differ diff --git a/.gitbook/assets/screenshot-styleguide.png b/.gitbook/assets/screenshot-styleguide.png new file mode 100644 index 000000000..d8e009394 Binary files /dev/null and b/.gitbook/assets/screenshot-styleguide.png differ diff --git a/.gitbook/assets/screenshot.png b/.gitbook/assets/screenshot.png new file mode 100644 index 000000000..b4ff4b2f9 Binary files /dev/null and b/.gitbook/assets/screenshot.png differ diff --git a/README.md b/README.md index e69de29bb..34f12aacf 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,22 @@ +--- +description: Welcome to the Human-Connection Nitro Documentation. +--- + +# Let's change the World + +## Why do we need HC Nitro? + +> This Prototype tries to resolve the biggest hurdle of connecting our services together. This is not possible in a sane way using our current approach. +> +> With this Prototype we can explore using the combination of GraphQL and the Neo4j Graph Database for achieving the connected nature of a social graph with better development experience as we do not need to connect data by our own any more through weird table structures etc. +> +> **Advantages:** + +> * easer data structure +> * better connected data +> * easy to achieve "recommendations" based on actions \(relations\) +> * more performant and better to understand API +> * better API client that uses caching +> +> We still need to evaluate the drawbacks and estimate the development cost of such an approach + diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 000000000..6684ecf50 --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,37 @@ +# Table of contents + +* [Let's change the World](README.md) + +## API + +* [Backend Installation](api/installation/README.md) + * [Configuration](api/installation/configuration.md) + * [Docker](api/installation/docker.md) +* [GraphQL with Apollo](api/graphql-with-apollo/README.md) + * [Mocking](api/graphql-with-apollo/mocking.md) + * [Seeding](api/graphql-with-apollo/seeding.md) +* [Middleware](api/middleware.md) +* [Import](api/data-import.md) +* [Todo's](api/todos.md) + +## Web UI + +* [Web Installation](ui/installation.md) +* [Styleguide](ui/styleguide.md) +* [Todo's](ui/todos.md) + +## Workflow + +* [Testing](integration-tests/testing.md) +* [Pull-Requests](integration-tests/pull-requests.md) +* [Deployment](integration-tests/deployment.md) + +## Recources + +* [Human-Connection.org](https://human-connection.org) +* [Staging \(comming soon\)](https://staging.nitro.human-connection.org/) + +## Translations + +* [Lokalise.co](https://lokalise.co/public/202462935bc64b38d64bb9.16240920/) + diff --git a/api/data-import.md b/api/data-import.md new file mode 100644 index 000000000..7923740eb --- /dev/null +++ b/api/data-import.md @@ -0,0 +1,139 @@ +# Import + +For importing Data we need to set some values in the Neo4J config. + +### Neo4J Config + +{% hint style="danger" %} +Do not leave this settings on the production environment +{% endhint %} + +```yaml +dbms.security.procedures.unrestricted=apoc.* +apoc.import.file.enabled=true +``` + +### Data import from Mongodumbs + +```bash +EXPORT MONGO COLLECTIONS AS mongodump + +### Categories + +CALL apoc.load.json('file:/Users/Greg/Projekte/HumanConnection/_notes/NEO4J-Import/hc_api.categories.json') YIELD value as category +MERGE(c:Category {id: category._id["$oid"]}) +ON CREATE SET c.name = category.title, + c.slug = category.slug, + c.icon = category.icon + +-- +CREATE CONSTRAINT ON (c:Category) ASSERT c.id IS UNIQUE +CREATE CONSTRAINT ON (c:Category) ASSERT c.name IS UNIQUE +CREATE CONSTRAINT ON (c:Category) ASSERT c.slug IS UNIQUE + + +### Badges + +CALL apoc.load.json('file:/Users/Greg/Projekte/HumanConnection/_notes/NEO4J-Import/hc_api.badges.json') YIELD value as badge +MERGE(b:Badge {id: badge._id["$oid"]}) +ON CREATE SET b.key = badge.key, + b.type = badge.type, + b.icon = badge.image.path, + b.status = badge.status + +-- +CREATE CONSTRAINT ON (b:Badge) ASSERT b.id IS UNIQUE +CREATE CONSTRAINT ON (b:Badge) ASSERT b.key IS UNIQUE + + +### Users + +CALL apoc.load.json('file:/Users/Greg/Projekte/HumanConnection/_notes/NEO4J-Import/hc_api.users.json') YIELD value as user +MERGE(u:User {id: user._id["$oid"]}) +ON CREATE SET u.name = user.name, + u.slug = user.slug, + u.email = user.email, + u.password = user.password, + u.avatar = user.avatar, + u.coverImg = user.coverImg, + u.wasInvited = user.wasInvited, + u.role = apoc.text.toUpperCase(user.role) +WITH u, user, user.badgeIds AS badgeIds +UNWIND badgeIds AS badgeId +MATCH (b:Badge {id: badgeId}) +MERGE (b)-[:REWARDED]->(u) + +-- +CREATE INDEX ON :User(name) +CREATE INDEX ON :User(deleted) +CREATE INDEX ON :User(disabled) +CREATE CONSTRAINT ON (u:User) ASSERT u.id IS UNIQUE +CREATE CONSTRAINT ON (u:User) ASSERT u.slug IS UNIQUE + + +### Contributions + +CALL apoc.load.json('file:/Users/Greg/Projekte/HumanConnection/_notes/NEO4J-Import/hc_api.contributions.json') YIELD value as post +MERGE (p:Post {id: post._id["$oid"]}) +ON CREATE SET p.title = post.title, + p.slug = post.slug, + p.image = post.teaserImg, + p.content = post.content, + p.contentExcerpt = post.contentExcerpt, + p.visibility = apoc.text.toUpperCase(post.visibility), + p.createdAt = datetime(post.createdAt["$date"]), + p.updatedAt = datetime(post.updatedAt["$date"]) +WITH p, post, post.tags AS tags, post.categoryIds as categoryIds +UNWIND tags AS tag +UNWIND categoryIds AS categoryId +MATCH (c:Category {id: categoryId}), + (u:User {id: post.userId}) +MERGE (t:Tag {id: apoc.create.uuid(), name: tag}) +MERGE (p)-[:TAGGED]->(t) +MERGE (u)-[:WROTE]->(p) +MERGE (p)-[:CATEGORIZED]->(c) + +-- +CREATE INDEX ON :Post(title) +CREATE INDEX ON :Post(content) +CREATE INDEX ON :Post(deleted) +CREATE INDEX ON :Post(disabled) +CREATE CONSTRAINT ON (p:Post) ASSERT p.id IS UNIQUE +CREATE CONSTRAINT ON (p:Post) ASSERT p.slug IS UNIQUE + + +### Coments + +CALL apoc.load.json('file:/Users/Greg/Projekte/HumanConnection/_notes/NEO4J-Import/hc_api.comments.json') YIELD value as comment +MERGE (c:Comment {id: comment._id["$oid"]}) +ON CREATE SET c.content = comment.content, + c.contentExcerpt = comment.contentExcerpt, + c.deleted = comment.deleted +MATCH (p:Post {id: comment.contributionId}), + (u:User {id: comment.userId}) +MERGE (c)-[:COMMENTS]->(p) +MERGE (u)-[:WROTE]->(c) + +-- +CREATE INDEX ON :Comment(deleted) +CREATE INDEX ON :Comment(disabled) +CREATE CONSTRAINT ON (c:Comment) ASSERT c.id IS UNIQUE + + +### Follolws + +CALL apoc.load.json('file:/Users/Greg/Projekte/HumanConnection/_notes/NEO4J-Import/hc_api.follows.json') YIELD value as follow +MATCH (u1:User {id: follow.userId}), + (u2:User {id: follow.foreignId}) +MERGE (u1)-[:FOLLOWS]->(u2) + + +### Shouts + +CALL apoc.load.json('file:/Users/Greg/Projekte/HumanConnection/_notes/NEO4J-Import/hc_api.shouts.json') YIELD value as shout +MATCH (u:User {id: shout.userId}), + (p:Post {id: shout.foreignId}) +MERGE (u)-[:SHOUTED]->(p) + +``` + diff --git a/api/graphql-with-apollo/README.md b/api/graphql-with-apollo/README.md new file mode 100644 index 000000000..018330259 --- /dev/null +++ b/api/graphql-with-apollo/README.md @@ -0,0 +1,12 @@ +--- +description: Our API Layer +--- + +# GraphQL with Apollo + +GraphQL is a data query language which provides an alternative to REST and ad-hoc web service architectures. It allows clients to define the structure of the data required, and exactly the same structure of the data is returned from the server. + +![GraphQL Playground](../../.gitbook/assets/graphql-playground.png) + + + diff --git a/api/graphql-with-apollo/mocking.md b/api/graphql-with-apollo/mocking.md new file mode 100644 index 000000000..8b99ea6bf --- /dev/null +++ b/api/graphql-with-apollo/mocking.md @@ -0,0 +1,12 @@ +--- +description: No Database? No problem! +--- + +# Mocking + +### Mocking API Results + +Alternatively you can just mock all responses from the api which let you build a frontend application without running a neo4j instance. + +Just set `MOCK=true` inside `.env` or pass it on application start. + diff --git a/api/graphql-with-apollo/seeding.md b/api/graphql-with-apollo/seeding.md new file mode 100644 index 000000000..205931683 --- /dev/null +++ b/api/graphql-with-apollo/seeding.md @@ -0,0 +1,20 @@ +# Seeding + +### Seeding The Database + +Optionally you can seed the GraphQL service by executing mutations that will write sample data to the database: + +{% tabs %} +{% tab title="Yarn" %} +```bash +yarn seedDb +``` +{% endtab %} + +{% tab title="NPM" %} +```bash +npm run seedDb +``` +{% endtab %} +{% endtabs %} + diff --git a/api/installation/README.md b/api/installation/README.md new file mode 100644 index 000000000..e0cba686c --- /dev/null +++ b/api/installation/README.md @@ -0,0 +1,48 @@ +--- +description: Lets try to install the Human Connection - Nitro Backend +--- + +# Backend Installation + +### Copy Environment Variables + +```bash +cp .env.template .env +``` + +Configure the file `.env` according to your needs and your local setup. + +### Install Dependencies + +{% tabs %} +{% tab title="Yarn" %} +```bash +yarn install +``` +{% endtab %} + +{% tab title="NPM" %} +```bash +npm install +``` +{% endtab %} +{% endtabs %} + +### Start the Server + +{% tabs %} +{% tab title="Yarn" %} +```bash +yarn start +``` +{% endtab %} + +{% tab title="NPM" %} +```bash +npm start +``` +{% endtab %} +{% endtabs %} + +This will start the GraphQL service \(by default on [http://localhost:4000](http://localhost:4000)\) where you can issue GraphQL requests or access GraphQL Playground in the browser + diff --git a/api/installation/configuration.md b/api/installation/configuration.md new file mode 100644 index 000000000..54bab4747 --- /dev/null +++ b/api/installation/configuration.md @@ -0,0 +1,30 @@ +# Configuration + +### Configure + +Set your Neo4j connection string and credentials in `.env`. For example: + +{% code-tabs %} +{% code-tabs-item title=".env" %} +```yaml +NEO4J_URI=bolt://localhost:7687 +NEO4J_USER=neo4j +NEO4J_PASSWORD=letmein +``` +{% endcode-tabs-item %} +{% endcode-tabs %} + +{% hint style="warning" %} +You **need to install APOC** as a plugin for the graph you create in the neo4j desktop app! +{% endhint %} + +Note that grand-stack-starter does not currently bundle a distribution of Neo4j. You can download [Neo4j Desktop](https://neo4j.com/download/) and run locally for development, spin up a [hosted Neo4j Sandbox instance](https://neo4j.com/download/), run Neo4j in one of the [many cloud options](https://neo4j.com/developer/guide-cloud-deployment/), [spin up Neo4j in a Docker container](https://neo4j.com/developer/docker/) or on Debian-based systems install [Neo4j from the Debian Repository ](http://debian.neo4j.org/). Just be sure to update the Neo4j connection string and credentials accordingly in `.env`. + +**Install APOC plugin on Debian-based systems** + +When you have install Neo4j from the Debian Repository, then download the [APOC plugin](https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/3.4.0.3/apoc-3.4.0.3-all.jar) to the `/var/lib/neo4j/plugins` directory manually or with: + +```text +wget https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/3.4.0.3/apoc-3.4.0.3-all.jar -P /var/lib/neo4j/plugins +``` + diff --git a/api/installation/docker.md b/api/installation/docker.md new file mode 100644 index 000000000..6aa5744a1 --- /dev/null +++ b/api/installation/docker.md @@ -0,0 +1,2 @@ +# Docker + diff --git a/api/middleware.md b/api/middleware.md new file mode 100644 index 000000000..f581097c7 --- /dev/null +++ b/api/middleware.md @@ -0,0 +1,21 @@ +--- +description: >- + GraphQL Middleware lets you run arbitrary code before or after a resolver is + invoked. It improves your code structure by enabling code reuse and a clear + separation of concerns. +--- + +# Middleware + + + +![](../.gitbook/assets/grafik.png) + +### Middleware keeps resolvers clean + +A well-organized codebase is key for the ability to maintain and easily introduce changes into an app. Figuring out the right structure for your code remains a continuous challenge - especially as an application grows and more developers are joining a project. + +A common problem in GraphQL servers is that resolvers often get cluttered with business logic, making the entire resolver system harder to understand and maintain. + +GraphQL Middleware uses the [_middleware pattern_](https://dzone.com/articles/understanding-middleware-pattern-in-expressjs) \(well-known from Express.js\) to pull out repetitive code from resolvers and execute it before or after one your resolvers is invoked. This improves code modularity and keeps your resolvers clean and simple. + diff --git a/api/todos.md b/api/todos.md new file mode 100644 index 000000000..14a3f7414 --- /dev/null +++ b/api/todos.md @@ -0,0 +1,11 @@ +# Todo's + +* [x] add jwt authentication \(in progress\) +* [ ] get directives working correctly \(@toLower, @auth, @role, etc.\) +* [ ] check if search is working +* [ ] check if sorting is working +* [x] check if pagination is working +* [ ] check if upload is working \(using graphql-yoga?\) +* [x] evaluate middleware +* [ ] ignore Posts and Comments by blacklisted Users \(in progress\) + diff --git a/integration-tests/deployment.md b/integration-tests/deployment.md new file mode 100644 index 000000000..ed3c9a4c8 --- /dev/null +++ b/integration-tests/deployment.md @@ -0,0 +1,2 @@ +# Deployment + diff --git a/integration-tests/pull-requests.md b/integration-tests/pull-requests.md new file mode 100644 index 000000000..2a6eae745 --- /dev/null +++ b/integration-tests/pull-requests.md @@ -0,0 +1,2 @@ +# Pull-Requests + diff --git a/integration-tests/testing.md b/integration-tests/testing.md new file mode 100644 index 000000000..fd198fa05 --- /dev/null +++ b/integration-tests/testing.md @@ -0,0 +1,2 @@ +# Testing + diff --git a/ui/installation.md b/ui/installation.md new file mode 100644 index 000000000..be87b4446 --- /dev/null +++ b/ui/installation.md @@ -0,0 +1,48 @@ +# Web Installation + +### Install Dependencies + +{% hint style="danger" %} +Current you have to use the `--ignore-engines` parameter on install as the izitoast wrapper package claims to not work on node >= 9 which is not true. If the Author does not responde we might fork the package or make our own component out of it. So its an temporary issue. +{% endhint %} + +{% tabs %} +{% tab title="Yarn" %} +```bash +cd styleguide && yarn install --ignore-engines && cd .. +yarn install --ignore-engines +``` +{% endtab %} + +{% tab title="NPM" %} +```bash +cd styleguide && npm install --ignore-engines && cd .. +npm install --ignore-engines +``` +{% endtab %} +{% endtabs %} + +### Development + +To start developing you need to start the server with the dev command. This will give you "hot reload" which updates the browser content \(mostly\) without reloading the whole page. + +{% tabs %} +{% tab title="Yarn" %} +```bash +yarn dev +``` +{% endtab %} + +{% tab title="NPM" %} +```bash +npm run dev +``` +{% endtab %} +{% endtabs %} + +This will start the UI under [http://localhost:3000](http://localhost:3000) + +![You should see this under http://localhost:3000](../.gitbook/assets/screenshot.png) + + + diff --git a/ui/styleguide.md b/ui/styleguide.md new file mode 100644 index 000000000..5c0983dae --- /dev/null +++ b/ui/styleguide.md @@ -0,0 +1,50 @@ +--- +description: 'The styleguide is not just a guide, its also our Design System.' +--- + +# Styleguide + +For this Projoject we decided to use [Jörg Bayreuther's](https://github.com/visualjerk) _\(visualjerk\)_ fantastic Design System called [CION](https://cion.visualjerk.de/). _\(see a_ [_demo_](https://styleguide.cion.visualjerk.de/)_\)_ + +![Styleguide in action under https://localhost:8080](../.gitbook/assets/screenshot-styleguide.png) + +### Developing with the Styleguide + +{% tabs %} +{% tab title="Yarn" %} +```bash +yarn styleguide +``` +{% endtab %} + +{% tab title="NPM" %} +```bash +npm run styleguide +``` +{% endtab %} +{% endtabs %} + +### Build + +if you changed design tokens or other styles inside the styleguide, run the refresh command to build the styleguide as a lib. + +{% hint style="info" %} +The Styleguide is build when installing the UI via Yarn or NPM, but when you have changes inside the styleguide, you will need to run following command so they will be repflected in the main UI + +We want to improve this in the future while running `yarn dev`. +{% endhint %} + +{% tabs %} +{% tab title="Yarn" %} +```bash +yarn styleguide:build +``` +{% endtab %} + +{% tab title="NPM" %} +```bash +npm run styleguide:build +``` +{% endtab %} +{% endtabs %} + diff --git a/ui/todos.md b/ui/todos.md new file mode 100644 index 000000000..e503852a5 --- /dev/null +++ b/ui/todos.md @@ -0,0 +1,3 @@ +# Todo's + +* [ ]