# sncfdevelopers/wcs architecture

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

- Interactive diagram: https://gitdiagram.com/sncfdevelopers/wcs
- Repository: https://github.com/sncfdevelopers/wcs

## Overview

##### Project Type and Purpose
- This is a monorepo for a Design System: “Web Components SNCF.”
- Built with StencilJS to generate reusable web components (`wcs-core`), plus framework integrations (`wcs-angular`, `wcs-formly`, `wcs-react`), a design-tokens generator, documentation (Storybook), and example apps (Angular & React).

##### File-Structure Analysis
- Top-level:
- src/ + stencil.config.ts → core components source.
- angular/ → Angular library projects (wcs-angular, wcs-formly).
- react/ → React wrapper library.
- design-tokens/ → JSON → CSS/DTF token pipelines and manifest.
- example/ → demo apps in Angular & React.
- stories/ → Storybook configuration & MDX docs.
- scripts/ → build/versioning helpers.
- CI files (.gitlab-ci.yml) & publishing configs (.npmrc, package.json).

##### README Insights
- Core packages published to npm: wcs-core, wcs-angular, wcs-formly, wcs-react.
- StencilJS builds core; wrappers are built by Angular CLI / Rollup.
- Storybook serves as live documentation.
- CI/CD via GitLab pipelines drives build, test, Storybook deploy, and npm publish.

##### Main Components
a. Core Web Components Package (StencilJS)
b. Angular Integration Packages (wcs-angular, wcs-formly)
c. React Integration Package (wcs-react)
d. Design-Tokens Generator (json-to-css, json-to-dtf)
e. Storybook Documentation App
f. Example Applications (Angular Standalone, React)
g. CI/CD Pipeline & NPM Registry
h. Consumers (Client Projects)

##### Relationships and Data Flows
- Developers edit src/, angular/, react/, design-tokens/, then run “npm run build”:
- Stencil builds core → outputs web components bundle.
- Angular CLI builds integrations → packages.
- Rollup compiles React wrappers.
- Design-tokens scripts transform JSON → CSS/DTF.
- Artifacts published to npm registry.
- Storybook reads built core + wrappers + tokens to render component library.
- Example apps install published or local builds of packages to showcase usage.
- CI/CD orchestrates build → test → deploy (Storybook hosting) → npm publish.

##### Architectural Patterns & Design Principles
- Monorepo with multi-package (Package per framework)
- Build pipelines per package: StencilJS for core, Angular CLI for Angular, Rollup for React
- Separation of concerns: core functionality vs. framework adapters vs. tokens vs. docs
- Publish-subscribe: packages published to registry, consumers subscribe via npm

