# migrationsverket/midas architecture

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

- Interactive diagram: https://gitdiagram.com/migrationsverket/midas
- Repository: https://github.com/migrationsverket/midas

## Overview

##### Project Type & Purpose
- This is a monorepo (managed with Nx and Lerna) that houses a React-based design-system (“Midas”), its documentation site, sample/demo apps, playgrounds, E2E test harnesses, and developer tools.
- The core deliverable is a publishable component library (`packages/components`), backed by a Docusaurus-powered docs site (`apps/docs`), plus example integrations (Next.js, Remix, Vite), playgrounds and test suites.

##### File Structure Analysis
- Root: monorepo config (`lerna.json`, `nx.json`), CI workflows (`.github/workflows`), lint/format tooling, and global tsconfigs.
- /packages/components: the component library (source, stories, tests, Storybook config).
- /apps/docs: Docusaurus site with MDX docs, changelog plugin, code examples, i18n, build config.
- /apps/next, /apps/remix, /apps/remix-vite: sample apps showing library integration in Next.js and Remix contexts.
- /apps/playground & /apps/playground-e2e, /apps/next-e2e: developer sandbox and Cypress E2E tests.
- /tools: custom executors, lint plugins, plop generator for code scaffolding.

##### Key README Insights
- Midas is a design system for UX consistency, accessibility, and reusability.
- CI badges show automated component builds, docs generation, Storybook tests, and Chromatic visual testing.

##### Diagramming the Architecture
- Monorepo Root (Nx/Lerna orchestrator)
- Component Library (`packages/components`)
- Documentation Site (`apps/docs`)
- Sample Apps (`apps/next`, `apps/remix`, `apps/remix-vite`)
- Playground (`apps/playground`)
- E2E Test Suites (`apps/next-e2e`, `apps/playground-e2e`)
- Developer Tools (`tools/eslint`, `tools/dependencies`, `tools/stylelint-plugin`, `plopfile.js`)
- CI/CD Pipelines (GitHub Actions workflows, Chromatic)
- External Services: npm registry (publishing), Chromatic, GitHub Pages or hosting for docs.

- Sample Apps & Docs Site → import → Component Library
- Playground → import → Component Library
- E2E Suites → test → Sample Apps / Playground
- CI Pipelines → run → builds/tests → Storybook → publish to Chromatic
- CI Pipelines → build & deploy → Docs Site
- Monorepo Tooling (Nx/Lerna) → orchestrates → build/test/publish tasks
- Developer Tools → integrated into → CI and local dev workflows

c. Architectural Patterns & Principles:
- Monorepo with logical separation: “apps/”, “packages/”, “tools/”
- Library-first approach: components are standalone, versioned, and documented
- Documentation as code: MDX in Docusaurus pulling component metadata and examples
- CI-driven quality: automated linting, unit tests, visual regression, E2E tests
- Pluggable tooling: custom executors and stylelint/plugin for consistent standards

