Skip to content

Commit ed2ca39

Browse files
nikomakelanikomakela
committed
docs: misc updates, mermaid graphs and improved architecture
TH-1422. Converted DITAA formatted ASCII charts to Mermaid charts. Added more information about the service architecture. E.g. external services are now in their own subgraph. Miscallenous fixes and updates to README files: - Fixed some URLs - Added some eslint configurations - Removed some nonsense text - etc.
1 parent 180e755 commit ed2ca39

7 files changed

Lines changed: 266 additions & 146 deletions

File tree

‎README.md‎

Lines changed: 58 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -17,26 +17,70 @@
1717
</a>
1818
</p>
1919

20+
## About Helsinki Events Monorepo
21+
2022
> Howtos for monorepo. New to monorepos ? [check this FAQ](./docs/howto/how-to.md).
2123
24+
The Helsinki Events Monorepo is a version control system for three related applications: Events-Helsinki, Hobbies-Helsinki, and Sports-Helsinki. These are React/Next.js-based applications that allow citizens to discover events, courses, hobbies, and activities in Helsinki. The monorepo also contains the shared services, libraries, and components used across these applications.
25+
26+
### Why a Monorepo?
27+
28+
The primary reason for using a monorepo is to streamline the development and deployment process for our applications. It offers several key advantages:
29+
30+
- **Shared Code and Resources**: Instead of maintaining separate repositories for each app, a monorepo allows us to centralize and easily share common code, components, and services. This reduces duplication and ensures consistency across all three applications.
31+
32+
- **Simplified Dependencies**: With a single repository, managing dependencies between the applications and shared libraries becomes much simpler. Developers can make changes to a shared library and see the effects on all dependent applications in one place.
33+
34+
- **Atomic Commits**: This allows for a single commit that spans multiple projects. For example, a single pull request can include a new feature in a shared library and the corresponding updates in all three applications that use it. This prevents versioning issues and ensures everything works together.
35+
2236
## Architecture
2337

2438
The subgraphs of multiple datasources are combined to a one supergraph with an app specific Apollo-Router instance.
2539
An application (Events, Hobbies, Sports) uses the app specific Apollo-Router so the app gets all the datasources in use with a single Apollo-Client.
2640
All the applications inside the monorepo are sharing the similar Apollo-Router in means of structure, but since there are app specific Headless CMS instances to share app specific data, each of the applications are connected to a unique environment-app-specific router instances.
2741

