# alexeagleson/monorepo-example architecture

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

- Interactive diagram: https://gitdiagram.com/alexeagleson/monorepo-example
- Repository: https://github.com/alexeagleson/monorepo-example

## Overview

##### Project type and purpose
- This is a small-scale full-stack TypeScript “monorepo” tutorial that demonstrates how to combine:
- An Express server (packages/simple-express-server)
- A React front-end (packages/simple-react-app)
- A shared data package (packages/simple-shared-data)
- A Git submodule (react-dark-mode)
- Orchestration via Lerna + Yarn Workspaces + root TypeScript config
- The goal is to show code sharing, version alignment, hoisting, parallel scripts, and submodule integration.

##### File structure
- Root directories & files:
- lerna.json (defines packages/*, versioning, npmClient=yarn, useWorkspaces)
- package.json (private: true, workspaces: ["packages/*"], start script uses lerna run --parallel)
- tsconfig.json (baseUrl: "./packages")
- .gitmodules (tracks the react-dark-mode submodule)
- packages/ contains three sub-projects plus the Git submodule under simple-react-app/src/react-dark-mode:
- simple-express-server – Express API on port 3001, exports QueryPayload interface
- simple-react-app – CRA TypeScript app, fetches JSON from server, imports shared types and submodule component
- simple-shared-data – holds the shared QueryPayload interface

##### README insights
- Confirms use of Lerna and Yarn workspaces, reasons for monorepos (sync versions, share types), submodules for external independent repos
- Stresses running `yarn start` at root to launch both server and client in parallel
- Shows code-sharing of lodash and QueryPayload, and submodule addition of react-dark-mode

## Diagram (Mermaid)

```mermaid
graph TD
    %% Orchestrator Layer
    subgraph "Monorepo Orchestrator"
        direction TB
        Lerna["lerna.json"]:::orchestrator
        RootPkg["package.json"]:::orchestrator
        RootTS["tsconfig.json"]:::orchestrator
        GitModules[".gitmodules"]:::orchestrator
    end

    %% Services Layer
    subgraph "simple-express-server" 
        direction TB
        ExpPkg["packages/simple-express-server/package.json"]:::service
        ExpTS["packages/simple-express-server/tsconfig.json"]:::service
        Server["packages/simple-express-server/server.ts"]:::service
    end

    subgraph "simple-react-app"
        direction TB
        ReactPkg["packages/simple-react-app/package.json"]:::service
        ReactTS["packages/simple-react-app/tsconfig.json"]:::service
        subgraph "public/"
            direction TB
            PublicIndex["index.html"]:::service
            PublicManifest["manifest.json"]:::service
            PublicRobots["robots.txt"]:::service
        end
        subgraph "src/"
            direction TB
            AppTsx["App.tsx"]:::service
            AppCss["App.css"]:::service
            AppTest["App.test.tsx"]:::service
            IndexTsx["index.tsx"]:::service
            IndexCss["index.css"]:::service
            EnvDts["react-app-env.d.ts"]:::service
            ReportWebVitals["reportWebVitals.ts"]:::service
            SetupTests["setupTests.ts"]:::service
            DarkMode["react-dark-mode/"]:::submodule
        end
    end

    subgraph "simple-shared-data"
        direction TB
        SharedPkg["packages/simple-shared-data/package.json"]:::shared
        SharedIndex["packages/simple-shared-data/index.ts"]:::shared
    end

    %% Hoisted Dependencies
    NodeModules[("node_modules")]:::hoisted

    %% External Entities
    NpmRegistry(("npm registry")):::external
    GitRepo["External Git Repo"]:::external

    %% Relationships
    Lerna -->|"runs start"| ExpPkg
    Lerna -->|"runs start"| ReactPkg

    ReactPkg -->|"hoisted deps"| NodeModules
    ExpPkg -->|"hoisted deps"| NodeModules
    SharedPkg -->|"hoisted deps"| NodeModules

    ReactPkg -->|"HTTP GET"| Server
    Server -->|"JSON QueryPayload"| ReactPkg

    ExpPkg -->|"imports QueryPayload"| SharedPkg
    ReactPkg -->|"imports QueryPayload"| SharedPkg

    ReactPkg -->|"imports DarkMode"| DarkMode

    GitModules -.->|submodule link| DarkMode
    GitRepo -.->|tracked by .gitmodules| DarkMode
    Lerna -.->|fetches| NpmRegistry

    %% Click Events
    click Lerna "https://github.com/alexeagleson/monorepo-example/blob/master/lerna.json"
    click RootPkg "https://github.com/alexeagleson/monorepo-example/blob/master/package.json"
    click RootTS "https://github.com/alexeagleson/monorepo-example/blob/master/tsconfig.json"
    click GitModules "https://github.com/alexeagleson/monorepo-example/blob/master/.gitmodules"
    click ExpPkg "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-express-server/package.json"
    click ExpTS "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-express-server/tsconfig.json"
    click Server "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-express-server/server.ts"
    click ReactPkg "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-react-app/package.json"
    click ReactTS "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-react-app/tsconfig.json"
    click PublicIndex "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-react-app/public/index.html"
    click PublicManifest "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-react-app/public/manifest.json"
    click PublicRobots "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-react-app/public/robots.txt"
    click AppTsx "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-react-app/src/App.tsx"
    click AppCss "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-react-app/src/App.css"
    click AppTest "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-react-app/src/App.test.tsx"
    click IndexTsx "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-react-app/src/index.tsx"
    click IndexCss "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-react-app/src/index.css"
    click EnvDts "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-react-app/src/react-app-env.d.ts"
    click ReportWebVitals "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-react-app/src/reportWebVitals.ts"
    click SetupTests "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-react-app/src/setupTests.ts"
    click SharedPkg "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-shared-data/package.json"
    click SharedIndex "https://github.com/alexeagleson/monorepo-example/blob/master/packages/simple-shared-data/index.ts"

    %% Styles
    classDef orchestrator fill:#FFA500,stroke:#333,stroke-width:1px
    classDef service fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef shared fill:#90EE90,stroke:#333,stroke-width:1px
    classDef submodule fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef hoisted fill:#E0FFFF,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
