feat[docs]: documentation site

docs/code-review-checklist.md → .agents/code-review-checklist.md

@@ -4,17 +4,17 @@ When performing code review, double check all of the items below:
 
 - [ ] Confirm that the changes solve the issues the PR is trying to solve partially or fully.
 - [ ] Review the code in terms of the [OWASP top 10 security issues](https://owasp.org/Top10/).
-- [ ] Verify that the code follows the [Code style guide](contributing.md#code-style-guide).
+- [ ] Verify that the code follows the [Code style guide](<docs/src/routes/(content)/developers-guide/contributing/code-style-guide/+page.md>).
 - [ ] Avoid using `any` at all costs. If there is no way to circumvent using it, document the reason carefully and consider using `@ts-expect-error` instead.
 - [ ] There is no code that is repeated within the PR or elsewhere in the repo.
 - [ ] All new components, functions and other entities are documented
 - [ ] The repo documentation markdown files are updated if the changes touch upon those.
 - [ ] If the change adds functions available to the user, tracking events are enabled with new ones defined if needed.
-- [ ] Any new Svelte components that have been created, follow the [Svelte component guidelines](contributing.md#svelte-components).
+- [ ] Any new Svelte components that have been created follow the [Svelte component guidelines](<docs/src/routes/(content)/developers-guide/contributing/code-style-guide/+page.md>).
 - [ ] Errors are handled properly and logged in the code.
 - [ ] Troubleshoot any failing checks in the PR.
 - [ ] Check that parts of the application that share dependencies with the PR but are not included in it are not unduly affected.
 - [ ] The changes pass the [WGAC A and AA requirements for accessibility](https://usability.yale.edu/web-accessibility/articles/wcag2-checklist).
 - [ ] The changed parts of the app are fully usable with keyboard navigation and screen-reading.
 - [ ] Documentation is added wherever necessary.
-- [ ] The commit history is clean and linear, and the commits follow the [commit guidelines](contributing.md#commit-your-update)
+- [ ] The commit history is clean and linear, and the commits follow the [commit guidelines](<docs/src/routes/(content)/developers-guide/contributing/contribute/+page.md>)

.claude/settings.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": ["Bash(yarn test:*)", "Bash(find:*)"],
+    "deny": [],
+    "ask": []
+  }
+}

.env.example

@@ -1,9 +1,12 @@
-# Strapi dependencies
+################################################################
+# Backend: Strapi configuration
+################################################################
+
 STRAPI_HOST=0.0.0.0
 STRAPI_PORT=1337
 APP_KEYS="toBeModified1,toBeModified2"
 API_TOKEN_SALT=tobemodified
-# ADMIN_JWT_SECRET and JWT_SECRET has to be different
+# ADMIN_JWT_SECRET and JWT_SECRET have to be different
 ADMIN_JWT_SECRET=tobemodified
 JWT_SECRET=tobemodified2
 DATABASE_HOST=postgres
@@ -14,10 +17,18 @@ DATABASE_PASSWORD=strapi
 DATABASE_SCHEMA=public
 DATABASE_SSL_SELF=false
 
+# See also PUBLIC_BROWSER_FRONTEND_URL below
+
+################################################################
+# Backend: AWS LocalStack (development only)
+################################################################
+
 ## AWS LocalStack development endpoint
 LOCALSTACK_ENDPOINT=http://127.0.0.1:4566
 
-## AWS SES Settings
+################################################################
+# Backend: AWS SES email, used by Strapi
+################################################################
 
 ## These settings correspond to LocalStack system defaults
 ## https://docs.localstack.cloud/references/configuration/
@@ -30,50 +41,87 @@ MAIL_FROM="no-reply@openvaa.org"
 MAIL_FROM_NAME="Voting Advice Application"
 MAIL_REPLY_TO="contact@openvaa.org"
 
-## AWS S3 settings
-
-AWS_S3_BUCKET=static.openvaa.org
+################################################################
+# Backend: AWS S3 storage, used by Strapi
+################################################################
 
 ## These settings correspond to LocalStack system defaults
 ## https://docs.localstack.cloud/references/configuration/
 AWS_S3_ACCESS_KEY_ID="test"
 AWS_S3_ACCESS_SECRET="test"
 AWS_S3_REGION=us-east-1
 
+## S3 bucket name used by Strapi to store static content (e.g. images uploaded via Strapi's UI)
+AWS_S3_BUCKET=static.openvaa.org
+
 ## The base URL is used to access static content uploaded via Strapi's UI to AWS S3:
 ## - on production it uses a dedicated subdomain which is linked to an eponymous AWS S3 bucket via a CNAME DNS record
 ## - in development it points directly to LocalStack host and is appended by the S3 bucket name in Strapi's `plugin.ts`
 STATIC_CONTENT_BASE_URL=http://localhost:4566
 STATIC_MEDIA_CONTENT_PATH=public/media
 
-# Point to a folder (relative to /backend/vaa-strapi) if you want to load data on initialise. This will only take place if the database contains no Election
-LOAD_DATA_ON_INITIALISE_FOLDER=""
+################################################################
+# Backend: Mock data generation in Strapi
+################################################################
 
 # Set to true to enable mock data on an empty database
 GENERATE_MOCK_DATA_ON_INITIALISE=true
 
 # Used only in development builds
 GENERATE_MOCK_DATA_ON_RESTART=false
 
-# LLM
-LLM_OPENAI_API_KEY=""
+################################################################
+# Frontend: configuration
+################################################################
 
 # Frontend dependencies
 # NB! If adding more such urls with different hosts on the server and client, please check whether /frontend/src/routes/[[lang=locale]]/api/cache/+server.ts needs to be updated accordingly
 # Used to reach backend instance from a browser
 PUBLIC_BROWSER_BACKEND_URL=http://localhost:1337
 # Used to reach frontend instance from a server (differs from `PUBLIC_BROWSER_BACKEND_URL` when using Docker)
 PUBLIC_SERVER_BACKEND_URL=http://strapi:1337
-# Used to reach frontend instance from a browser
+# Used to reach frontend instance from a browser. NB. This variable is used by Strapi
 PUBLIC_BROWSER_FRONTEND_URL=http://localhost:5173
 # Used to reach frontend instance from a server (differs from `PUBLIC_BROWSER_FRONTEND_URL` when using Docker)
 PUBLIC_SERVER_FRONTEND_URL=http://frontend:5173
 
+# Make sure this martches the urls above
 FRONTEND_PORT=5173
 
+################################################################
+# Frontend: cache settings
+################################################################
+
+# FlatCache disk cache settings
+
+# Set to 'true' to enable the cache. The variable must be public because the universal data adapter uses it.
+PUBLIC_CACHE_ENABLED=false
+# An absolute path to the cache location
+CACHE_DIR=/var/data/cache
+# "Time-To-Live" (TTL) means each cached item will be removed after {env.CACHE_TTL} seconds, even if it's still needed.
+# 86400000 seconds = 24 hours
+CACHE_TTL=86400000
+#  "Least Recently Used" (LRU) means the cache will only keep the most recent {env.CACHE_LRU_SIZE} items.
+CACHE_LRU_SIZE=1000
+#  The cache checks for expired items every {env.CACHE_EXPIRATION_INTERVAL} seconds and removes them.
+# 3600000 seconds = 1 hour
+CACHE_EXPIRATION_INTERVAL=3600000
+
+################################################################
+# Frontend: local data adapter settings
+################################################################
+
 # An absolute path to the local data location when using the local data adapter
 LOCAL_DATA_DIR=/var/data/local
 
+################################################################
+# Frontend: pregistration settings
+################################################################
+
+# Source: {PUBLIC_BROWSER_BACKEND_URL}/admin/settings/api-tokens
+# Minimal permissions: Users-Permissions > Candidate > Preregister
+BACKEND_API_TOKEN=api_token
+
 # IdP (Signicat)
 
 # Source: https://openvaa.sandbox.signicat.com/auth/open/.well-known/openid-configuration
@@ -94,24 +142,15 @@ IDENTITY_PROVIDER_CLIENT_SECRET=client_secret
 # Select "Encryption", keep the private part of the key pair.
 IDENTITY_PROVIDER_DECRYPTION_JWKS='[{"kty":"RSA","kid":"{key_id}","use":"enc","alg":"RSA-OAEP","e":"{secret}","n":"{secret}","d":"{secret}","p":"{secret}","q":"{secret}","dp":"{secret}","dq":"{secret}","qi":"{secret}"}]'
 
-# Source: {PUBLIC_BROWSER_BACKEND_URL}/admin/settings/api-tokens
-# Minimal permissions: Users-Permissions > Candidate > Preregister
-BACKEND_API_TOKEN=api_token
+################################################################
+# Frontend: LLM settings, used by the Admin App
+################################################################
 
-# If 'true', frontend debug messages will be logged even in production
-PUBLIC_DEBUG=false
+LLM_OPENAI_API_KEY=""
 
-# FlatCache disk cache settings
+################################################################
+# Debugging
+################################################################
 
-# Set to 'true' to enable the cache. The variable must be public because the universal data adapter uses it.
-PUBLIC_CACHE_ENABLED=false
-# An absolute path to the cache location
-CACHE_DIR=/var/data/cache
-# "Time-To-Live" (TTL) means each cached item will be removed after {env.CACHE_TTL} seconds, even if it's still needed.
-# 86400000 seconds = 24 hours
-CACHE_TTL=86400000
-#  "Least Recently Used" (LRU) means the cache will only keep the most recent {env.CACHE_LRU_SIZE} items.
-CACHE_LRU_SIZE=1000
-#  The cache checks for expired items every {env.CACHE_EXPIRATION_INTERVAL} seconds and removes them.
-# 3600000 seconds = 1 hour
-CACHE_EXPIRATION_INTERVAL=3600000
+# If 'true', frontend debug messages will be logged even in production
+PUBLIC_DEBUG=false

.github/workflows/claude-code-review.yml

@@ -52,7 +52,7 @@ jobs:
 
             Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
 
-            Make sure to check all the items in the [Code Review Checklist](/docs/code-review-checklist.md).
+            Make sure to check all the items in the [Code Review Checklist](/.agents/code-review-checklist.md).
 
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options

.github/workflows/docs.yml

@@ -0,0 +1,73 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - deploy-docs
+    paths:
+      - 'docs/**'
+      - 'packages/**'
+      - 'frontend/src/lib/**'
+      - 'scripts/generate-docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'yarn'
+
+      - name: Install dependencies
+        run: |
+          yarn install --immutable
+          cd docs
+          yarn install --immutable
+
+      - name: Build shared packages
+        run: yarn build:shared
+
+      - name: Generate documentation
+        run: |
+          cd docs
+          yarn generate:docs
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Build docs site
+        run: |
+          cd docs
+          yarn build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/build
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -4,11 +4,14 @@
 !.env.example
 node_modules
 
+# Claude Code local settings
+.claude/*.local.json
+
 # Yarn 4 without Zero-installs
 .pnp.*
 .yarn/*
 !.yarn/patches
 !.yarn/plugins
 !.yarn/releases
 !.yarn/sdks
-!.yarn/versions
+!.yarn/versions

.lintstagedrc.json

@@ -2,7 +2,7 @@
   "*.{html,js,jsx,cjs,mjssvelte,ts,tsx,cts,mts,xml,yaml,yml}": [
     "yarn build:app-shared",
     "prettier --write",
-    "eslint --fix --flag unstable_config_lookup_from_file"
+    "eslint --fix --flag v10_config_lookup_from_file"
   ],
   "*.{css,json,md}": ["yarn build:app-shared", "prettier --write"]
 }

.prettierignore

@@ -28,4 +28,7 @@ frontend/package
 frontend/tailwind.config.cjs
 # Ignores copied from /tests/.prettierignore
 tests/test-results/
-tests/playwright*/
+tests/playwright*/
+# Ignores docs because it must be formatted separately due to different Svelte version
+# TODO[Svelte 5]: Remove this limitation
+docs

CLAUDE.md

@@ -309,3 +309,7 @@ Recent costs (2024-2025): $80-350/month depending on traffic and instance sizes.
 **2025 H2**: Documentation site, AI features, application manager UI, first production release
 
 **2026**: Plugins/customization, multi-tenant model, migration from Strapi to Supabase, Svelte 5 upgrade
+
+## Code Review
+
+When performing code review or developing new features, make sure to check all the items in the [Code Review Checklist](/.agents/code-review-checklist.md).