docs: document project structure and observability principles

Herve Tribouilloy · Herve Tribouilloy · commit cbded12040c1 · 2026-01-25T13:56:00.000Z
diff --git a/.gitignore b/.gitignore
@@ -1,139 +1,17 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-lerna-debug.log*
+# IDE
+.idea
 
-# Diagnostic reports (https://nodejs.org/api/report.html)
-report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+# dependencies
+node_modules
 
-# Runtime data
-pids
-*.pid
-*.seed
-*.pid.lock
+# editor temp files
+*.swp
 
-# Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
-
-# Coverage directory used by tools like istanbul
-coverage
-*.lcov
-
-# nyc test coverage
-.nyc_output
-
-# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# Bower dependency directory (https://bower.io/)
-bower_components
-
-# node-waf configuration
-.lock-wscript
-
-# Compiled binary addons (https://nodejs.org/api/addons.html)
-build/Release
-
-# Dependency directories
-node_modules/
-jspm_packages/
-
-# Snowpack dependency directory (https://snowpack.dev/)
-web_modules/
-
-# TypeScript cache
-*.tsbuildinfo
-
-# Optional npm cache directory
-.npm
-
-# Optional eslint cache
-.eslintcache
-
-# Optional stylelint cache
-.stylelintcache
-
-# Optional REPL history
-.node_repl_history
-
-# Output of 'npm pack'
-*.tgz
-
-# Yarn Integrity file
-.yarn-integrity
-
-# dotenv environment variable files
+# local environment
 .env