d. Key Technologies & Frameworks:
- Nx & Lerna (monorepo management)
- TypeScript, React, Babel, Vite
- Storybook + Chromatic (component preview & visual testing)
- Docusaurus (docs site)
- Next.js & Remix (sample apps)
- Cypress (E2E)
- ESLint, Stylelint, Prettier, Husky (code quality & hooks)
- GitHub Actions (CI/CD)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Monorepo Orchestrator
    Orchestrator["Monorepo Orchestrator\n(Nx & Lerna)"]:::cicd

    %% Library
    ComponentLibrary["Component Library (Midas)"]:::library

    %% Documentation Site
    DocsSite["Documentation Site (Docusaurus)"]:::apps

    %% Sample Apps
    NextApp["Next.js Sample App"]:::apps
    RemixApp["Remix Sample App"]:::apps
    RemixViteApp["Remix-Vite Sample App"]:::apps

    %% Playground
    PlaygroundApp["Playground App"]:::apps

    %% E2E Test Suites
    NextE2E["Next.js E2E Test Suite"]:::cicd
    PlaygroundE2E["Playground E2E Test Suite"]:::cicd

    %% Developer Tools
    ToolsDeps["Dependencies Executor"]:::tools
    ToolsEslint["ESLint Plugin"]:::tools
    ToolsStylelint["Stylelint Plugin"]:::tools
    Plop["Plop Code Scaffolding"]:::tools

    %% CI/CD & External Services
    CI["CI/CD Pipelines\n(GitHub Actions)"]:::cicd
    Chromatic["Chromatic"]:::external
    Npm["npm Registry"]:::external
    GitHubPages["Docs Hosting\n(GitHub Pages)"]:::external

    %% Relationships
    Orchestrator -->|"orchestrates"| ComponentLibrary
    Orchestrator -->|"orchestrates"| DocsSite
    Orchestrator -->|"orchestrates"| NextApp
    Orchestrator -->|"orchestrates"| RemixApp
    Orchestrator -->|"orchestrates"| RemixViteApp
    Orchestrator -->|"orchestrates"| PlaygroundApp
    Orchestrator -->|"orchestrates"| NextE2E
    Orchestrator -->|"orchestrates"| PlaygroundE2E

    ComponentLibrary -->|"import"| DocsSite
    ComponentLibrary -->|"import"| NextApp
    ComponentLibrary -->|"import"| RemixApp
    ComponentLibrary -->|"import"| RemixViteApp
    ComponentLibrary -->|"import"| PlaygroundApp

    NextE2E -->|"test"| NextApp
    PlaygroundE2E -->|"test"| PlaygroundApp

    CI -->|"run builds/tests"| ComponentLibrary
    CI -->|"run docs build"| DocsSite
    CI -->|"run sample builds"| NextApp
    CI -->|"run sample builds"| RemixApp
    CI -->|"run sample builds"| RemixViteApp
    CI -->|"visual tests"| Chromatic
    CI -->|"publish components"| Npm
    CI -->|"deploy docs"| GitHubPages

    ToolsDeps -.->|"integrated"| Orchestrator
    ToolsDeps -.->|"integrated"| CI
    ToolsEslint -.->|"integrated"| Orchestrator
    ToolsEslint -.->|"integrated"| CI
    ToolsStylelint -.->|"integrated"| Orchestrator
    ToolsStylelint -.->|"integrated"| CI
    Plop -.->|"integrated"| Orchestrator
    Plop -.->|"integrated"| CI

    %% Click Events
    click Orchestrator "https://github.com/migrationsverket/midas/blob/dev/lerna.json"
    click Orchestrator "https://github.com/migrationsverket/midas/blob/dev/nx.json"
    click ComponentLibrary "https://github.com/migrationsverket/midas/tree/dev/packages/components"
    click DocsSite "https://github.com/migrationsverket/midas/tree/dev/apps/docs"
    click NextApp "https://github.com/migrationsverket/midas/tree/dev/apps/next"
    click RemixApp "https://github.com/migrationsverket/midas/tree/dev/apps/remix"
    click RemixViteApp "https://github.com/migrationsverket/midas/tree/dev/apps/remix-vite"
    click PlaygroundApp "https://github.com/migrationsverket/midas/tree/dev/apps/playground"
    click NextE2E "https://github.com/migrationsverket/midas/tree/dev/apps/next-e2e"
    click PlaygroundE2E "https://github.com/migrationsverket/midas/tree/dev/apps/playground-e2e"
    click ToolsDeps "https://github.com/migrationsverket/midas/tree/dev/tools/dependencies"
    click ToolsEslint "https://github.com/migrationsverket/midas/tree/dev/tools/eslint"
    click ToolsStylelint "https://github.com/migrationsverket/midas/tree/dev/tools/stylelint-plugin"
    click Plop "https://github.com/migrationsverket/midas/blob/dev/tools/plopfile.js"
    click CI "https://github.com/migrationsverket/midas/tree/dev/.github/workflows"

    %% Styles
    classDef library fill:#cfe2f3,stroke:#000,stroke-width:1px;
    classDef apps fill:#d9ead3,stroke:#000,stroke-width:1px;
    classDef tools fill:#fce5cd,stroke:#000,stroke-width:1px;
    classDef cicd fill:#d9d2e9,stroke:#000,stroke-width:1px;
    classDef external fill:#fff2cc,stroke:#000,stroke-width:1px;
```
