# barbajs/barba architecture

> Architecture diagram of the GitHub repository barbajs/barba, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/barbajs/barba
- Repository: https://github.com/barbajs/barba

## Overview

##### Project Type & Purpose
- This is an open-source, monorepo JavaScript/TypeScript library (Barba.js) managed with Lerna.
- Its purpose is to provide a core engine for page-transition management in websites (SPA-like behavior) and expose an extensible plugin system (css, prefetch, router).

##### High-Level Architectural Components
A. Monorepo Root
- Lerna orchestrator (lerna.json)
- CI/CD (CircleCI config)
- Linters & formatters (.eslintrc.js, prettier.config.js, tsconfig.json)
- Documentation site (documentation/ with Handlebars theme)
- Test runners (jest.config.js, cypress.config.ts)
B. Core Package (packages/core)
- Core engine entry (src/index.ts, src/core.ts)
- Modules folder (Cache, Error, Headers, Ignore, Logger, Prevent, Store, Transitions, Views)
- Hook system & lifecycle definitions (src/defs, src/hooks.ts)
- Utilities & polyfills (src/utils, src/polyfills)
- Examples (packages/core/__web__)
- Tests: unit (__tests__), integration (__e2e__)
C. Plugin Packages
1. CSS Plugin (packages/css)
- Extends core with CSS state & prefixing APIs
- src/css.ts and defs
- Examples (__web__)
- Tests (__tests__, __e2e__)
2. Prefetch Plugin (packages/prefetch)
- Adds idle‐time prefetching capabilities
- src/prefetch.ts, polyfills
3. Router Plugin (packages/router)
- Exposes routing logic to navigate and intercept links
- src/router.ts, defs
D. External Ecosystem
- npm registry (package.json publishing)
- Consumers’ websites (user code integrates with Barba API)
- Browser environment (DOM, history API)

##### Relationships & Data Flows
- Modules process events, manipulate DOM, manage state, handle errors, etc. (intra-core flow).
- Tests and examples instantiate Core+plugins in an isolated environment (Cypress or Jest).
- CI/CD pipelines run linters, unit tests, E2E tests, and on success publish packages via Lerna.