28-
```
29-
┌─────────────┐ ┌───────────────┐ ┌── Headless CMS (app specific datasource for the dynamic page and articles content)
30-
│ │ │ │ ├── Unified-Search (Elasticsearch-service for search results scoring)
31-
│ Application ├───────┤ Apollo Router ├───────├── Events GraphQL Proxy (A GraphQL-proxy for the LinkedEvents)
32-
│ │ │ │ └── Venues GraphQL Proxy (A GraphQL-proxy for the Palvelukartta/Servicemap / "TPREK" Toimipaikkarekisteri)
33-
└─────────────┘ └───────────────┘
42+
```mermaid
43+
---
44+
title: Graph Service Diagram
45+
---
46+
flowchart LR
47+
subgraph Supergraph
48+
ROUTER[**Events Graphql Federation**: *Apollo Router service to provide a supergraph*]
49+
subgraph Subgraphs
50+
EventsProxy["**Events GraphQL Proxy**: *A GraphQL-proxy for the LinkedEvents*"]
51+
VenuesProxy["**Venues GraphQL Proxy**: *A GraphQL-proxy for the Palvelukartta/Servicemap / 'TPREK' Toimipaikkarekisteri*"]
52+
CMS["**Headless CMS**: *App specific datasource for the dynamic page and articles content*"]
53+
US["**Unified-Search**: *Elasticsearch-service for search results scoring*"]
54+
end
55+
end
56+
57+
subgraph ExternalGraph["External services"]
58+
LinkedEvents
59+
Wordpress["Wordpress (Headless CMS)"]
60+
Servicemap["Palvelukartta / Servicemap"]
61+
Sentry
62+
DigiaIiris
63+
Askem
64+
end
65+
66+
Application --> ROUTER
67+
Application --> Sentry
68+
Application --> DigiaIiris
69+
Application --> Askem
70+
71+
ROUTER --> EventsProxy
72+
ROUTER --> VenuesProxy
73+
ROUTER --> CMS
74+
ROUTER --> US
75+
76+
EventsProxy --> LinkedEvents
77+
VenuesProxy --> Servicemap
78+
CMS --> Wordpress
79+
US --> Servicemap
3480
```
3581

3682
## Structure
3783

38-
[![Open in Gitpod](https://img.shields.io/badge/Open%20In-Gitpod.io-%231966D2?style=for-the-badge&logo=gitpod)](https://gitpod.io/#https://github.com/City-of-Helsinki/events-helsinki-monorepo)
39-
4084
```
4185
.
4286
├── proxies
@@ -48,6 +92,7 @@ All the applications inside the monorepo are sharing the similar Apollo-Router i
4892
│ ├── hobbies-helsinki (i18n, ssr, api, vitest)
4993
│ ├── events-helsinki ("clone of hobbies-helsinki")
5094
│ └── sports-helsinki ("clone of hobbies-helsinki")
95+
│
5196
└── packages
5297
├── common-i18n (locales...)
5398
├── components (common event components, utils and hooks, storybook, vitest)
@@ -167,13 +212,12 @@ Some convenience scripts can be run in any folder of this repo and will call the
167212
| `yarn g:clean` | Clean builds in all workspaces |
168213
| `yarn g:check-dist` | Ensure build dist files passes es2017 (run `g:build` first). |
169214
| `yarn g:check-size` | Ensure browser dist files are within size limit (run `g:build` first). |
170-
| `yarn clean:global-cache` | Clean tooling caches (eslint, vitest...) |
215+
| `yarn clean:global-cache` | Clean tooling caches (eslint, vitest...) |
171216
| `yarn deps:check --dep dev` | Will print what packages can be upgraded globally (see also [.ncurc.yml](https://github.com/sortlist/packages/blob/main/.ncurc.yml)) |
172217
| `yarn deps:update --dep dev` | Apply possible updates (run `yarn install && yarn dedupe` after) |
173218
| `yarn check:install` | Verify if there's no peer-deps missing in packages |
174219
| `yarn dedupe` | Built-in yarn deduplication of the lock file |
175220
| `yarn build` | Builds application with rollup. |
176-
| `yarn publish-canary` | Publishes a canary tagged version of the application. CD is configured to run this script on additions to the main branch. |
177221

178222
> Why using `:` to prefix scripts names ? It's convenient in yarn 3+, we can call those scripts from any folder in the monorepo.
179223
> `g:` is a shortcut for `global:`. See the complete list in [root package.json](./package.json).
@@ -284,6 +328,10 @@ Optinally it is possible revalidate one selected uri. Uri have to be exactly cor
284328
curl -X POST https://tapahtumat.test.hel.ninja/api/revalidate -H "Content-Type: application/json" -d '{"secret": "secretrevalidationtoken", "uri": "/fi"}'
285329
```
286330
331+
### 4.3 Updating pages and articles in CMS
332+
333+
INFO: The headless CMS that the apps are using (Wordpress), should trigger the revalidation process automatically, by sending a request when a save button is clicked!
334+
287335
## 5. Quality
288336
289337
### 5.1 Linters

‎apps/events-helsinki/README.md‎

Lines changed: 52 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,58 @@ Production server: https://tapahtumat.hel.fi (NOTE: this production server might
88

99
This is a [Next.js](https://nextjs.org/) project originally bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app), but cloned from the Hobbies-Helsinki.
1010

11-
## Architecture
12-
13-
```
14-
┌─────────────┐ ┌───────────────┐ ┌── Headless CMS (app specific datasource for the dynamic page and articles content)
15-
│ │ supergraph > │ │ subgraphs > ├── Unified-Search (Elasticsearch-service for search results scoring)
16-
│ Application ├───────────────┤ Apollo Router ├─────────────├── Events GraphQL Proxy (A GraphQL-proxy for the LinkedEvents)
17-
│ │ │ │ └── Venues GraphQL Proxy (A GraphQL-proxy for the Palvelukartta/Servicemap / "TPREK" Toimipaikkarekisteri)
18-
└─────────────┘ └───────────────┘
11+
## Service architecture
12+
13+
The service consists of:
14+
15+
- **[Events-Helsinki](https://github.com/City-of-Helsinki/events-helsinki-monorepo/apps/events-helsinki):** The NextJS / React application. Integrates to a supergraph of Events Feration Router that provides subgraphs to get dynamic CMS content and events.
16+
- **[Events Graphql Federation](https://github.com/City-of-Helsinki/events-helsinki-monorepo/proxies/events-graphql-federation):** [Apollo Router](https://www.apollographql.com/docs/graphos/routing) to provide a supergraph.
17+
- **[Headless CMS](https://github.com/City-of-Helsinki/headless-cms):** Content Management Service that provides dynamic pages and dynamic content for the teachers' UI. It also provides content for the header and the footer. A React component library can be found from https://github.com/City-of-Helsinki/react-helsinki-headless-cms.
18+
- **[LinkedEvents API](https://github.com/City-of-Helsinki/linkedevents):** A city of Helsinki centralized API for events.
19+
- **[Unified Search](https://github.com/City-of-Helsinki/unified-search):** Provide search service for venues.
20+
- **[Palvelukartta / Servicemap](https://servicemap.hel.fi):** Provides details for venues.
21+
- **[Digia Iiris](https://iirishelp.digia.com/):** Web analytics (a [Matomo](https://matomo.org/) service).
22+
- **[Sentry](https://sentry.io/):** A monitoring service.
23+
- **[Askem](https://www.askem.com/):** A website feedback collection and analysis tool.
24+
25+
```mermaid
26+
---
27+
title: Graph Service Diagram
28+
---
29+
flowchart LR
30+
subgraph Supergraph
31+
ROUTER[**Events Graphql Federation**: *Apollo Router service to provide a supergraph*]
32+
subgraph Subgraphs
33+
EventsProxy["**Events GraphQL Proxy**: *A GraphQL-proxy for the LinkedEvents*"]
34+
VenuesProxy["**Venues GraphQL Proxy**: *A GraphQL-proxy for the Palvelukartta/Servicemap / 'TPREK' Toimipaikkarekisteri*"]
35+
CMS["**Headless CMS**: *App specific datasource for the dynamic page and articles content*"]
36+
US["**Unified-Search**: *Elasticsearch-service for search results scoring*"]
37+
end
38+
end
39+
40+
subgraph ExternalGraph["External services"]
41+
LinkedEvents
42+
Wordpress["Wordpress (Headless CMS)"]
43+
Servicemap["Palvelukartta / Servicemap"]
44+
Sentry
45+
DigiaIiris
46+
Askem
47+
end
48+
49+
Application --> ROUTER
50+
Application --> Sentry
51+
Application --> DigiaIiris
52+
Application --> Askem
53+
54+
ROUTER --> EventsProxy
55+
ROUTER --> VenuesProxy
56+
ROUTER --> CMS
57+
ROUTER --> US
58+
59+
EventsProxy --> LinkedEvents
60+
VenuesProxy --> Servicemap
61+
CMS --> Wordpress
62+
US --> Servicemap
1963
```
2064

2165
### Headless CMS datasources
@@ -135,10 +179,6 @@ class AppConfig {
135179

136180
The application configuration is done via the [AppConfig.ts](./src/domain/app/AppConfig.ts) as much as possible, so there would be a single point to configure it.
137181

138-
## Contact
139-
140-
City of Helsinki Slack channel _NO CHANNEL YET?_ (use #hobbieshelsinki)
141-
142182
## Learn more
143183

144184
You can learn more in the [NextJs documentation](https://nextjs.org/docs/getting-started).

‎apps/hobbies-helsinki/README.md‎

Lines changed: 52 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,58 @@ Production server: https://harrastukset.hel.fi
88

99
This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
1010

11-
## Architecture
12-
13-
```
14-
┌─────────────┐ ┌───────────────┐ ┌── Headless CMS (app specific datasource for the dynamic page and articles content)
15-
│ │ supergraph > │ │ subgraphs > ├── Unified-Search (Elasticsearch-service for search results scoring)
16-
│ Application ├───────────────┤ Apollo Router ├─────────────├── Events GraphQL Proxy (A GraphQL-proxy for the LinkedEvents)
17-
│ │ │ │ └── Venues GraphQL Proxy (A GraphQL-proxy for the Palvelukartta/Servicemap / "TPREK" Toimipaikkarekisteri)
18-
└─────────────┘ └───────────────┘
11+
## Service architecture
12+
13+
The service consists of:
14+
15+
- **[Hobbies-Helsinki](https://github.com/City-of-Helsinki/events-helsinki-monorepo/apps/hobbies-helsinki):** The NextJS / React application. Integrates to a supergraph of Events Feration Router that provides subgraphs to get dynamic CMS content and courses.
16+
- **[Events Graphql Federation](https://github.com/City-of-Helsinki/events-helsinki-monorepo/proxies/events-graphql-federation):** [Apollo Router](https://www.apollographql.com/docs/graphos/routing) to provide a supergraph.
17+
- **[Headless CMS](https://github.com/City-of-Helsinki/headless-cms):** Content Management Service that provides dynamic pages and dynamic content for the teachers' UI. It also provides content for the header and the footer. A React component library can be found from https://github.com/City-of-Helsinki/react-helsinki-headless-cms.
18+
- **[LinkedEvents API](https://github.com/City-of-Helsinki/linkedevents):** A city of Helsinki centralized API for events.
19+
- **[Unified Search](https://github.com/City-of-Helsinki/unified-search):** Provide search service for venues.
20+
- **[Palvelukartta / Servicemap](https://servicemap.hel.fi):** Provides details for venues.
21+
- **[Digia Iiris](https://iirishelp.digia.com/):** Web analytics (a [Matomo](https://matomo.org/) service).
22+
- **[Sentry](https://sentry.io/):** A monitoring service.
23+
- **[Askem](https://www.askem.com/):** A website feedback collection and analysis tool.
24+
25+
```mermaid
26+
---
27+
title: Graph Service Diagram
28+
---
29+
flowchart LR
30+
subgraph Supergraph
31+
ROUTER[**Events Graphql Federation**: *Apollo Router service to provide a supergraph*]
32+
subgraph Subgraphs
33+
EventsProxy["**Events GraphQL Proxy**: *A GraphQL-proxy for the LinkedEvents*"]
34+
VenuesProxy["**Venues GraphQL Proxy**: *A GraphQL-proxy for the Palvelukartta/Servicemap / 'TPREK' Toimipaikkarekisteri*"]
35+
CMS["**Headless CMS**: *App specific datasource for the dynamic page and articles content*"]
36+
US["**Unified-Search**: *Elasticsearch-service for search results scoring*"]
37+
end
38+
end
39+
40+
subgraph ExternalGraph["External services"]
41+
LinkedEvents
42+
Wordpress["Wordpress (Headless CMS)"]
43+
Servicemap["Palvelukartta / Servicemap"]
44+
Sentry
45+
DigiaIiris
46+
Askem
47+
end
48+
49+
Application --> ROUTER
50+
Application --> Sentry
51+
Application --> DigiaIiris
52+
Application --> Askem
53+
54+
ROUTER --> EventsProxy
55+
ROUTER --> VenuesProxy
56+
ROUTER --> CMS
57+
ROUTER --> US
58+
59+
EventsProxy --> LinkedEvents
60+
VenuesProxy --> Servicemap
61+
CMS --> Wordpress
62+
US --> Servicemap
1963
```
2064

2165
### Headless CMS datasources
@@ -135,10 +179,6 @@ class AppConfig {
135179

136180
The application configuration is done via the [AppConfig.ts](./src/domain/app/AppConfig.ts) as much as possible, so there would be a single point to configure it.
137181

138-
## Contact
139-
140-
City of Helsinki Slack channel #hobbieshelsinki
141-
142182
## Learn more
143183

144184
You can learn more in the [NextJs documentation](https://nextjs.org/docs/getting-started).

0 commit comments

Comments
 (0)