- Core Layer:
[src/] → (Stencil Build) → [wcs-core bundle]
- Integration Layer:
[angular/projects/wcs-angular] → (ng build) → [wcs-angular package]
[angular/projects/wcs-formly] → (ng build) → [wcs-formly package]
[react/lib & rollup.config.mjs] → (rollup) → [wcs-react package]
- Design-Tokens:
[design-tokens/tokens/*.json] → (token-builder.mjs) → CSS/DTF outputs
- Documentation:
[stories/] + built packages → (Storybook) → Live Docs
- Examples:
[example/angular-standalone] & [example/react] install local builds or registry packages → run dev servers
- CI/CD Pipeline:
[.gitlab-ci.yml] → jobs: install → build core + integrations + tokens → test (unit & e2e) → deploy Storybook → npm publish
- Consumers:
Client Applications import `wcs-core` ± integrations via npm

##### Final Checklist
- Components labeled and grouped logically
- External services: GitLab CI, NPM Registry, Browsers
- Technology nodes: StencilJS, Angular CLI, Rollup, Storybook

## Diagram (Mermaid)

```mermaid
graph TB
    %% Core Layer
    subgraph "Core Layer"
        src["src/"]:::core
        stencilConfig["stencil.config.ts"]:::core
        StencilBuild["Stencil Build (StencilJS)"]:::tools
        WCSCoreBundle["wcs-core bundle"]:::core
    end

    %% Integration Layer
    subgraph "Integration Layer"
        WCS_Angular["wcs-angular package"]:::integration
        WCS_Formly["wcs-formly package"]:::integration
        WCS_React["wcs-react package"]:::integration

        AngularSrc1["angular/projects/wcs-angular"]:::integration
        AngularSrc2["angular/projects/wcs-formly"]:::integration
        ReactSrc["react/"]:::integration
        ReactRollup["rollup.config.mjs"]:::integration
        ReactLib["react/lib/"]:::integration

        AngularBuild1["ng build (Angular CLI)"]:::tools
        AngularBuild2["ng build (Angular CLI)"]:::tools
        ReactBuild["Rollup Build"]:::tools
    end

    %% Design-Tokens Layer
    subgraph "Design-Tokens Generator"
        TokensDir["design-tokens/"]:::tools
        TokenBuilder["token-builder.mjs"]:::tools
        TokenIndex["index.mjs"]:::tools
        TokenManifest["manifest.mjs"]:::tools
        TokenOutput["CSS/DTF outputs"]:::tools
    end

    %% Documentation
    subgraph "Documentation"
        StorybookConf[".storybook/"]:::docs
        Stories["stories/"]:::docs
        StorybookApp["Storybook Live Docs"]:::docs
    end

    %% Examples
    subgraph "Example Applications"
        ExAng["Angular Standalone App"]:::docs
        ExReact["React App"]:::docs
    end

    %% CI/CD and Registry
    subgraph "CI/CD & Publishing"
        CI["GitLab CI/CD"]:::ci
        CICfg[".gitlab-ci.yml"]:::ci
        NpmRC[".npmrc"]:::ci
        PackageJson["package.json"]:::ci
        NpmRegistry["NPM Registry"]:::external
    end

    Consumers["Client Projects"]:::external

    %% Flows
    src -->|uses| StencilBuild
    stencilConfig -->|configures| StencilBuild
    StencilBuild -->|outputs| WCSCoreBundle

    AngularSrc1 -->|uses| AngularBuild1
    AngularBuild1 -->|outputs| WCS_Angular

    AngularSrc2 -->|uses| AngularBuild2
    AngularBuild2 -->|outputs| WCS_Formly

    ReactSrc -->|inputs| ReactBuild
    ReactRollup -->|configures| ReactBuild
    ReactLib -->|sources| ReactBuild
    ReactBuild -->|outputs| WCS_React

    TokensDir -->|reads| TokenBuilder
    TokenIndex -->|imports| TokenBuilder
    TokenManifest -->|imports| TokenBuilder
    TokenBuilder -->|generates| TokenOutput

    WCSCoreBundle -->|feeds| StorybookApp
    WCS_Angular -->|feeds| StorybookApp
    WCS_Formly -->|feeds| StorybookApp
    WCS_React -->|feeds| StorybookApp
    TokenOutput -->|feeds| StorybookApp
    StorybookConf -->|configures| StorybookApp
    Stories -->|docs| StorybookApp

    ExAng -->|installs| WCSCoreBundle
    ExAng -->|installs| WCS_Angular
    ExAng -->|installs| TokenOutput

    ExReact -->|installs| WCSCoreBundle
    ExReact -->|installs| WCS_React
    ExReact -->|installs| TokenOutput

    CI -->|runs| CICfg
    CI -->|reads| NpmRC
    CI -->|reads| PackageJson
    CI -->|builds| StencilBuild
    CI -->|builds| AngularBuild1
    CI -->|builds| AngularBuild2
    CI -->|builds| ReactBuild
    CI -->|runs| TokenBuilder
    CI -->|tests| WCSCoreBundle
    CI -->|deploys| StorybookApp
    CI -->|publishes| NpmRegistry

    WCSCoreBundle -->|published to| NpmRegistry
    WCS_Angular -->|published to| NpmRegistry
    WCS_Formly -->|published to| NpmRegistry
    WCS_React -->|published to| NpmRegistry
    TokenOutput -->|published to| NpmRegistry

    NpmRegistry -->|serves| ExAng
    NpmRegistry -->|serves| ExReact
    NpmRegistry -->|serves| Consumers

    %% Click Events
    click src "https://github.com/sncfdevelopers/wcs/tree/develop/src/"
    click stencilConfig "https://github.com/sncfdevelopers/wcs/blob/develop/stencil.config.ts"
    click AngularSrc1 "https://github.com/sncfdevelopers/wcs/tree/develop/angular/projects/wcs-angular"
    click AngularSrc2 "https://github.com/sncfdevelopers/wcs/tree/develop/angular/projects/wcs-formly"
    click ReactSrc "https://github.com/sncfdevelopers/wcs/tree/develop/react/"
    click ReactRollup "https://github.com/sncfdevelopers/wcs/blob/develop/react/rollup.config.mjs"
    click ReactLib "https://github.com/sncfdevelopers/wcs/tree/develop/react/lib/"
    click TokensDir "https://github.com/sncfdevelopers/wcs/tree/develop/design-tokens/"
    click TokenBuilder "https://github.com/sncfdevelopers/wcs/blob/develop/design-tokens/token-builder.mjs"
    click TokenIndex "https://github.com/sncfdevelopers/wcs/blob/develop/design-tokens/index.mjs"
    click TokenManifest "https://github.com/sncfdevelopers/wcs/blob/develop/design-tokens/manifest.mjs"
    click StorybookConf "https://github.com/sncfdevelopers/wcs/tree/develop/.storybook/"
    click Stories "https://github.com/sncfdevelopers/wcs/tree/develop/stories/"
    click ExAng "https://github.com/sncfdevelopers/wcs/tree/develop/example/angular-standalone"
    click ExReact "https://github.com/sncfdevelopers/wcs/tree/develop/example/react"
    click CICfg "https://github.com/sncfdevelopers/wcs/blob/develop/.gitlab-ci.yml"
    click NpmRC "https://github.com/sncfdevelopers/wcs/blob/develop/.npmrc"
    click PackageJson "https://github.com/sncfdevelopers/wcs/blob/develop/package.json"

    %% Styles
    classDef core fill:#B3D4FC,stroke:#333,stroke-width:1px
    classDef integration fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef tools fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef docs fill:#D1C4E9,stroke:#333,stroke-width:1px
    classDef ci fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef external fill:#FFF9C4,stroke:#333,stroke-width:1px
```
