# datawrapper/frontend architecture

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

- Interactive diagram: https://gitdiagram.com/datawrapper/frontend
- Repository: https://github.com/datawrapper/frontend

## Overview

##### Project type and purpose
- This is the Datawrapper Frontend service: a Node.js/Hapi-based full-stack “frontend” application that performs server-side rendering (SSR) of Svelte views, hydrates them client-side, serves static assets, and exposes a plugin system and localization pipeline.

##### File structure
- Top-level directories and files:
- locale/ (translation JSONs)
- src/auth/ (Hapi cookie-session adapter)
- src/routes/ (route handlers/controllers)
- src/utils/ (plugin loader, Svelte-view adapter, event hooks, caching)
- src/views/ (Svelte and Pug templates, layouts, partials)
- src/styles/ (SCSS for static CSS build)
- static/ (precompiled CSS, JS, fonts)
- package.json, nodemon.json, Husky hooks, ESLint config
- Key patterns:
- MVC-style routing (routes → handlers → views)
- Plugin-based extensibility via Hapi plugins + event hooks
- SSR + CSR compilation of Svelte (with cache)
- Localization via locale JSONs pulled from Lokalise

##### README for additional insights
- Middleware: authentication adapter, Svelte-view engine with compile-and-cache strategy, view pre-compilation on startup
- Plugin model: server.register(frontend.cjs), symlinking plugin Svelte views into src/views/plugins
- Event hooks for extending admin navigation
- Global Svelte stores exposed via Hapi view context (e.g. user info, messages)

