Merge pull request #2 from fbraem/feature/c

FastAPI frontend release

.github/workflows/backend_test.yml

@@ -17,18 +17,18 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10"]
+        python-version: ["3.12"]
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install Poetry
         run: pip install poetry
       - name: Install dependencies
-        working-directory: backend/src
-        run: poetry install
+        working-directory: backend
+        run: poetry install --with dev,docs
       - name: Start MySQL
         run: |
           sudo systemctl enable mysql.service
@@ -48,6 +48,32 @@ jobs:
           KWAI_EMAIL_PASSWORD: ${{ secrets.KWAI_EMAIL_PASSWORD }}
         run: |
           cat <<EOF > .kwai.toml
+          [frontend]
+          test = true
+          path = ""
+          root_app = "portal"
+          [frontend.apps.portal]
+          base="/apps/portal"
+          base_dev="http://localhost:3000"
+          entries="/src/index.ts"
+          [frontend.apps.author]
+          base="/apps/author"
+          base_dev="http://localhost:3001"
+          entries="/src/index.ts"
+          [frontend.apps.auth]
+          base="/apps/auth"
+          base_dev="http://localhost:3002"
+          entries="/src/index.ts"
+          [frontend.apps.coach]
+          base="/apps/coach"
+          base_dev="http://localhost:3003"
+          entries="/src/index.ts"
+          [frontend.apps.club]
+          base="/apps/club"
+          base_dev="http://localhost:3004"
+          entries="/src/index.ts"
+          [files]
+          path = "/var/tmp/kwai"
           [security]
           jwt_secret="$KWAI_JWT_SECRET"
           jwt_refresh_secret="$KWAI_JWT_SECRET"
@@ -87,18 +113,18 @@ jobs:
           DBMATE_WAIT_TIMEOUT: "30s"
         run: ./dbmate up
       - name: Test with pytest
-        working-directory: backend/src
+        working-directory: backend
         env:
           KWAI_SETTINGS_FILE: ${{github.workspace}}/.kwai.toml
         run: poetry run pytest --cov=kwai --cov-report html
       - name: Generate coverage badge
-        working-directory: backend/src
+        working-directory: backend
         run: poetry run coverage-badge -o ./htmlcov/coverage.svg
       - name: Remove .gitignore from coverage report
-        run: rm backend/src/htmlcov/.gitignore
+        run: rm backend/htmlcov/.gitignore
       - name: Deploy coverage to github pages
         uses: JamesIves/[email protected]
         with:
           branch: gh-pages
           target-folder: coverage
-          folder: backend/src/htmlcov
+          folder: backend/htmlcov

.github/workflows/generate_docs.yml

@@ -10,21 +10,21 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout
-      uses: actions/checkout@master
+      uses: actions/checkout@v4
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@v3
+    - uses: actions/setup-python@v5
       with:
-        python-version: "3.10"
+        python-version: "3.12"
     - name: Install Poetry
       run: pip install poetry
     - name: install
-      working-directory: backend/src
-      run: poetry install
+      working-directory: backend
+      run: poetry install --with docs
     - name: Build documentation
-      working-directory: backend/src
+      working-directory: backend
       run: |
-        poetry run mkdocs build -f ../../mkdocs.yml
+        poetry run mkdocs build -f ../mkdocs.yml
     - name: Copy site
       run: |
         mkdir -p gh-pages

.github/workflows/mirror.yml

@@ -0,0 +1,27 @@
+name: Mirror to Codeberg
+
+on:
+  push:
+    branches: ["**"]
+    tags: ["**"]
+  release:
+    types: ["published"]
+  workflow_dispatch:
+
+jobs:
+  mirror:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: "Mirror to codeberg"
+        uses: cssnr/mirror-repository-action@master
+        with:
+          host: https://codeberg.org
+          owner: zumuta
+          repo: kwai
+          username: ${{ secrets.CODEBERG_USER }}
+          password:  ${{ secrets.CODEBERG_TOKEN }}

.github/workflows/ruff.yml

@@ -10,8 +10,8 @@ jobs:
   ruff:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: chartboost/ruff-action@v1
+      - uses: actions/checkout@v4
+      - uses: astral-sh/ruff-action@v1
         with:
           src: "${{ github.workspace }}/backend/src"
-          args: --ignore D102
+          args: check --ignore D102

.gitignore

@@ -9,7 +9,6 @@
 /_site/
 /backend/src/.venv/
 /backend/src/.coverage
-.turbo
 dist
 node_modules
 public
