👷📝 Move some internal doc inside the repo

.github/workflows/deploy-docs.yml → .github/workflows/deploy-generated-docs.yml

@@ -50,7 +50,7 @@ jobs:
       - name: Upload artifact
         uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
         with:
-          path: './docs'
+          path: './generated-docs'
 
       - name: Deploy to GitHub Pages
         id: deployment

.gitignore

@@ -10,7 +10,7 @@ specs.log
 /test-report/
 browserstack.err
 package.tgz
-docs/
+generated-docs/
 *.tsbuildinfo
 /developer-extension/dist
 /developer-extension/.wxt

.prettierignore

@@ -8,6 +8,6 @@ test/**/dist
 test/**/.next
 test/apps/nextjs/next-env.d.ts
 yarn.lock
-/docs
+/generated-docs
 /developer-extension/.output
 /developer-extension/.wxt

.wokeignore

@@ -1,7 +1,7 @@
 **/dist/**
 yarn.lock
 .yarn/releases
-docs
+generated-docs
 
 # code import
 packages/worker/src/domain/deflate.js

AGENTS.md

@@ -60,6 +60,8 @@ packages/
 
 developer-extension/ # Chrome DevTools extension
 
+docs/                # Repository documentation
+
 test/
 ├── apps/            # Test apps for E2E and performance testing
 ├── e2e/             # Playwright E2E test scenarios
@@ -69,6 +71,17 @@ test/
 scripts/             # Build, deploy, release automation
 ```
 
+## Documentation
+
+For deeper context, see:
+
+- `docs/DEVELOPMENT.md` — commit conventions, dependency management, schema generation, TS compatibility
+- `docs/CONVENTIONS.md` — coding style, file organization, size control
+- `docs/ARCHITECTURE.md` — package dependencies, data pipeline
+- `docs/TESTING.md` — local testing strategies, debugging flaky tests
+- `scripts/AGENTS.md` — writing and organizing scripts in this codebase
+- `test/e2e/AGENTS.md` — E2E test writing guide (createTest builder, IntakeRegistry, patterns)
+
 ## Critical Patterns
 
 ### Unit Tests
@@ -102,29 +115,7 @@ scripts/             # Build, deploy, release automation
 
 ## Commit Messages
 
-Use gitmoji conventions (based on actual usage in this repo):
-
-### User-Facing Changes
-
-- ✨ **New feature** - New public API, behavior, event, property
-- 🐛 **Bug fix** - Fix bugs, regressions, crashes
-- ⚡️ **Performance** - Improve performance, reduce bundle size
-- 💥 **Breaking change** - Breaking API changes
-- 📝 **Documentation** - User-facing documentation
-- ⚗️ **Experimental** - New public feature behind a feature flag
-
-### Internal Changes
-
-- 👷 **Build/CI** - Dependencies, tooling, deployment, CI config
-- ♻️ **Refactor** - Code restructuring, architectural changes
-- 🎨 **Code structure** - Improve code structure, formatting
-- ✅ **Tests** - Add/fix/improve tests
-- 🔧 **Configuration** - Config files, project setup
-- 🔥 **Removal** - Remove code, features, deprecated items
-- 👌 **Code review** - Address code review feedback
-- 🚨 **Linting** - Add/fix linter rules
-- 🧹 **Cleanup** - Minor cleanup, housekeeping
-- 🔊 **Logging** - Add/modify debug logs, telemetry
+Use gitmoji conventions — see `docs/DEVELOPMENT.md` for the full reference.
 
 ## Git Workflow
 

CONTRIBUTING.md

@@ -18,50 +18,17 @@ Have you fixed a bug or written a new feature and want to share it? Many thanks!
 In order to ease/speed up our review, here are some items you can check/improve when submitting your
 pull request:
 
+- Follow this repository [Documentation][2]
 - Keep commits small and focused, rebase your branch if needed.
 - Write unit and e2e tests for the code you wrote.
-- Write meaningful [Commit messages and Pull Request
-  titles](#commit-messages-and-pull-request-titles)
+- Write meaningful [Commit messages and Pull Request titles][3]
+- Sign your commits, see [Github's documentation][4]
+- Sign the CLA
 
 Our CI is not (yet) public, so it may be difficult to understand why your pull request status is
 failing. Make sure that all tests pass locally, and we'll try to sort it out in our CI.
 
-## Modules usage convention
-
-Use index.ts files to expose a single, minimal API in directories where modules are used together.
-Do not use index.ts when a directory contains independent modules.
-An index.ts file should not have exports only used for spec files.
-
-## Commit messages and Pull Request titles
-
-Messages should be concise but explanatory. We are using a convention inspired by [gitmoji][2], to
-label our Commit messages and Pull Request titles:
-
-### User-facing changes
-
-💥 - Breaking change.
-
-✨ - New feature.
-
-🐛 - Bug fix.
-
-⚡️ - Performance improvement.
-
-📝 - Documentation.
-
-⚗ - Experimental.
-
-### Internal changes
-
-👷 - Updating project setup (continuous integration, build system, package dependencies...).
-
-♻️ - Refactoring code.
-
-🎨 - Improving structure / format of the code.
-
-✅ - Updating tests.
-
-👌 - Updating code due to code review changes.
-
 [1]: https://docs.datadoghq.com/help/
-[2]: https://gitmoji.carloscuesta.me/
+[2]: https://github.com/DataDog/browser-sdk/blob/main/docs/README.md
+[3]: https://github.com/DataDog/browser-sdk/blob/main/docs/DEVELOPMENT.md#commit-messages-and-pull-request-titles
+[4]: https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits

docs/ARCHITECTURE.md

@@ -0,0 +1,86 @@
+# Architecture
+
+Describes architecture patterns with examples — detailed component documentation lives as JSDoc on the files themselves.
+
+## Package dependencies
+
+The [monorepo](https://github.com/DataDog/browser-sdk) contains several packages:
+
+```mermaid
+graph TD
+  core["@datadog/browser-core\n(shared utilities)"]
+  rum-core["@datadog/browser-rum-core\n(core RUM)"]
+  rum["@datadog/browser-rum\n(full RUM)"]
+  rum-slim["@datadog/browser-rum-slim\n(lightweight RUM)"]
+  rum-react["@datadog/browser-rum-react\n(React integration)"]
+  logs["@datadog/browser-logs"]
+  worker["@datadog/browser-worker"]
+
+  core --> rum-core
+  core --> logs
+  rum-core --> rum
+  rum-core --> rum-slim
+  rum --> rum-react
+```
+
+## Data processing
+
+High-level view of RUM SDK data processing. Each box represents a module:
+
+```mermaid
+flowchart TD
+  startRum["startRum\n(boot)"]
+  collections["collections\n(views, actions, resources, errors…)"]
+  assembly["assembly\n(adds common attributes)"]
+  batch["batch\n(in-memory buffer)"]
+
+  startRum --> collections
+  collections -->|"raw RUM events"| assembly
+  assembly -->|"enriched events"| batch
+```
+
+### startRum [[code](https://github.com/DataDog/browser-sdk/blob/32ffe4bb7e50a37a43794773bbbc57aabb373468/packages/rum-core/src/boot/startRum.ts)]
+
+Called at SDK initialization. Starts all event data collection.
+
+### collection [[code](https://github.com/DataDog/browser-sdk/blob/32ffe4bb7e50a37a43794773bbbc57aabb373468/packages/rum-core/src/domain/rumEventsCollection/error/errorCollection.ts)]
+
+Creates raw RUM events (`views`, `actions`, `resources`, …) by listening to or instrumenting various web APIs, then notifies the assembly.
+
+### assembly [[code](https://github.com/DataDog/browser-sdk/blob/32ffe4bb7e50a37a43794773bbbc57aabb373468/packages/rum-core/src/domain/assembly.ts)]
+
+Enriches each event with common attributes (`applicationId`, `service`, `version`, view context, customer context, …) then forwards it to the batch.
+
+## Data transfer
+
+```mermaid
+flowchart TD
+  batch["batch\n(in-memory buffer)"]
+  httpRetry["httpRetry\n(retry & throttle)"]
+  httpRequest["httpRequest\n(fetch / XHR)"]
+  intake["Datadog intake"]
+
+  batch -->|"flush"| httpRetry
+  httpRetry -->|"send"| httpRequest
+  httpRequest --> intake
+```
+
+### batch [[code](https://github.com/DataDog/browser-sdk/blob/32ffe4bb7e50a37a43794773bbbc57aabb373468/packages/core/src/transport/batch.ts)]
+
+Collects events into an in-memory batch. Flushed:
+
+- Periodically, every `configuration.flushTimeout` (30s by default)
+- When the buffer size reaches `configuration.batchBytesLimit`
+- When the number of events reaches `configuration.maxBatchSize`
+- On `visibilitychange` when the document becomes hidden
+- On `beforeunload`
+
+### httpRetry
+
+Buffers and retries failed requests (`network failure`, `intake unavailable`, `no connectivity`, …). Also throttles requests when too many are in progress.
+
+The SDK buffers at most 3MB of requests; older requests are dropped beyond that limit. The buffer is in-memory — requests are lost if the tab is closed.
+
+### httpRequest [[code](https://github.com/DataDog/browser-sdk/blob/32ffe4bb7e50a37a43794773bbbc57aabb373468/packages/core/src/transport/httpRequest.ts)]
+
+Sends events using `fetch` with `keepAlive`, falling back to `XMLHttpRequest`.