Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• src/index.ts
• src/modules/ConsentManager.ts
• src/modules/DOMConnector.ts
• src/modules/GrantsInterface.ts
• src/bundle.ts
• package.json
• README.md

The consent-manager project is a modular, privacy-focused cookie consent management solution. Its architecture is designed for flexibility, allowing developers to use only the components they need. The system is centered around a core ConsentManager class that handles state and logic, which can be extended with optional modules for DOM manipulation (DOMConnector) and user interface elements (GrantsInterface).

The architecture is event-driven. The core ConsentManager dispatches events when consent grants are updated. Other modules, like DOMConnector and GrantsInterface, listen for these events to reactively update the page content and UI components. This decoupled approach ensures that the core logic is independent of its presentation or side effects.

Core Components

The system is composed of three primary classes, each with a distinct responsibility. They are designed to work together but can be used independently depending on the project's needs.

This diagram illustrates the relationship between the main components. ConsentManager is the central hub, with DOMConnector and GrantsInterface acting as clients that consume its state and events.

ConsentManager

This is the core class and the brain of the system. It is responsible for managing the consent state, persisting it to a browser cookie, and providing an event-driven API for other parts of the application to interact with.

Key Responsibilities

• Configuration: Initializes with a user-defined configuration specifying categories, cookie name, expiration, and version.
• State Management: Maintains the current consent grants in the grants property.
• Cookie Persistence: Reads from and writes consent status to a browser cookie using the js-cookie library. It validates the cookie's structure and version upon initialization.
• Event Emitter: Implements an event system (on, off, dispatch) to notify listeners of changes. Supported events are update, grant, and revoke.

Class Structure

Initialization Flow

On instantiation, ConsentManager merges the user-provided config with defaults, then attempts to parse an existing consent cookie. If a valid cookie matching the current version is found, its grants are loaded, and isCustomized is set to true. Otherwise, it falls back to the default grants defined in the configuration.

DOMConnector

This module connects the ConsentManager's state to the browser's DOM. It allows for declarative, conditional rendering of elements or modification of attributes based on the user's consent choices, using data-* attributes.

Key Responsibilities

• DOM Scanning: Scans the DOM for elements with the data-consent-manager attribute.
• Attribute-based Logic: Modifies element attributes based on a set of data-cm-* attributes.
• Reactive Updates: Listens for the update event from ConsentManager and re-evaluates the DOM to apply or remove attributes as consent changes.

Data Attributes

Attribute	Description	Example
data-consent-manager	Marks an element to be processed by DOMConnector.	<script data-consent-manager ...>
data-cm-categories	A comma-separated list of category IDs. The element is "enabled" if consent is granted for at least one category.	data-cm-categories="analytics,marketing"
data-cm-attribute	The name of the attribute to set on the element when it is enabled.	data-cm-attribute="src"
data-cm-value	The value to be assigned to the attribute specified by data-cm-attribute.	data-cm-value="https://analytics.js"
data-cm-inverted	Inverts the logic, enabling the element when consent is not granted for the specified categories.	<p data-cm-inverted ...>

Sources: src/modules/DOMConnector.ts:8-28, README.md:123-143

GrantsInterface

This module provides ready-to-use UI components for managing consent: a cookie banner and a preferences modal. It is highly configurable, allowing for custom text strings and manual control over its visibility.

Key Responsibilities

• UI Generation: Dynamically creates and injects a cookie banner and a preferences modal into the DOM.
• User Interaction: Handles button clicks (Accept All, Only required, More options) and updates the ConsentManager state by calling setGrant().
• Automatic Display: By default, it shows the banner if the user has not yet customized their preferences (isCustomized is false). This can be disabled via the autoShow: false config option.
• Customization: Allows overriding default UI text through the languageStrings configuration object.

The following diagram shows the sequence of events when a user interacts with the UI to provide consent.

Data Structures

ConsentManagerConfig

This interface defines the shape of the configuration object passed to the ConsentManager constructor.

Property	Type	Required	Default	Description
version	string	Yes	1	Version of the config. A change invalidates existing user consents.
cookieName	string	No	consent-manager	The name of the cookie used for storage.
expires	number | Date | 'session'	No	365	Cookie expiration in days, a specific Date, or 'session'.
categories	Array<object>	Yes	[]	An array of consent category objects.

Sources: src/modules/ConsentManager.ts:49-61, 63-68

Cookie Data Structure

The consent data is stored in a cookie as a JSON string. The validateCookie function ensures the integrity of this data before it is used.

interface CookieData {
  version: string;
  grants: Record<string, boolean>;
}

Sources: src/modules/ConsentManager.ts:7-38, 44-47

Module System and Bundling

The project is structured to support multiple consumption methods.

1. ESM/CJS Module: The src/index.ts file serves as the main entry point for bundlers like Webpack or Rollup. It exports the ConsentManager class as the default export and the other classes as named exports.
   Sources: src/index.ts:1-5

2. Browser Bundle: The src/bundle.ts file is used to create a bundle for direct inclusion in a browser via a <script> tag. It attaches the ConsentManager, DOMConnector, and GrantsInterface classes to the global window object.
   Sources: src/bundle.ts:1-7

The build process is defined in package.json and uses tsc to compile TypeScript for Node.js environments and esbuild to create the browser bundles (consent-manager.js and consent-manager.min.js).
Sources: package.json:29-35

Conclusion

The consent-manager architecture is a well-defined, decoupled system that separates concerns effectively. The ConsentManager class provides the core state management and persistence logic. The DOMConnector and GrantsInterface modules build upon this core, offering powerful, declarative ways to integrate consent management into a web application's DOM and user interface. The event-driven nature of the communication between components ensures that the system is both efficient and extensible.