# gouvernementfr/dsfr architecture

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

- Interactive diagram: https://gitdiagram.com/gouvernementfr/dsfr
- Repository: https://github.com/gouvernementfr/dsfr

## Overview

##### Main Components
- Core/Source – The heart of the design system lives in the “src” folder. This contains the source Sass, JavaScript, and template files for every DSFR component (buttons, alerts, accordions, forms, etc.).
- Components Library – Located under “src/dsfr/component” (and many subdirectories), this is a modular collection of UI components. Each component directory follows the BEM methodology and includes assets (SCSS, JS, EJS templates, and documentation).
- Distribution (Dist) – The “dist” folder houses the final CSS and JavaScript bundles (the minified files such as dsfr.min.css, dsfr.module.min.js, dsfr.nomodule.min.js) that are consumed by projects integrating the DSFR.
- Documentation & Examples – The README and “example” folders contain HTML snippets and standalone pages for developers to see live examples and understand how to set up their project structure.

##### Relationships and Interactions
- Developer Workflow Flow: Developers work in the “src” directory, creating or modifying Sass, JavaScript, and template code for various UI components. These are then processed by the build tools (from the “tool” folder) to produce the distribution files.
- The Build Pipeline: There is a clear pipeline from “src” to “dist” – tools such as build scripts, asset generators, and concatenation utilities orchestrate this translation while preserving modularity and BEM naming conventions.
- Documentation Linkages: The README, legal documents (in “doc/legal”) and the online documentation site provide context that ensures developers follow prescribed UI and accessibility standards.

##### Architectural Patterns and Design Principles
- Component-Based Architecture: Each UI element is developed and maintained in isolation. This modularity allows independent development, testing, and eventual integration.
- BEM Naming Convention: The use of Block–Element–Modifier in CSS is central to how components are styled and how their relationships are indicated.
- Layered Build Process: The separation between source (development) and distribution (consumable libraries) components is essential. Visualizing the build tools as an intermediary layer helps clarify the transformation pipeline.
- Dual JavaScript Bundling: To support a wide spectrum of browsers, the system provides both an ES6 module version and an older “nomodule” version, highlighting attention to backward compatibility.

##### Relevant Technologies, Frameworks, and Libraries
- Sass (SCSS): For structured, modular styling.
- JavaScript (ES6 modules and legacy scripts): For dynamic functionality.
- NPM and Browser-Sync: For package management and local development server.
- Build Tools and Custom Node Scripts: For processing, concatenation, and asset management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph: Development / Source Code Layer
    subgraph "Development / Source Code"
        CA["Core/Source (SASS, JS, Templates)"]:::dev
        CL["Components Library (UI Components, BEM)"]:::dev
        CU["Core & Utilities (Helpers, Typography)"]:::dev
        AS["Assets (Icons, Fonts, Favicons)"]:::asset
    end

    %% Subgraph: Build Process Layer
    subgraph "Build Process"
        BT["Build/Tool Chain (Scripts & Automation)"]:::build
    end

    %% Subgraph: Distribution Layer
    subgraph "Distribution"
        DS["Distribution (Final CSS & JS Bundles)"]:::dist
    end

    %% Subgraph: Consumption Layer
    subgraph "Consumption"
        CP["Consumer Projects (HTML Integration)"]:::consume
    end

    %% Subgraph: Documentation & Examples Layer
    subgraph "Documentation / Examples"
        DO1["README.md"]:::doc
        DO2["Doc & Storybook Examples"]:::doc
    end

    %% Flow connections
    CA -->|"providesBaseFor"| CL
    CA -->|"providesBaseFor"| CU
    CA -->|"suppliesAssetsTo"| AS

    CL -->|"suppliesComponentsTo"| BT
    CU -->|"suppliesUtilitiesTo"| BT
    AS -->|"integratedAssetsInto"| BT

    BT -->|"buildsInto"| DS
    DS -->|"integratedBy"| CP
    DO1 ---|"guidesUsage"| CP
    DO2 ---|"guidesUsage"| CP

    %% Legend Node
    LEG["Legend:\n• Blue: Development / Source Code\n• Grey: Assets\n• Orange: Build Tools\n• Green: Distribution\n• Peach: Consumption\n• Purple: Documentation & Examples"]
    CP --- LEG

    %% Click Events for mapped components
    click CA "https://github.com/gouvernementfr/dsfr/tree/main/src/dsfr/core"
    click CL "https://github.com/gouvernementfr/dsfr/tree/main/src/dsfr/component"
    click CU "https://github.com/gouvernementfr/dsfr/tree/main/src/dsfr/utility"
    click AS "https://github.com/gouvernementfr/dsfr/tree/main/src/dsfr/core/asset"
    click BT "https://github.com/gouvernementfr/dsfr/tree/main/tool"
    click DO1 "https://github.com/gouvernementfr/dsfr/blob/main/README.md"
    click DO2 "https://github.com/gouvernementfr/dsfr/tree/main/doc"

    %% Styles
    classDef dev fill:#ADD8E6,stroke:#000,stroke-width:2px
    classDef asset fill:#D3D3D3,stroke:#000,stroke-width:2px
    classDef build fill:#FFA07A,stroke:#000,stroke-width:2px
    classDef dist fill:#90EE90,stroke:#000,stroke-width:2px
    classDef consume fill:#FFDEAD,stroke:#000,stroke-width:2px
    classDef doc fill:#DDA0DD,stroke:#000,stroke-width:2px
```
