Add architecture documentation

README.md

@@ -35,3 +35,4 @@ This library is one of Segment’s most popular Flagship libraries. It is active
 
 - Contribution guidelines: [CONTRIBUTING.md](CONTRIBUTING.md)
 - Development instructions: [DEVELOPMENT.md](DEVELOPMENT.md)
+- Releasing (to npm): [RELEASING.md](RELEASING.md)

packages/browser/README.md

@@ -7,7 +7,7 @@ Analytics Next (aka Analytics 2.0) is the latest version of Segment’s JavaScri
 - [🏎️ Quickstart](#-quickstart)
   - [💡 Using with Segment](#-using-with-segment)
   - [💻 Using as an `npm` package](#-using-as-an-npm-package)
-- [🔌 Plugins](#-plugins)
+- [🔌 Architecture](#-architecture--plugins)
 - [🐒 Development](#-development)
 
 ---
@@ -187,6 +187,8 @@ declare global {
 }
 ```
 
+##  🔌 Architecture & Plugins
+- See [ARCHITECTURE.md](architecture/ARCHITECTURE.md)
 
 ## 🐒 Development
 
@@ -207,56 +209,5 @@ Then, make your changes and test them out in the test app!
 
 <img src="https://user-images.githubusercontent.com/2866515/135407053-7561d522-b969-484d-8d3a-6f1c4d9c025b.gif" alt="Example of the development app" width="500px">
 
-# 🔌 Plugins
-
-When developing against Analytics Next you will likely be writing plugins, which can augment functionality and enrich data. Plugins are isolated chunks which you can build, test, version, and deploy independently of the rest of the codebase. Plugins are bounded by Analytics Next which handles things such as observability, retries, and error management.
-
-Plugins can be of two different priorities:
-
-1. **Critical**: Analytics Next should expect this plugin to be loaded before starting event delivery
-2. **Non-critical**: Analytics Next can start event delivery before this plugin has finished loading
-
-and can be of five different types:
-
-1. **Before**: Plugins that need to be run before any other plugins are run. An example of this would be validating events before passing them along to other plugins.
-2. **After**: Plugins that need to run after all other plugins have run. An example of this is the segment.io integration, which will wait for destinations to succeed or fail so that it can send its observability metrics.
-3. **Destination**: Destinations to send the event to (ie. legacy destinations). Does not modify the event and failure does not halt execution.
-4. **Enrichment**: Modifies an event, failure here could halt the event pipeline.
-5. **Utility**: Plugins that change Analytics Next functionality and don't fall into the other categories.
-
-Here is an example of a simple plugin that would convert all track events event names to lowercase before the event gets sent through the rest of the pipeline:
-
-```ts
-import type { Plugin } from '@segment/analytics-next'
-
-export const lowercase: Plugin = {
-  name: 'Lowercase Event Name',
-  type: 'before',
-  version: '1.0.0',
-
-  isLoaded: () => true,
-  load: () => Promise.resolve(),
-
-  track: (ctx) => {
-    ctx.event.event = ctx.event.event.toLowerCase()
-    return ctx
-  }
-}
-
-analytics.register(lowercase)
-```
-
-For further examples check out our [existing plugins](/packages/browser/src/plugins).
-
-## 🧪 QA
-Feature work and bug fixes should include tests. Run all [Jest](https://jestjs.io) tests:
-```
-$ yarn test
-```
-Lint all with [ESLint](https://github.com/typescript-eslint/typescript-eslint/):
-```
-$ yarn lint
-```
-
 
 

packages/browser/architecture/ARCHITECTURE.md

@@ -0,0 +1,222 @@
+## Analytics.js Plugin Architecture
+
+> [!IMPORTANT]
+> This doc may get out-of-date. Please prefer to use and link to Segment documentation for the most up-to-date information. It would be advisable to move this doc to https://segment.com/docs/connections/sources/catalog/libraries/website/javascript, so there is a single source of truth.
+
+
+### You can use the [vscode mermaid extension](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) to preview the following diagram code block inside of vscode, or copy and paste into the [mermaid live editor](https://mermaid.live/).
+
+## Table of Contents
+- [Initialization Flow](#initialization-flow)
+- [Plugin Types and Middleware](#plugin-types-and-middleware)
+
+
+### Analytics.js Initialization Flow
+The following diagram illustrates how Analytics.js bootstraps and initializes:
+
+```mermaid
+graph TD
+    subgraph Load Phase
+        Start([Web Page Load]) --> LoadAJS[Fetch analytics.js<br/>from CDN]
+        LoadAJS --> InitAJS[analytics.load<br/>with writeKey]
+        InitAJS --> FetchSettings[Fetch settings<br/>from cdn.segment.io]
+    end
+
+    subgraph Plugin Registration Phase
+        FetchSettings --> RegisterCore[Register Core Plugins<br/>and Middleware]
+        RegisterCore --> ParseDest[Parse Device Mode<br/>Destinations]
+    end
+
+    subgraph Destination Loading Phase
+        ParseDest --> LoadDests{Load Device Mode<br/>Destinations}
+        LoadDests -->|Async| Dest1[Load Destination 1<br/>+ Scripts]
+        LoadDests -->|Async| Dest2[Load Destination 2<br/>+ Scripts]
+        LoadDests -->|Async| DestN[Load Destination N<br/>+ Scripts]
+    end
+
+    subgraph Event Processing Phase
+        Dest1 --> Ready1[Destination 1<br/>Ready]
+        Dest2 --> Ready2[Destination 2<br/>Ready]
+        DestN --> ReadyN[Destination N<br/>Ready]
+
+        Ready1 --> Flush1[Flush Events to<br/>Destination 1]
+        Ready2 --> Flush2[Flush Events to<br/>Destination 2]
+        ReadyN --> FlushN[Flush Events to<br/>Destination N]
+    end
+
+    RegisterCore -.->|Events Blocked<br/>Until Complete| ParseDest
+    LoadDests -.->|Critical Plugins<br/>Block Events| EventReady[Event Pipeline Ready]
+
+
+
+    class Dest1,Dest2,DestN,Flush1,Flush2,FlushN async
+```
+
+
+Key Points:
+1. **Load Phase**
+   - Analytics.js is fetched from CDN
+   - Initialized with writeKey that identifies your Segment source
+   - CDN settings are fetched containing destination configurations
+
+2. **Plugin Registration Phase**
+   - Core plugins and middleware are registered synchronously
+   - Event queue is blocked until this phase completes
+   - Device mode destinations are identified from CDN settings
+
+3. **Destination Loading Phase**
+   - Device mode destinations are loaded in parallel
+   - Each destination loads its own third-party scripts
+   - Critical plugins (if any) must complete registration
+
+4. **Event Processing Phase**
+   - Destinations become ready independently
+   - Buffered events are flushed to each destination in parallel
+   - Non-critical destinations can receive events while others are still loading
+
+
+
+### Event Flow 
+```mermaid
+graph TD
+  subgraph Event Creation
+    UserAction[analytics.track/page/identify] --> EventCreate[Event Factory]
+    EventCreate --> Queue[Event Queue]
+  end
+
+  subgraph Plugin Pipeline
+    Queue --> BeforePlugins[Before Plugins e.g add page context]
+    BeforePlugins --> EnrichPlugins[Enrichment Plugins]
+    EnrichPlugins --> DestPlugins[Destination Plugins e.g Segment.io]
+    DestPlugins --> AfterPlugins[After Plugins]
+  end
+
+  subgraph Plugin Types Details
+    BeforeDetails[Before Plugins<br/>Priority: Critical<br/>Example: Event Validation] --- BeforePlugins
+    EnrichDetails[Enrichment Plugins<br/>Priority: Critical<br/>Parallel Execution<br/>Can Modify Events<br/>Example: Add User Agent] --- EnrichPlugins
+    DestDetails[Destination Plugins<br/>Parallel Execution<br/>Cannot Modify Events<br/>Example: Google Analytics] --- DestPlugins
+    AfterDetails[After Plugins<br/>Example: Metrics Collection] --- AfterPlugins
+  end
+
+  subgraph Notes
+    Priorities[Plugin Priorities]
+    Critical[Critical - Must load before<br/>event delivery starts]
+    NonCritical[Non-Critical - Can load<br/>after event delivery starts]
+    Priorities --> Critical
+    Priorities --> NonCritical
+  end
+```
+
+
+### Plugin Types and Middleware
+[This information is also available in the Segment documentation](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/#plugins-and-source-middleware)
+
+- **Source Middleware** (see [Example](#example-source-middleware-implementation))
+  - **Source Middleware is just a light API wrapper around a "Before" type plugin Plugin**
+  - Source Middleware is the legacy API (pre-analytics next). It's less verbose than the full plugin API, but a bit less powerful. It is functionally equivalent to a "Before" type plugin.
+
+- **Before Plugins** (see [Example](#example-plugin-implementation))
+  - Run before any other plugins
+  - Critical priority - block event pipeline until `.load()` resolves
+  - Use cases: Event validation, data transformation
+  - Example: Event validation before passing to other plugins)
+
+
+- **Enrichment Plugins**
+  - Functionally Identitical to "before" plugins, but run after them. Before plugins are typically used internally (e.g adding page info), but there's no hard and fast rule.
+
+- **Destination Plugins**
+  - Run after enrichment
+  - Cannot modify the event
+  - Execute in parallel
+  - Failures do not halt pipeline
+  - Example: Segment.io, Google Analytics, Mixpanel
+
+- **After Plugins (uncommon)**
+  - Run after all other plugins complete
+  - Use cases: Metrics, logging
+  - Example: segment.io plugin for observability metrics
+
+- **Utility Plugins**
+  - Executes only once during the analytics.js bootstrap. Gives you access to the analytics instance using the plugin's load() method. This doesn't allow you to modify events.
+  - Do not directly process events
+  - Example: some plugin that registers a bunch of analytics event listeners (e.g. analytics.on('track', ...) and reports them to an external system)
+
+- **Destination Middleware** (See [Example](#example-destination-middleware-implementation))
+  - A special type of plugin that allows you to add a plugin that only affects a specific (device mode) destination plugin.
+
+
+### Example: Plugin Implementation
+```ts
+analytics.register({
+  name: 'My Plugin',
+  type: 'before',
+  isLoaded: () => true,
+  load: () => Promise.resolve(),
+  // lowercase all track event names
+  track: (ctx) => {
+    ctx.event.event = ctx.event.event.toLowerCase()
+    return ctx
+  },
+  // drop page events with a specific title
+  page: (ctx) => {
+    if (ctx.properties.title === 'some title') {
+      return null 
+    }
+    return ctx
+  }
+})
+``` 
+### Example: Source Middleware Implementation
+```ts
+analytics.addSourceMiddleware(({ payload, next }) => {
+  const { event } = payload.obj.context
+  if (event.type === 'track') {
+    // change the event name to lowercase
+    event.event = event.event.toLowerCase()
+  } else if (event.type === 'page') {
+    // drop any page events with a specific title
+    if (event.properties.title === 'some title') {
+      return null
+    }
+}
+  next(payload) 
+})
+```
+
+### Example: Destination Middleware Implementation
+> [!NOTE]
+> It is not currently possible to add a destination middleware to the Segment.io destination.
+```ts
+analytics.addDestinationMiddleware('amplitude', ({ next, payload }) => {
+  payload.obj.properties!.hello = 'from the other side'
+  next(payload)
+})
+```
+or, to apply to all destinations
+```ts
+analytics.addDestinationMiddleware('*', ({ next, payload }) => {
+ ...
+})
+```
+
+
+### Event Flow Example
+
+When `analytics.track()` is called:
+
+1. Event is created via Event Factory
+2. Event enters the queue
+3. Before plugins run, in order of registration
+3. Enrichment plugins run, in order of registration
+4. Destination plugins receive the event in parallel (including Segment.io plugin)
+5. Any after plugins handle post-processing (e.g. metrics collection)
+
+### Plugin Priorities
+
+- **Critical Plugins**: Must be loaded before event delivery starts
+  - Example: Before plugins, Validation plugins
+- **Non-Critical Plugins**: Can load after event delivery begins
+  - Example: Destination plugins
+
+