@@ -24,3 +23,8 @@ __pycache__
 /frontend/apps/portal/images/*.jpg
 *.tsbuildinfo
 stats.html
+/backend/.venv/
+/frontend/packages/kwai-config/src/config.production.toml
+.task
+/frontend/.env.test
+/backend/db/schema.sql

.pre-commit-config.yaml

@@ -22,11 +22,11 @@ repos:
         language_version: python3.12
 -   repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.3.2
+    rev: v0.7.3
     hooks:
     -   id: ruff
         types: [python]
-        args: [--ignore=D102]
+        args: [--ignore=D102, --fix]
 -   repo: https://github.com/gitleaks/gitleaks
     rev: v8.18.2
     hooks:

Taskfile.yml

@@ -0,0 +1,20 @@
+version: '3'
+
+tasks:
+  # build documentation
+  build_doc:
+    desc: Build the documentation
+    dir: backend
+    cmds:
+      - poetry run mkdocs build -f ../mkdocs.yml
+
+  serve_doc:
+    desc: Build the documentation and run the webserver
+    dir: backend
+    cmds:
+      - poetry run mkdocs serve -f ../mkdocs.yml
+
+includes:
+  frontend:
+    taskfile: ./frontend/Taskfile.yml
+    dir: ./frontend

backend/docs/api/api_auth.md

@@ -1,14 +1,57 @@
 # Auth API's
-## ::: kwai.api.v1.auth.endpoints.login
-    selection:
-        members: no
 
-### ::: kwai.api.v1.auth.endpoints.login.login
-### ::: kwai.api.v1.auth.endpoints.login.logout
-### ::: kwai.api.v1.auth.endpoints.login.recover_user
-### ::: kwai.api.v1.auth.endpoints.login.renew_access_token
-### ::: kwai.api.v1.auth.endpoints.login.reset_password
+All API's used for authentication, authorization, users, ...
 
-# Auth Responses
+## /api/v1/auth
 
-### ::: kwai.api.v1.auth.endpoints.login.TokenSchema
+### Requests
+
+::: kwai.api.v1.auth.endpoints.login.renew_access_token
+    options:
+        heading_level: 4
+
+::: kwai.api.v1.auth.endpoints.login.login
+    options:
+        heading_level: 4
+
+::: kwai.api.v1.auth.endpoints.login.logout
+    options:
+        heading_level: 4
+
+::: kwai.api.v1.auth.endpoints.login.recover_user
+    options:
+        heading_level: 4
+
+::: kwai.api.v1.auth.endpoints.login.reset_password
+    options:
+        heading_level: 4
+
+::: kwai.api.v1.auth.endpoints.user.get
+    options:
+        heading_level: 4
+
+### Responses
+
+#### ::: kwai.api.v1.auth.endpoints.login.TokenSchema
+    options:
+      show_root_toc_entry: false
+
+## /api/v1/auth/users
+
+### Requests
+
+::: kwai.api.v1.auth.endpoints.user_invitations.create_user_invitation
+    options:
+        heading_level: 4
+
+::: kwai.api.v1.auth.endpoints.user_invitations.delete_user_invitation
+    options:
+        heading_level: 4
+
+::: kwai.api.v1.auth.endpoints.user_invitations.get_user_invitations
+    options:
+        heading_level: 4
+
+::: kwai.api.v1.auth.endpoints.user_invitations.get_user_invitation
+    options:
+        heading_level: 4

backend/docs/api/index.md

@@ -0,0 +1,13 @@
+# API
+
+## [Authentication](./api_auth.md)
+
+All API's related to authentication.
+
+!!! Note
+
+    Use [swagger](https://swagger.io/) UI from [FastAPI](https://fastapi.tiangolo.com) to get a list of
+    all available api's.
+
+    When the Kwai api backend is running in test mode, point your browser
+    to `http://localhost:<port>/api/docs`.

backend/docs/architecture.md

@@ -0,0 +1,60 @@
+Architecture
+============
+
+Kwai tries to follow the [clean architecture](http://cleancoder.com) principles. The [frontend]() is already a
+separated layer. The backend code is using the domain driven design (DDD) for modeling the software.
+
+One of the rules of clean architecture is that when you don't own or control something, then keep it on the
+outside of your design or wrap it. This means for example, that the domain code isn't allowed to contain FastAPI code
+or database related code. The code for the API is on the outside because it's the entry point of a call to the system.
+Presenters are used to transform domain objects into JSON:API documents. The repository pattern keeps the
+database code on the outside. And interfaces are used to protect the inside from the outside.
+
+The [pendulum](https://pendulum.eustace.io/) library is used for processing dates and timestamps. Because kwai doesn't
+own this code, the pendulum code is wrapped into value objects (Timestamp, Date, ...). If the pendulum package is
+outdated, we only need to change these value objects.
+
+> This is also the reason why [Pydantic](https://docs.pydantic.dev/latest/) isn't used for entities or value objects.
+> Pydantic is great for validation and serialization, but we don't want Pydantic to become a dependency of the kwai
+> domain.
+
+Dependency injection containers are only used on the outside. There should not be any magic code in the domain.
+So, dependency injection containers can only be used in the API entry code, the CLI entry code, ... From there on,
+the dependency should be passed as an argument (and passing it down should be done using an interface).
+
+Actors
+======
+
+Who are the actors in our application?
+
+Visitor
+-------
+
+A visitor is a person that visits our website. He/She does not have any permissions and is
+not known in the system.
+
+Member
+------
+
+A member is a person that is a member of the club.
+
+Coach
+-----
+
+A coach is a member of the club. A coach can create/view/update/delete trainings. A coach can also registers
+participants for a training. When participants are registered, a training can't be deleted anymore.
+
+````mermaid
+sequenceDiagram
+    actor Coach
+    Coach->>Trainings: View
+    Coach->>Trainings: Create
+    Coach->>Trainings: Update
+    Coach->>Trainings: Delete
+    Coach->>Trainings: Register participants
+````
+
+Admin
+-----
+
+An administrator is a person that manages the website.

backend/docs/cli.md

@@ -1,29 +1,28 @@
 # Command Line Interface
-A command line interface (CLI) is provided to help managing the kwai system. To run the cli, use the kwai_cli.py 
+A command line interface (CLI) is provided to help managing the kwai system. To run the cli, use the kwai_cli.py
 script:
 
 `kwai_cli.py --help`
 
-::: kwai.cli.bus
+::: kwai.cli.commands.bus
     options:
         show_root_full_path: False
         show_signature: False
         members:
             - show
             - test
 
-::: kwai.cli.db
+::: kwai.cli.commands.db
     options:
         show_root_full_path: False
         show_signature: False
         members:
             - show
             - test
 
-::: kwai.cli.identity
+::: kwai.cli.commands.identity
     options:
         show_root_full_path: False
         show_signature: False
         members:
             - create
-