-.env.*
-!.env.example
-
-# parcel-bundler cache (https://parceljs.org/)
-.cache
-.parcel-cache
-
-# Next.js build output
-.next
-out
-
-# Nuxt.js build / generate output
-.nuxt
-dist
-
-# Gatsby files
-.cache/
-# Comment in the public line in if your project uses Gatsby and not Next.js
-# https://nextjs.org/blog/next-9-1#public-directory-support
-# public
-
-# vuepress build output
-.vuepress/dist
-
-# vuepress v2.x temp and cache directory
-.temp
-.cache
-
-# Sveltekit cache directory
-.svelte-kit/
-
-# vitepress build output
-**/.vitepress/dist
-
-# vitepress cache directory
-**/.vitepress/cache
-
-# Docusaurus cache and generated files
-.docusaurus
-
-# Serverless directories
-.serverless/
-
-# FuseBox cache
-.fusebox/
-
-# DynamoDB Local files
-.dynamodb/
-
-# Firebase cache directory
-.firebase/
-
-# TernJS port file
-.tern-port
-
-# Stores VSCode versions used for testing VSCode extensions
-.vscode-test
-
-# yarn v3
-.pnp.*
-.yarn/*
-!.yarn/patches
-!.yarn/plugins
-!.yarn/releases
-!.yarn/sdks
-!.yarn/versions
+widget.local.crt
+widget.local.key
 
-# Vite logs files
-vite.config.js.timestamp-*
-vite.config.ts.timestamp-*
+# generated / local artefacts
+www
+test-results
diff --git a/README.md b/README.md
@@ -38,9 +38,29 @@ This widget focuses on **delivery and safety**, not business promises.
 - **Deferred by default** – does not require early page execution to function
 - **Layered structure** – organised to encourage consistency across ReactEdge widgets without enforcing a framework
 - **Boring on purpose** – clarity over cleverness
+- **Observable by the host** – key lifecycle and interaction events are emitted to allow integration with analytics or monitoring tools without coupling to a specific provider
 
 ---
 
+## Project structure (high level)
+
+This repository contains the widget itself, along with supporting tooling used for development, testing, and community maintenance.
+
+- `vite_project/`  
+  Source code for the USP widget and its build configuration.
+
+- `tests/`  
+  End-to-end tests (Playwright) used to validate widget behaviour in a real browser environment.
+
+- `docker/` and `docker-compose.yml`  
+  Optional local development tooling. These are provided for convenience and are not required to use the widget.
+
+- `.github/`  
+  GitHub metadata (issue templates, CI workflows, etc.) to support collaboration and maintainability.
+
+- `www/`  
+  Generated build output. This folder is intentionally not committed to the repository.
+
 ## Installation (high level)
 
 The widget is delivered as a standalone JavaScript file and exposed via a custom element.
@@ -51,3 +71,45 @@ Typical usage looks like:
 <script src="path-to-widget.js"></script>
 
 <reactedge-usp-widget></reactedge-usp-widget>
+```
+
+## Local development
+
+This project uses Node.js and npm.
+
+From the repository root:
+
+```bash
+npm install
+```
+
+To run the widget locally:
+
+```bash
+cd vite_project
+npm install
+npm run dev
+```
+
+To run the test suite:
+```bash
+npx playwright test --config=tests/playwright.dev.config.ts
+```
+
+## Deploying the widget
+
+ReactEdge widgets are deployed as **static JavaScript artefacts**.
+They do not require a server-side runtime once built.
+
+### Build the artefact
+
+From the `vite_project` directory:
+
+```bash
+npm run build
+```
+
+This produces a versioned JavaScript file in the www/ directory
+(e.g. widget-usp@x.y.z.iife.js).
+
+The www/ Generated build output produced by the build process. This folder is intentionally not committed to the repository.
diff --git a/docker/nginx_vite/ssl/widget.local.crt b/docker/nginx_vite/ssl/widget.local.crt
@@ -1,19 +1,19 @@
 -----BEGIN CERTIFICATE-----
-MIIDFzCCAf+gAwIBAgIUAldtzZoCay1Lh6bRuR4FnXWcVmYwDQYJKoZIhvcNAQEL
-BQAwGzEZMBcGA1UEAwwQd2lkZ2V0LnVzcC5jby51azAeFw0yNTEyMTAxNDM0MDFa
-Fw0yNjEyMTAxNDM0MDFaMBsxGTAXBgNVBAMMEHdpZGdldC51c3AuY28udWswggEi
-MA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCtlrJlXq0TOsxo/JNSFl1yNYVz
-1kCi8gcnfVonb8WjffQTR5fgB1M1mfMPhy6D55SrNGYtkTJF3tPdo9nRICqo9AFj
-L0LHaLZ10c6Mbh+EhQAVAepuEgmEUHDIT5e1m/nPBfh7jMAs6ezGHl1j9xFjtLTS
-XESGpvFT/otzYTXSwgB9yATwdAy7ruQZkeTs43q1Rkdk5lQFcBIOcawoUxWdytrt
-nMfHRBkUw10S4KWIr2yQDPaEWv0S4zTdn9EFRcfgbAJhKTfM5dTRQ7TDGmoy+ZAC
-Isq4l+KsEMKU6ZiLgKHDmSpcVh/iuDKCpok5+4uBpmUGdBDsPJRmI370EEyjAgMB
-AAGjUzBRMB0GA1UdDgQWBBRrgBZCIAZzOtSbgILDIA+zgMY+6jAfBgNVHSMEGDAW
-gBRrgBZCIAZzOtSbgILDIA+zgMY+6jAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3
-DQEBCwUAA4IBAQAtze3F9PiOMGmqufJu00a5uRpEusr9+C7TWGZS0Q71R3ORFkyr
-klUYftU6X94qA7UByhI5JiRdJ4b2jjsRkkl58kavlMDrzrIFSjN4+lP2bYdf+VBj
-hqszVgDqpM/MXfZsDUFyWGyy+AhlT2xqm//WrYmLovJLfwgMZD0YpR0EbqavrLXK
-K2adNzXYF1DELwdgUQ2NF9fj7Vd9WBxD1j2FSMJSbqNolniQTw7lB5mmW327FN3u
-GcIT4gjjHRTFZaptsfjv+b/bXqIW4pmXadbbjJti3zTXDq/SNugo8hP8j5I/zAcG
-VXI+8eqzkA/oaGbSHGShLI2Ttrg9vBG0Sgw5
+MIIDFzCCAf+gAwIBAgIUJaHvmg4HnMztVd5+tlPGpd8wmYYwDQYJKoZIhvcNAQEL
+BQAwGzEZMBcGA1UEAwwQd2lkZ2V0LnVzcC5jby51azAeFw0yNjAxMjUxMzQ1NDla
+Fw0yNzAxMjUxMzQ1NDlaMBsxGTAXBgNVBAMMEHdpZGdldC51c3AuY28udWswggEi
+MA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC8zXKanCRMsC9X9ATY9/80xSsB
+7W4ZLU07AZ2EKEi9/qfMK5c4zHrKoQRYLko650yBIa2BTEkmHfJ4sS2e+jIlOF6o
+zB3aATfHxa7G0qLwZXCWPu9/1mgvapCvDU38HiHlrE0dW/fj4/H1NDcaYlbndc5+
+NHEE48HwYkn0RG+B6itHeH1QsZooEa4pvAIzmPE6zNl8NuY8QnfquOWbt3gGV5AC
+i1uUKt2I/D47B8vgIzT22sF9pxFDeZFxcKMASRUjWh26mNB+S5SNmyPT4HSxnwGa
+Zi5IjxioQR8GEFQq9BqmDXEyJHbVa5UhTpcvMPnWA13w8SwrZUDQJ9klYDrFAgMB
+AAGjUzBRMB0GA1UdDgQWBBS+OGSKx3nu665U4alcj2EDCI8feTAfBgNVHSMEGDAW
+gBS+OGSKx3nu665U4alcj2EDCI8feTAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3
+DQEBCwUAA4IBAQCWzwoUvSuGHtSMbTOaPuunRPrk49W2XEibAKvspR51ujkrY0w9
++TcWPNlBOabkBOBke0PnP3hVdm4QqTlCCVJ3EoDpfnJoP3hkt+payMKE3Ksv7yUh
+3UMDJ1lP/X2tzE7Pw32oPEsTO2B0cqfO8GkYgBTkgOeJMDZc0colBsCAx9VHNnIG
+exqI1INB32t40LrMNeEhHkSSgZfeDhXUTxZqgvX5e80ckpGeufzjXKDlrGBQLLgK
+6iCmmvNxYxqBajVIpdb1B6/G+bjAZeElX7/00w8BpAAy8M25+tR1q2130SSdrK5N
+vVzhlsd9dRWwr3oakYzHJCeOP4Fop1x0PalJ
 -----END CERTIFICATE-----
diff --git a/docker/nginx_vite/ssl/widget.local.key b/docker/nginx_vite/ssl/widget.local.key
@@ -1,28 +1,28 @@
 -----BEGIN PRIVATE KEY-----
-MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCtlrJlXq0TOsxo
-/JNSFl1yNYVz1kCi8gcnfVonb8WjffQTR5fgB1M1mfMPhy6D55SrNGYtkTJF3tPd
-o9nRICqo9AFjL0LHaLZ10c6Mbh+EhQAVAepuEgmEUHDIT5e1m/nPBfh7jMAs6ezG
-Hl1j9xFjtLTSXESGpvFT/otzYTXSwgB9yATwdAy7ruQZkeTs43q1Rkdk5lQFcBIO
-cawoUxWdytrtnMfHRBkUw10S4KWIr2yQDPaEWv0S4zTdn9EFRcfgbAJhKTfM5dTR
-Q7TDGmoy+ZACIsq4l+KsEMKU6ZiLgKHDmSpcVh/iuDKCpok5+4uBpmUGdBDsPJRm
-I370EEyjAgMBAAECggEAKop868TZC5ZkU/JaNErQ2dVuACZorsY7pJzexD1rJRcQ
-As2P1dJVvRQechbB+od9crujstUbie4C5BVsowiMC93InUMOzYnG9XbWdKnkRXjG
-vV870X/QH0ILcbu3xUUVYnvnGngy/I7TfPYiEwaQl2vIyKjeDlXJXLlL+ZnANAb5
-/X+6itdSJH0nIj5OENYzwPAEculHehiiVVIl6gZDQLbl7MnSlAz+EjriEXJMxtup
-w13aAEX6Odh7Tj7Omv9VFQAePOgOelUgJtxVMET7kiqP3Pk0oNFpBRGpclcd+mwl
-RNRmdDQYov3YLzsAYgP5BLVmiWb2Y9/QDswfCpI88QKBgQDU4z3oXbb/32CkLj55
-faEleYWlmMPY+KYKGJU13x+YFMFfPLee6yQLA56TpX7kIfyHjz+cU0sBDRAoNgXc
-aZdI+KZcj3l0D67mxwvyO4ZX6QVeAHrWtAWL0gNFd/F3M28TjvEmkKZA6lNXd/p4
-b7rhyW4LnUAQZbYstcUZsyjXuQKBgQDQvhKRFHRBivJ2L55UQbdpwssU/corz1+h
-P6sH30Qkd5zxV+0nvwLWHeE/X1FNeP1yyDlZxnYROYkzV/OFOld7cPU046U4/3LK
-NW/x5DLUJ8cutuZkvV7XmesVaZiZ8pTeKELHvjGSMIpLSNkds1eda2sQYWq1dE2h
-bVNSAPu9OwKBgQDR3rRJPxoJZc2ADZbJbnBO4V4/wjpQy8/kZBe05CHha5S2rsTW
-hjkiIo9SPvS5Mkgh27Z6BiMLBjXHbnqYr//UkExxM4AoSs3B9LhyNPxb7fy8jvyK
-bS6KiJ9w/K2vNaVrQp+5xSAhHuDKeh0SXhN+Q3WZPYzKnXra2NdWXqkFAQKBgDmT
-xBFKgAq4JcrdtaFuAwZkGZovqr1M1QboRefE+MnKSHr1ks+8yy5+TWwqgYWKEva/
-LbqKmHSF10dXQi+EeS7uaGRvSlqfc209MiSZmj+UvUcwYfp1lZyIsyRT3SjRlah1
-mH36AzhctTiw3lpn5ongYEbDaCim7ObS/gGHjeiTAoGAJN5oGwF7kGDhLtMlZsQ3
-dSbUW9FHYkeGWy3i00JpfcmKdH23ldeMABY+WnyrtoNsUa/6pbUgrqaAXDTM2fP4
-CCjv4DtL86fdg9yehWyEybXqiLkpOMvhdcLI+xSgfh4HEptUUVW6lWuUjhFMCnAt
-UV7IlCex5dxNfdNk8RpcSYc=
+MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC8zXKanCRMsC9X
+9ATY9/80xSsB7W4ZLU07AZ2EKEi9/qfMK5c4zHrKoQRYLko650yBIa2BTEkmHfJ4
+sS2e+jIlOF6ozB3aATfHxa7G0qLwZXCWPu9/1mgvapCvDU38HiHlrE0dW/fj4/H1
+NDcaYlbndc5+NHEE48HwYkn0RG+B6itHeH1QsZooEa4pvAIzmPE6zNl8NuY8Qnfq
+uOWbt3gGV5ACi1uUKt2I/D47B8vgIzT22sF9pxFDeZFxcKMASRUjWh26mNB+S5SN
+myPT4HSxnwGaZi5IjxioQR8GEFQq9BqmDXEyJHbVa5UhTpcvMPnWA13w8SwrZUDQ
+J9klYDrFAgMBAAECggEBAIIHvPZes2Fdtj2NAgmsQ0fEw2oAa+NLH/WTlzh9xhuU
+V1x2aR/lNGx5mNRijR0kT7xfxW9XasmltmkJHbJv/jlEKW13pteOHyynKUglqbKH
+KpNPpQMWV4rQifUF5L/OwOm9UR73SDLburh1zb2OHOwsZprk4zHK6rbz+psQxvth
+a+nCJzVWo/r4tvV0qiRsnYKT9U8e8Scbn1VvzKWtwt0OrfvCk96HglTq5WnZRxkM
+5rartSQRuCuSE+JhWr5B4m6igrxtkYNty9xqGdRdpoaPH8LB/9xYy0pRLNFTHf5r
+UybQebE+NDgVL0oyq8DWb4CTdZ1Wae15XXzqCYt5J8ECgYEA7Ia/NqlZn2iITZWm
+T7nIhscEl2Lrwdl0L12aVmlrtcQgAU6XeCrh9G4Lm1J6hv19+bBUkWWNdaWP5lxb
+DQ0elXmHlKwAb+cwVSbZ95nKz3Uy6t7weblS12xZKw/FwxgOz7brXYpnx6/p1f2L
+qDsJAjT0GY7FVDsVffLm5xiVBK8CgYEAzFjUCok6QIYz4bkifrKsvaw4Gw9JgdJx
+rxcm5Xd6Q5qYxtEUYNGUluhoumKdgfIMxrweqw8TuwfwYwDRXA4L6advVw+Xe0O2
+hX3cixE0npZpgxMcweip7QCTssp123p6HEcMHObaU+i+O9S1eA3TTCqd40dVF7Zl
+TAohmc/LvMsCgYBGcQL1ho4YeYtOf+keCVh9OzxU0bMg8mA10wyp+4+GfLiDayKV
+OUA+CaAPTAsNtOUVvbwR6Uqt5PbsRkkfo+6d2anVTzx6F0I/uehkYzsRefgGFwtL
+VTQk0DHmLzZYmgufNPz3yMaLpApiHra/DYXrUFX6XpjKMyZ9ch/uZ1XKJQKBgQCF
+gIMHXx/vh73delZO7+xq/lipVRNw/UvIWBfRUn1OLXIicfYeSs4IyU2id0rv2nL+
+Y2il2PPK/STPiXk96u9dd0YGWulcXqCgFdpAAL2f3iSQvavMA3UAoZ/c7uiQuzOL
+xd7kAu4gY63k6NKl3GJvIGiGU9QD6eXEB9pr4pX4gQKBgHAeduYtgyeGFbiElnXy
+v6KG6l5Isf25VhwPnCJUTlHL/Y9Igo6VVVjN/iUrxBWjwhUa7/GyCOSLXVmMdpAF
+5hm9r7ykJFGL+eP9u8q4pgjeBwXMfXuKHnLptPA5U5aIo3gvN5azzlRwzZq+tOh0
+gv6XUAdjAl/eQRmAqnoCStSt
 -----END PRIVATE KEY-----
diff --git a/package-lock.json b/package-lock.json
diff --git a/vite_project/package-lock.json b/vite_project/package-lock.json