##### Architectural Patterns & Principles
- Monorepo with Lerna for multi‐package management.
- Plugin architecture: core engine + opt-in extensions.
- Event‐driven & hook system for lifecycle management.
- Progressive enhancement: polyfills directory.
- Separation of concerns: modules encapsulate cache, error handling, view management.
- Test pyramid: unit tests → integration/E2E tests.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Tooling
    subgraph "Monorepo Tooling" 
        direction TB
        LERNA["lerna.json"]:::tooling
        CIRCLECI["CircleCI config"]:::tooling
        ESLINT[".eslintrc.js"]:::tooling
        PRETTIER["prettier.config.js"]:::tooling
        TSCONFIG["tsconfig.json"]:::tooling
        JESTCFG["jest.config.js"]:::tooling
        CYPRESSCFG["cypress.config.ts"]:::tooling
        LERNA -->|orchestrates| CI[("CI Pipeline")]:::tooling
        CI -->|runs linters/tests| Publish["Publish via Lerna"]:::tooling
    end

    %% Documentation Site
    subgraph "Documentation Site" 
        direction TB
        DOCS["documentation/"]:::docs
    end

    %% Core Engine
    subgraph "Core Engine" 
        direction TB
        Core["Core Engine"]:::core
        subgraph "Modules" 
            direction TB
            Cache["Cache"]:::core
            Error["Error"]:::core
            Headers["Headers"]:::core
            Ignore["Ignore"]:::core
            Logger["Logger"]:::core
            Prevent["Prevent"]:::core
            Store["Store"]:::core
            Transitions["Transitions"]:::core
            Views["Views"]:::core
        end
        Core -->|dispatches events| Cache
        Core -->|dispatches events| Error
        Core -->|dispatches events| Headers
        Core -->|dispatches events| Ignore
        Core -->|dispatches events| Logger
        Core -->|dispatches events| Prevent
        Core -->|dispatches events| Store
        Core -->|dispatches events| Transitions
        Core -->|dispatches events| Views
    end

    %% Plugins
    subgraph "CSS Plugin" 
        direction TB
        CSSImpl["css.ts / index.ts"]:::plugin
        CSSDefs["defs"]:::plugin
        CSSImpl -->|extends| Core
    end

    subgraph "Prefetch Plugin" 
        direction TB
        PrefetchImpl["prefetch.ts / index.ts"]:::plugin
        PrefetchDefs["defs"]:::plugin
        PrefetchPoly["polyfills"]:::plugin
        PrefetchImpl -->|extends| Core
    end

    subgraph "Router Plugin" 
        direction TB
        RouterImpl["router.ts / index.ts"]:::plugin
        RouterDefs["defs"]:::plugin
        RouterImpl -->|extends| Core
    end

    %% Tests & Examples
    subgraph "Examples & Tests" 
        direction TB
        CoreWeb["core/__web__"]:::examples
        CoreUnit["core/__tests__"]:::tests
        CoreE2E["core/__e2e__"]:::tests
        CSSWeb["css/__web__"]:::examples
        CSSUnit["css/__tests__"]:::tests
        CSSE2E["css/__e2e__"]:::tests
        PrefetchWeb["prefetch/__web__"]:::examples
        PrefetchUnit["prefetch/__tests__"]:::tests
        PrefetchE2E["prefetch/__e2e__"]:::tests
        RouterWeb["router/__web__"]:::examples
        RouterUnit["router/__tests__"]:::tests
        RouterE2E["router/__e2e__"]:::tests
        CoreWeb -->|instantiates| Core
        CoreUnit -->|tests| Core
        CoreE2E -->|tests| Core
        CSSWeb -->|instantiates| Core
        CSSUnit -->|tests| CSSImpl
        CSSE2E -->|tests| CSSImpl
        PrefetchWeb -->|instantiates| Core
        PrefetchUnit -->|tests| PrefetchImpl
        PrefetchE2E -->|tests| PrefetchImpl
        RouterWeb -->|instantiates| Core
        RouterUnit -->|tests| RouterImpl
        RouterE2E -->|tests| RouterImpl
    end

    %% External Entities
    User["External Consumers\n(user websites)"]:::external
    NPM["npm registry"]:::external
    Browser["Browser Environment"]:::external
    User -->|uses API/hooks| Core
    Browser -->|fires events| Core
    Publish -->|publishes| NPM

    %% Click Events
    click LERNA "https://github.com/barbajs/barba/blob/main//lerna.json"
    click CIRCLECI "https://github.com/barbajs/barba/blob/main//.circleci/config.yml"
    click ESLINT "https://github.com/barbajs/barba/blob/main//.eslintrc.js"
    click PRETTIER "https://github.com/barbajs/barba/blob/main//prettier.config.js"
    click TSCONFIG "https://github.com/barbajs/barba/blob/main//tsconfig.json"
    click JESTCFG "https://github.com/barbajs/barba/blob/main//jest.config.js"
    click CYPRESSCFG "https://github.com/barbajs/barba/blob/main//cypress.config.ts"
    click DOCS "https://github.com/barbajs/barba/tree/main//documentation"
    click Core "https://github.com/barbajs/barba/blob/main//packages/core/src/index.ts"
    click Core "https://github.com/barbajs/barba/blob/main//packages/core/src/core.ts"
    click CoreWeb "https://github.com/barbajs/barba/tree/main//packages/core/__web__"
    click CoreUnit "https://github.com/barbajs/barba/tree/main//packages/core/__tests__"
    click CoreE2E "https://github.com/barbajs/barba/tree/main//packages/core/__e2e__"
    click CSSImpl "https://github.com/barbajs/barba/blob/main//packages/css/src/css.ts"
    click CSSImpl "https://github.com/barbajs/barba/blob/main//packages/css/src/index.ts"
    click CSSDefs "https://github.com/barbajs/barba/tree/main//packages/css/src/defs"
    click CSSWeb "https://github.com/barbajs/barba/tree/main//packages/css/__web__"
    click CSSUnit "https://github.com/barbajs/barba/tree/main//packages/css/__tests__"
    click CSSE2E "https://github.com/barbajs/barba/tree/main//packages/css/__e2e__"
    click PrefetchImpl "https://github.com/barbajs/barba/blob/main//packages/prefetch/src/prefetch.ts"
    click PrefetchImpl "https://github.com/barbajs/barba/blob/main//packages/prefetch/src/index.ts"
    click PrefetchDefs "https://github.com/barbajs/barba/tree/main//packages/prefetch/src/defs"
    click PrefetchPoly "https://github.com/barbajs/barba/tree/main//packages/prefetch/src/polyfills"
    click PrefetchWeb "https://github.com/barbajs/barba/tree/main//packages/prefetch/__web__"
    click PrefetchUnit "https://github.com/barbajs/barba/tree/main//packages/prefetch/__tests__"
    click PrefetchE2E "https://github.com/barbajs/barba/tree/main//packages/prefetch/__e2e__"
    click RouterImpl "https://github.com/barbajs/barba/blob/main//packages/router/src/router.ts"
    click RouterImpl "https://github.com/barbajs/barba/blob/main//packages/router/src/index.ts"
    click RouterDefs "https://github.com/barbajs/barba/tree/main//packages/router/src/defs"
    click RouterWeb "https://github.com/barbajs/barba/tree/main//packages/router/__web__"
    click RouterUnit "https://github.com/barbajs/barba/tree/main//packages/router/__tests__"
    click RouterE2E "https://github.com/barbajs/barba/tree/main//packages/router/__e2e__"

    %% Styles
    classDef core fill:#cce5ff,stroke:#0062cc,stroke-width:1px
    classDef plugin fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef tooling fill:#ffeeba,stroke:#856404,stroke-width:1px
    classDef docs fill:#e2d4f0,stroke:#5e35b1,stroke-width:1px
    classDef examples fill:#f0e6f6,stroke:#6a1b9a,stroke-width:1px
    classDef tests fill:#f8d7da,stroke:#721c24,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
```
