Merge pull request #575 from ncs-northware/update-docs

Update Docs

Author: onissen

.github/workflows/release.yml .github/workflows/changesets-release.yml.github/workflows/release.yml renamed to .github/workflows/changesets-release.yml

@@ -1,36 +1,3 @@
-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).
+# Northware Cockpit
 
-## Getting Started
-
-First, run the development server:
-
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
-```
-
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
-
-You can start editing the page by modifying `app/page.js`. The page auto-updates as you edit the file.
-
-This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font.
-
-## Learn More
-
-To learn more about Next.js, take a look at the following resources:
-
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
-
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
-
-## Deploy on Vercel
-
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
-
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
+This [Next.js App](https://nextjs.org) is part of the Northware Suite. The App is used to manage the internal bussiness of the fictional NCS Group and administer the Northware Suite itself.

apps/cockpit/README.md

@@ -2,7 +2,6 @@
   "extends": "@northware/tsconfig/nextjs.json",
   "compilerOptions": {
     "baseUrl": ".",
-    "plugins": [{ "name": "next" }],
     "paths": {
       "@/*": ["./src/*"],
       "@northware/ui/*": ["../../packages/ui/*"]

apps/cockpit/tsconfig.json

@@ -7,19 +7,26 @@ description: Wie die Apps und Packages der Northware Suite versioniert werden
 
 Das Tool [Changesets](https://github.com/changesets/changesets) wird verwendet, um die Versionierung und das erstellen von Changelogs zu vereinfachen.
 
-Zu jedem Pull Request, der einen neuen Release (major, minor oder patch) auslösen soll benötigt ein Changeset. Ein Changeset ist eine Markdown-Datei im `.changesets/*` Ordner, der beschreibt welche Art von Release passiert, wenn die beschriebene Code-Änderung in die App übernommen wird (Versionsänderung) und was mit dieser Code-Änderung passiert (Changelog Eintrag zur neuen Version).
+Zu jedem Pull Request, der einen neuen Release (major, minor oder patch) auslösen soll, wird ein Changeset benötigt.
+Ein Changeset ist eine Markdown-Datei im `.changesets/*` Ordner, die beschreibt welche Art von Release passiert, 
+wenn die beschriebene Code-Änderung in die App übernommen wird (Versionsänderung) und was mit dieser Code-Änderung passiert (Changelog Eintrag zur neuen Version).
 
-Der [Changeset Bot](https://github.com/apps/changeset-bot) prüft bei jedem Pull Request, ob ein Changeset existiert und erinnert ggf. mit einem Kommentar im PR daran, ein Changeset hinzuzufügen.
+Der [Changeset Bot](https://github.com/apps/changeset-bot) prüft bei jedem Pull Request, 
+ob ein Changeset existiert und erinnert ggf. mit einem Kommentar im PR daran, ein Changeset hinzuzufügen.
 
-Ein Changeset kann schon vor Eröffnung des Pull Requests oder per Link in dem Kommentar vom Changesets Bot direkt in GitHub oder als nachträglicher Commit hinzugefügt werden. Es bietet sich an, zur Erstellung eines Changesets den CLI Command `pnpm changeset` oder `pnpm changeset add` zu verwenden, Da dieser Command interaktiv durch die Erstellung eines Changesets führt.
+Ein Changeset kann schon vor Eröffnung des Pull Requests oder per Link in dem Kommentar vom Changesets Bot direkt in GitHub
+oder als nachträglicher Commit hinzugefügt werden. 
+Es bietet sich an, zur Erstellung eines Changesets den CLI Command `pnpm changeset` oder `pnpm changeset add` zu verwenden, 
+da dieser Command interaktiv durch die Erstellung eines Changesets führt.
 
-Innerhalb einer Changeset-Datei wird definiert, welche Packages durch den Merge dieses Changesets welche Art von Version Bump erhalten. Außerdem wird im Changeset für das Changelog beschrieben, welche Änderungen vorgenommen wurden.
+Innerhalb einer Changeset-Datei wird definiert, welche Packages durch den Merge dieses Changesets welche Art von Version Bump erhalten. 
+Außerdem wird im Changeset für das Changelog beschrieben, welche Änderungen vorgenommen wurden.
 
 ```mdx
 ---
 <!-- Welche Packages erhalten welche Art von Version Bump -->
 "docs": patch
-"northware-cockpit": patch
+"cockpit": patch
 ---
 
 <!-- Beschreibung für das Changelog -->
@@ -29,7 +36,8 @@ An awesome release
 
 ### Changesets Release Workflow
 
-Der Workflow "Auto Release" (release.yml) erstellt immer automatisch einen Pull Request, der den nächsten Release vorbereitet. Der Pull Request wird immer mit dem `main` Branch abgeglichen. Ein Merge dieses Pull Requests führt zur Veröffentlichung neuer Versionen.
+Der Workflow "Changesets Release" (changesets-release.yml) erstellt immer automatisch einen Pull Request, der den nächsten Release vorbereitet. 
+Der Pull Request wird immer mit dem `main` Branch abgeglichen. Ein Merge dieses Pull Requests führt zur Veröffentlichung neuer Versionen.
 
 ### Mehr über Changesets
 

apps/docs/content/docs/(home)/github/release-strategy.mdx

@@ -86,7 +86,8 @@ Die Workflows sind nicht mit klassischen GitHub Actions sondern über das [integ
 
 ### Turborepo CI
 
-Der Workflow **Turborepo CI** (`.github/workflows/turborepo-ci.yml`) wird immer dann ausgelöst, wenn Code auf den `main` Branch gepusht wird oder ein neuer Pull Request eröffnet oder aktualisiert wird.
+Der Workflow **Turborepo CI** (`.github/workflows/turborepo-ci.yml`) wird immer dann ausgelöst, 
+wenn Code auf den `main` Branch gepusht wird oder ein neuer Pull Request eröffnet oder aktualisiert wird.
 
 - Der Workflow nutzt den vorliegenden Code und installiert das Projekt in einer Node.js Umgebung mit `pnpm`.
 - Mit `pnpm build --affected` werden die von der Änderung betroffenen Code-Teile gebaut.
@@ -96,7 +97,8 @@ Sollte es während dieses Workflows zu Problemen kommen, wird der Workflow abgeb
 
 <Callout type="info">
 Der Turborepo CI-Workflow durchläuft bei jedem Pull Request und bei jedem Merge die Schritte `pnpm turbo build --affected` und `pnpm turbo run lint:ci`. 
-Damit diese Schritte nicht immer erst gemacht werden, wenn alles fertig ist lässt sich dieser Ablauf mit `pnpm localci` auch lokal abbilden, damit Fehler schon vor dem CI-Durchlauf auffallen.
+Damit diese Schritte nicht immer erst gemacht werden, wenn alles fertig ist lässt sich dieser Ablauf mit `pnpm localci` auch lokal abbilden, 
+damit Fehler schon vor dem CI-Durchlauf auffallen.
 </Callout>
 
 ### autofix.ci
@@ -108,6 +110,25 @@ Wenn durch den Durchlauf des Workflows Änderungen am Code vorgenommen wurden, w
 
 **Dieser Commit unterbricht nun alle laufenden Workflows.** Diese Workflows scheitern. Anschließend starten alle vorgesehenen Workflows wieder von neuem.
 
+### Changesets Auto Release
+
+Der Workflow **Changesets Auto Release** (.github/workflows/changesets-release.yml) wird ausgeführt, wenn Code auf den `main` Branch gepusht wird.
+
+Der Workflow nutzt [changesets/action](https://github.com/changesets/action), um einen Pull Request mit dem Titel `chore(release): New Package Versions` zu erstellen. Wird dieser Pull Request in `main` gemerged,
+werden alle Packages und Apps entsprechend der im Repository enthaltenen Changesets versioniert und die `CHANGELOG.md` wird entsprechend der Changesets aktualisiert.
+Alle vorhandenen Changesets werden gelöscht. [Weitere Infos zur Release Strategie](./release-strategy.mdx)
+
+Exisitiert bereits ein durch Changesets erstellter Pull Request, wird dieser bei jedem push auf den `main` Branch aktualisiert.
+Enthält der gepushte Code ein neues oder geändertes Changeset, wird dieses in das `CHANGELOG` aufgenommen.
+Enthält der gepushte Code keine Veränderungen an Changesets, wird der Branch lediglich auf den Stand des `main` Branch gebracht.
+
+### Typescript Syntax Checks
+
+Der Workflow **Typescript Syntax Checks** (.github/workflows/tsc-check) wird bei jedem neu eröffneten oder aktualisierten Pull Request und bei Pushes auf den `main` Branch ausgeführt. 
+Das Projekt wird mit den Commands `pnpm tsc-check:root` (für Dateien im Root-Verzeichnis) und `pnpm turbo tsc-check` (für die einzelnen Apps und Packages) auf Typescript-Fehler untersucht.
+Die beschriebenen Commands führen dazu den Command `tsc --noEmit` aus. Werden Fehler im Typescript-Code festgestellt, scheitert der Durchlauf des Workflows. Die Fehler sollten behoben werden, 
+bevor der Pull Request gemerged wird.
+
 ## Renovate Bot
 
 Mit dem [Renovate Bot](https://www.mend.io/renovate/) werden die Dependencies im GitHub Repository aktuell gehalten.

apps/docs/content/docs/(home)/github/workflows.mdx

@@ -0,0 +1,38 @@
+---
+title: Admin Panel
+description: Funktionen, mit der die Northware Suite technisch administriert werden
+---
+
+Über das Admin Panel wird die Northware Suite technisch administriert.
+
+## Benutzerverwaltung
+
+Über die Benutzerverwaltung können die Benutzerkonten der Endnutzer der Northware Suite verwaltet werden. Es können Benutzer und ihre Berechtigungen verwaltet werden.
+
+Ein Benutzer besteht aus einem User-Account und den Relationen des Butzers zu Rollen und Berechtigungen in der Northware Suite.
+Die Benutzerverwaltung ist die Oberfläche, mit der Adminstratoren diese Benutzer, Rollen und Berechtigungen aus `@northware/auth` und der Northware Datenbank verwalten können.
+
+Jeder User-Account enthält E-Mail-Adresse, Benutzernamen und Passwort sowie optional Vorname und Nachname des Benutzers. 
+Dieser Benutzer wird bei [Clerk](https://clerk.com/) gespeichert.
+
+Darüber hinaus erhält jeder Benutzer Rollen und Berechtigungen zur Nutzung der Northware Apps. Diese Daten werden in der Northware Datenbank gespeichert.
+In der Codebase wird abgefragt, ob ein Benutzer eine bestimmte Berechtigung hat. Die verfügbaren Berechtigungen werden in der Datenbank gespeichert.
+Diese Daten können zu Rollen zusammengefasst werden. Diese Rollen können einer Gruppe von Benutzern zugewiesen werden. 
+Wurde einem Nutzer eine Rolle zugewiesen, erhält er alle Berechtigungen, die der Rolle zugewiesen wurden. Ein Benutzer kann mehrere Rollen erhalten.
+Es ist auch möglich, einem Benutzer einzelne Berechtigungen zuzuweisen, die über die Rollenberechtigungen zu erweitern. 
+Es ist nicht möglich einem Benutzer eine Rollenberechtigung zu entziehen.
+
+### Rollendetails
+
+| Feldname             | Beschreibung                                                   | Eingabeformat         | Beispiel                    |
+| -------------------- | -------------------------------------------------------------- | --------------------  | --------                    |
+| Schlüsselbezeichnung | Der eindeutige Schlüssel der Rolle, der im Code verwendet wird | app::rolestring.role  | app::hr-management          |
+| Rollenbezeichnung    | Die kurze und lesbare Bezeichnung der Rolle                    | String                | Verwaltung von Mitarbeitern |
+| Rollenberechtigungen | Relationen zu Berechtigungen der Northware Suite               | Many-to-many Relation |                             |
+
+### Details der Berechtigungsschlüssel
+
+| Feldname               | Beschreibung                                                     | Eingabeformat                      | Beispiel                |
+| --------------------   | --------------------------------------------------------------   | ---------------------------------- | ------------------------|
+| Berechtigungsschlüssel | Der eindeutige Schlüssel der Berechtigung zur Verwendung im Code | app::feature:subfeature.permission | app::hr:employee.create |
+| Bezeichnung            | Die kurze lesbare Bezeichnung der Berechtigung                   | String                             | Mitarbeiter erstellen   |

apps/docs/content/docs/apps/cockpit/admin.mdx

@@ -0,0 +1,10 @@
+---
+title: Northware Cockpit
+description: Die Webapp zur Verwaltung der NCS Group und der Northware Suite
+---
+
+<Callout type="info">
+    Das Northware Cockpit wird lokal unter dem Port 40110 betrieben und unter [northware-cockpit.netlify.app](https://northware-cockpit.netlify.app) veröffentlicht.
+</Callout>
+
+Die NCS Group verwendet das Northware Cockpit um das eigene Unternehmen zu verwalten. Außerdem wird die Northware Suite über das Northware Cockpit administriert.

apps/docs/content/docs/apps/cockpit/index.mdx

@@ -0,0 +1,12 @@
+---
+title: Northware Storybook
+description: Die Dokumentation von @northware/ui
+---
+
+<Callout type="info">
+Das Storybook wird lokal unter dem Port 40181 betrieben und unter [northware-storybook.netlify.app](https://northware-storybook.netlify.app) veröffentlicht.
+</Callout>
+
+Im Storybook ist alles rund um [`@northware/ui`](/packages/ui/) dokumentiert. 
+Dort ist beschrieben, wie das Package in den Northware Apps verwendet werden.
+`@northware/ui` stellt die Grundstruktur und das gemeinsame Styling für die Apps genau so bereit, wie gemeinsame Komponenten und Icons.

apps/docs/content/docs/apps/storybook.mdx

@@ -1,12 +1,14 @@
 ---
 title: '@northware/auth'
-description: Authentifizierung, Login und Rechte
+description: Funktionen zum Umgang mit Authentifizierung und Zugriffsbeschränkungen von Benutzern.
 ---
 
-Das Package `@northware/auth` stellt die Authentifizierungs- und Loginfunktion für die Northware Apps bereit.
-Das Package nutzt für diese Funktionalität [Auth.js](https://authjs.dev/) mit dem Credentials Provider.
+Das Package `@northware/auth` stellt die Authentifizierungsfunktion für die Northware Apps bereit.
+Außerdem wird über dieses Package der Umgang mit Zugriffsberechtigungen gesteuert.
+Das Package nutzt für diese Funktionalität den Service von [Clerk](https://clerk.com/) und einige spezielle Funktionen zum Abruf von Zugriffsberechtigungen.
 
-Die User-Daten werden in der Neon API gespeichert. Die Definition der Tabelle der Nutzerdaten wird vom `@northware/database` Package übernommen.
-Innerhalb von `@northware/auth` wird auf die Nutzerdaten zugegriffen und validiert.
+Das Package stellt alle Funktionen des Packages `@clerk/nextjs` client- und serverseitig bereit. 
+Mithilfe dieser Funktionen kann sich ein Benutzer in einer App an- und abmelden. 
+Außerdem werden die von Clerk gespeicherten Nutzerdaten von diesem Package bereitgestellt.
 
-Der Code im `@northware/auth` Package ist vom Repository [vercel/nextjs-postgres-auth-starter](https://github.com/vercel/nextjs-postgres-auth-starter) inspiriert.
+Darauf aufbauend stellt `@northware/auth` einige Funktionen bereit, um die Berechtigungen eines Benutzers aus der Northware Datenbank abzurufen.

apps/docs/content/docs/packages/auth.mdx

@@ -0,0 +1,65 @@
+---
+title: "@northware/tsconfig"
+description: Config Presets für TypeScript in den Apss und Packages
+---
+
+Das Package `@northware/tsconfig` stellt einige Config-Presets für TypeScript zur Verfügung, die von Apps und Packages verwendet werden.
+Durch die Verwendung dieser Presets wird sichergestellt, das alle Apps und Packages den gleichen Konfigurationsstandards unterliegen.
+
+Das Package basiert auf einem Standard-Package von Turborepo. Die Standard-Konfigurationen allerdings auf den Stack in diesem Projekt abgestimmt.
+Auf der [Website von Turborepo](https://turborepo.com/docs/guides/tools/typescript) ist genauer beschrieben, 
+wie das Package funktioniert und konfiguriert werden kann.
+
+## Das Base Preset
+
+In der Datei `base.json` ist die Basis-Konfiguration von TypeScript definiert. Diese Konfiguration wird von allen übrigen Presets verwendet und erweitert.
+
+## TSConfig in einer Next.js App
+
+Das Preset `@northware/tsconfig/nextjs.json` enthält die Standard-Konfiguration für Next.js Apps.
+Innerhalb der einzelnen Apps muss dieses Preset dann nur noch importiert werden und die `baseUrl`, 
+einzelne `paths` und die zu prüfenden Dateien müssen definiert werden.
+
+```json title="tsconfig.json in einer App"
+{
+  "extends": "@northware/tsconfig/nextjs.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./src/*"],
+      "@northware/ui/*": ["../../packages/ui/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
+```
+
+Sollte es in einer App spezielle Anforderungen an die TypeScript Konfiguration geben, kann das Next.js Preset in der `tsconfig.json` der App erweitert werdem.
+
+## TSConfig in einem Package
+
+Das Preset `@northware/tsconfig/react-library.json` enthält die Standard-Konfiguration für alle Packages ([Library Packages](https://turborepo.com/docs/core-concepts/package-types#library-packages)) 
+innerhalb des Monorepos. 
+
+Das Preset kann innerhalb der einzelnen Packages importiert werden. Hier müssen dann nur noch die `baseUrl` und die zu beachtenden Dateien definiert werden.
+
+```json title="tsconfig.json in einem Package"
+{
+  "extends": "@northware/tsconfig/react-library.json",
+  "include": ["."],
+  "exclude": ["node_modules"],
+  "compilerOptions": {
+    "baseUrl": "."
+  }
+}
+```
+
+Dieses Preset enthält weniger Konfigurationen als das Next.js Preset. 
+Die Konfigurationen können bei Bedarf auf die individuellen Anforderungen des Packages abgestimmt werden.
+
+<Callout type="info">
+Wenn nötig können einzelne Packages auch das Next.js Preset verwenden, 
+falls die Library-Konfiguration für das individuelle Package nicht ausreichend ist oder zu Problemen führt.
+</Callout>