##### Main components
- Client Browser
- Requests pages, assets, hydration bundles
- Hapi Frontend Service
- Authentication Adapter (src/auth)
- Route Controllers (src/routes)
- Plugin Loader & Event Hook Manager (src/utils/plugin-loader, events.js)
- Svelte-View Engine (src/utils/svelte-view)
‣ Template Compiler (SSR & CSR bundling via Rollup)
‣ Cache Layer (Map cache, optional Redis)
‣ View Pre-processor (prepareView)
‣ Global Store Context Injector
- Localization Module (loads locale/*.json, exposes messages store)
- Static File Server (serves static/ assets and /lib/csr bundles)
- External Services
- Datawrapper API (for data, chart definitions, user info)
- Lokalise API (for updating locale files)

##### Relationships and interactions
- Browser → Hapi Server: HTTP GET/POST → server.route handlers
- Handlers → Auth Adapter: validate session, attach user context
- Handlers → Plugin-registered routes and event hooks
- Handlers → Svelte-View Engine: SSR render of .svelte or .pug view with props + stores
- Svelte-View Engine ↔ Cache Layer: compile or retrieve compiled templates
- SSR Response → Browser: initial HTML + JSON for hydration
- Browser → Static File Server: load CSS, fonts, CSR bundles (/lib/csr/*.js)
- Browser CSR bundle → Hydrate SSR markup, connect to Svelte stores
- Hapi Server ↔ Datawrapper API: fetch chart/user data for rendering
- Hapi Server ↔ Lokalise API: update translations (development only)

##### Architectural patterns and design principles
- Separation of concerns: authentication, routing, view rendering, caching, localization
- Plugin architecture: Hapi plugins + event hooks for modular extensions
- SSR + CSR hydration for Svelte components with IE11 fallback detection
- Pre-compilation strategy to avoid runtime compile spikes
- Global state management via Svelte stores injected into view context
- Use of SCSS pipeline for styling, static asset hosting

##### Detail without overthinking
- Every major directory as a logical component
- Both the SSR path and CSR hydration path separately
- Event hook and plugin extension points explicitly
- Configuration entry points: server.js and plugin registration in src/utils/plugin-loader

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Browser["Client Browser"]:::external

    %% External Services
    DWAPI["Datawrapper API"]:::external
    Lokalise["Lokalise API"]:::external

    %% Datastores
    CacheLayer[(Cache Layer)]:::datastore
    LocaleFiles[(Locale JSON Files)]:::datastore

    %% Hapi Frontend Service Boundary
    subgraph "Hapi Frontend Service"
        direction TB
        Server["Hapi Server\n(src/server.js)"]:::service
        Auth["Authentication Adapter\n(src/auth/dw-auth.js)"]:::module
        Routes["Route Controllers\n(src/routes/)"]:::module
        PL["Plugin Loader\n(src/utils/plugin-loader.js)"]:::module
        EH["Event Hook Manager\n(src/utils/events.js)"]:::module
        subgraph "Svelte-View Engine"
            direction TB
            Engine["Engine Entry\n(src/utils/svelte-view/index.js)"]:::module
            ViewComp["View.svelte Wrapper\n(src/utils/svelte-view/View.svelte)"]:::module
            TemplateEJS["Template Adapter\n(src/utils/svelte-view/template.ejs)"]:::module
            Rollup["Rollup Runtime\n(src/utils/svelte-view/rollup-runtime.js)"]:::module
            CacheJS["Cache Layer\n(src/utils/svelte-view/cache.js)"]:::module
            Context["Global Store Injector\n(src/utils/svelte-view/context.js)"]:::module
        end
        Localization["Localization Module\n(locale/)"]:::module
        StaticFS["Static File Server\n(static/)"]:::module
    end

    %% Browser to Server
    Browser -->|"1. HTTP Request"| Server
    Server -->|"2. Auth Validate"| Auth
    Server -->|"3. Route Handler"| Routes
    Routes -->|registers| PL
    PL -->|initialize hooks| EH
    Routes -->|"4. Render View"| Engine
    Engine -->|compile or retrieve| CacheJS
    Engine -->|uses| Rollup
    Engine -->|wraps view| ViewComp
    Engine -->|apply template| TemplateEJS
    Engine -->|inject stores| Context
    Engine -->|"load messages"| Localization
    Localization -->|reads| LocaleFiles
    Engine -->|"SSR Response"| Server
    Server -->|respond HTML| Browser
    Browser -->|"5. Load Assets"| StaticFS
    Browser -->|"6. Hydrate CSR"| StaticFS
    Server -->|"fetch data"| DWAPI
    Server -->|"update locales"| Lokalise

    %% Click Events
    click Server "https://github.com/datawrapper/frontend/blob/master/src/server.js"
    click Auth "https://github.com/datawrapper/frontend/blob/master/src/auth/dw-auth.js"
    click Routes "https://github.com/datawrapper/frontend/tree/master/src/routes/"
    click PL "https://github.com/datawrapper/frontend/blob/master/src/utils/plugin-loader.js"
    click EH "https://github.com/datawrapper/frontend/blob/master/src/utils/events.js"
    click Engine "https://github.com/datawrapper/frontend/blob/master/src/utils/svelte-view/index.js"
    click ViewComp "https://github.com/datawrapper/frontend/blob/master/src/utils/svelte-view/View.svelte"
    click TemplateEJS "https://github.com/datawrapper/frontend/blob/master/src/utils/svelte-view/template.ejs"
    click Rollup "https://github.com/datawrapper/frontend/blob/master/src/utils/svelte-view/rollup-runtime.js"
    click CacheJS "https://github.com/datawrapper/frontend/blob/master/src/utils/svelte-view/cache.js"
    click Context "https://github.com/datawrapper/frontend/blob/master/src/utils/svelte-view/context.js"
    click Localization "https://github.com/datawrapper/frontend/tree/master/locale/"
    click StaticFS "https://github.com/datawrapper/frontend/tree/master/static/"

    %% Styles
    classDef service fill:#D6EAF8,stroke:#5DADE2,stroke-width:2px,rx:5px,ry:5px
    classDef module fill:#EBF5FB,stroke:#AED6F1,stroke-width:1px
    classDef external fill:#F2F3F4,stroke:#CCD1D1,stroke-width:1px,stroke-dasharray: 2 2
    classDef datastore fill:#E9F7EF,stroke:#58D68D,stroke-width:1px,shape:cylinder
    classDef plugin stroke-dasharray: 5 5,fill:none,stroke:#7D3C98,stroke-width:1px
```
