# ngneat/falso architecture

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

- Interactive diagram: https://gitdiagram.com/ngneat/falso
- Repository: https://github.com/ngneat/falso

## Overview

To: Principal Software Engineer

##### Project Type and Purpose
- This is an open-source, tree-shakeable, fully-typed TypeScript library for fake data generation (205+ functions).
- It’s managed as an Nx monorepo, with three main “products”:
- The core library (`packages/falso`)
- The documentation site (Docusaurus in `docs/`)
- Custom workspace executors and tooling (`tools/`)

##### File Structure
- Top-level:
- Configuration & metadata (`README.md`, `.github/`, `nx.json`, `package.json`, CI/CD workflows)
- Scripts (`scripts/`, root build configs)
- Docs app (`docs/`)
- Library package (`packages/falso/`)
- Workspace plugins and executors (`tools/`)
- Indicators:
- Monorepo orchestrated via Nx
- Jest + Rollup + Babel for building & testing
- Docusaurus for docs site
- Custom executors for locale builds, translation, manipulation

##### README Insights
- Core feature: generate massive fake data in Node/browser
- Usage examples, seed API, contribution guidance
- CI/CD badges imply GitHub Actions pipelines for CI and docs deploy

##### Main Components & Relationships
a. Components
1. Developer Machine & IDE
2. Nx CLI & Workspace Plugin (`tools/workspace-plugin`)
3. Custom Executors (`tools/executors/{build-locales,manipulator,translate}`)
4. Core Library Package (`packages/falso/src`)
5. Test Runner (Jest via `jest.config.ts`)
6. Bundler (Rollup + Babel)
7. Docs Generator (`docs-generator.js`) & Docusaurus App (`docs/`)
8. CI/CD Pipeline (GitHub Actions: ci.yml, docs.yml)
9. npm Registry (Publishing)
10. GitHub Repository (Issue/PR templates, Actions)

b. Relationships & Data Flow
- Developer invokes Nx CLI → calls custom workspace plugin → triggers executors
- Executors process locales / translate / manipulate → output intermediate files in `packages/falso` or `docs/src`
- Core code → tested by Jest → results feed into Rollup/Babel bundling → `dist/`
- `docs-generator.js` reads package metadata + source → generates MDX for docs site → Docusaurus builds static site
- GitHub Actions (ci.yml) runs tests & bundles → semantic-release publishes to npm
- GitHub Actions (docs.yml) runs docs build → deploys to GitHub Pages

c. Architectural Patterns & Principles
- Monorepo with Nx orchestrator
- Plugin-executor pattern for custom CLI tasks
- Separation of concerns: source code vs. docs vs. tooling
- Test-first with comprehensive Jest test suites
- Tree-shaking and typed exports for minimal bundle size

d. Key Technologies
– TypeScript, Babel, Rollup
– Jest for testing
– Nx for workspace management
– Docusaurus for documentation
– GitHub Actions for CI/CD
– semantic-release for automated publishing
– Custom Nx executors in NodeJS

##### Essential Elements to Capture
– Highlight extensibility: how new fake-data functions or executors plug into the system

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer
    Dev["Developer Machine & IDE"]:::developer

    %% Monorepo Config
    Monorepo["Monorepo Config\n(nx.json,\ntsconfig.base.json,\npackage.json)"]:::tooling

    %% CLI & Executors
    subgraph "CLI & Executors"
        direction TB
        CLI["Nx CLI & Workspace Plugin"]:::tooling
        BL["Executor: build-locales"]:::tooling
        MAN["Executor: manipulator"]:::tooling
        TR["Executor: translate"]:::tooling
    end

    %% Source Code
    CoreSrc["Core Library Source\npackages/falso/src"]:::source

    %% Build Tools
    Jest["Test Runner (Jest)"]:::build
    Rollup["Bundler (Rollup + Babel)"]:::build

    %% Documentation
    DocsGen["Docs Generator Script"]:::tooling
    Docusaurus["Docusaurus App\ndocs/"]:::source
    GHPages["GitHub Pages"]:::external

    %% CI/CD
    GitHubRepo["GitHub Repository"]:::external
    CI["CI Pipeline"]:::cicd
    DocsCI["Docs Pipeline"]:::cicd
    SemRel["semantic-release"]:::cicd

    %% Flows
    Dev --> CLI
    Dev --> Monorepo
    Monorepo --> CLI

    CLI --> BL
    CLI --> MAN
    CLI --> TR

    BL --> CoreSrc
    MAN --> CoreSrc
    TR --> CoreSrc

    CoreSrc --> Jest
    Jest --> Rollup
    Rollup --> npm["npm Registry"]:::external

    CoreSrc --> DocsGen
    Monorepo --> DocsGen
    DocsGen --> Docusaurus
    Docusaurus --> GHPages

    GitHubRepo --> CI
    CI --> Jest
    CI --> Rollup
    CI --> SemRel
    CI --> npm
    GitHubRepo --> DocsCI
    DocsCI --> DocsGen
    DocsCI --> Docusaurus
    DocsCI --> GHPages

    %% Click Events
    click CLI "https://github.com/ngneat/falso/tree/main/tools/workspace-plugin"
    click BL "https://github.com/ngneat/falso/blob/main/tools/executors/build-locales/index.ts"
    click MAN "https://github.com/ngneat/falso/blob/main/tools/executors/manipulator/index.ts"
    click TR "https://github.com/ngneat/falso/blob/main/tools/executors/translate/index.ts"
    click CoreSrc "https://github.com/ngneat/falso/tree/main/packages/falso/src"
    click Jest "https://github.com/ngneat/falso/blob/main/jest.config.ts"
    click Rollup "https://github.com/ngneat/falso/blob/main/packages/falso/rollup.config.js"
    click DocsGen "https://github.com/ngneat/falso/blob/main/docs-generator.js"
    click Docusaurus "https://github.com/ngneat/falso/tree/main/docs/"
    click CI "https://github.com/ngneat/falso/blob/main/.github/workflows/ci.yml"
    click DocsCI "https://github.com/ngneat/falso/blob/main/.github/workflows/docs.yml"
    click SemRel "https://github.com/ngneat/falso/blob/main/changelog.config.js"

    %% Styles
    classDef developer fill:#dddddd,stroke:#888,stroke-width:1px
    classDef tooling fill:#bbdefb,stroke:#1976d2,stroke-width:1px
    classDef source fill:#c8e6c9,stroke:#388e3c,stroke-width:1px
    classDef build fill:#b3e5fc,stroke:#0288d1,stroke-width:1px
    classDef cicd fill:#ffe0b2,stroke:#f57c00,stroke-width:1px
    classDef external fill:none,stroke-dasharray:5 5,stroke:#666,stroke-width:1px
```
