# rio-cloud/create-frontend architecture

> Architecture diagram of the GitHub repository rio-cloud/create-frontend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rio-cloud/create-frontend
- Repository: https://github.com/rio-cloud/create-frontend

## Overview

##### Project type and purpose
- This is an open‐source CLI tool (a Node.js application) whose purpose is to scaffold opinionated React/Vite frontend projects.
- It provides a template directory containing a ready-to-go frontend stack (React, Redux Toolkit, RTK Query, React Router, MSW, etc.), and a set of CLI modules to customize and write out that template based on user-provided parameters (OAuth IDs, Sentry DSN, etc.).

##### File structure
- Top‐level:
- index.js – CLI entrypoint
- src/cli.js, src/tasks.js, src/util.js, src/rioLogo.js – core modules for parsing arguments, orchestrating tasks, utilities, and console art
- template/ – a complete React/Vite frontend project scaffold that will be copied and parameterized
- .github/, LICENSE, README.md, package.json, biome.json – CI, licensing, dependencies, formatting
- Patterns:
- A “template engine” pattern: copy-and-transform
- Task orchestration: CLI → tasks → utility functions → filesystem & child_process
- No web server or database inside this project—it’s purely a code generator.

##### README for additional insights
- Confirms it’s invoked via `npm create rio-cloud/frontend <project-name>`
- Lists the frontend stack (Vite, React, Redux Toolkit, RTK Query, MSW, React Hook Form, react-intl, Sentry, Renovate, Biome) – these are only in the template.
- Mentions external dependencies (OAuth, Sentry) that the generated project will integrate with but not used by the CLI itself except for parameter injection.

##### Main components and interactions
A. User & Environment
- The developer runs the CLI (`npm create …`) in a shell.
- CLI prompts (or reads flags) for OAuth/Sentry params.
B. CLI Core (Node.js process)
1. index.js
– Bootstraps the CLI, shows rio logo, forwards args to cli.js
2. src/cli.js
– Parses user input (project name, OAuth IDs, DSN)
– Calls tasks.js with parsed options
3. src/tasks.js
– High-level orchestration:
- Create project directory
- Copy template folder contents using fs.* functions
- Perform variable substitution in .env, package.json, config files
- Install dependencies (invoke `npm install` via child_process)
- Initialize git (if enabled)
- Output “Next steps” instructions
4. src/util.js
– Helpers for string templating, path resolution, logging, error handling
5. src/rioLogo.js
– ASCII art/logo displayed at startup
C. Template Directory
- A self-contained React/Vite project that includes:
– src/ (components, pages, routes, configuration, mocks, tests)
– package.json, tsconfig, Vite config, .env files, CI configs, mocks setup, Playwright config, Renovate, Biome, etc.
D. External Systems
- npm registry – to fetch packages when installing dependencies in the new project
- git – optional `git init` in the new project directory
- OAuth provider & Sentry – parameters injected into the scaffolded project for later runtime usage (no live calls at CLI time)

##### Architectural patterns and design principles
- Single‐responsibility modules: cli, tasks, util, logo
- Template engine: treat the template folder as a source of truth; isolate transformation logic
- Sequential task orchestration: each step produces the inputs for the next
- Minimal external side‐effects (only FS and child_process calls)

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["Developer (User)"]:::user

    subgraph "CLI Core"
        Index["index.js"]:::cli
        CLIParser["src/cli.js"]:::cli
        Tasks["src/tasks.js"]:::cli
        Util["src/util.js"]:::cli
        Logo["src/rioLogo.js"]:::cli
    end

    subgraph "Template Store"
        TemplateStore["template/"]:::template
    end

    Docs["docs/"]:::template

    subgraph "Project Metadata & Config"
        Pkg["package.json"]:::template
        Biome["biome.json"]:::template
        Readme["README.md"]:::template
    end

    FS["Filesystem"]:::fs

    subgraph "Child Process Layer"
        NPM["npm install"]:::child
        Git["git init"]:::child
    end

    subgraph "External Systems"
        NPMReg["npm registry"]:::external
        GitSystem["git"]:::external
        OAuth["OAuth/Sentry endpoints"]:::external
    end

    User -->|npm create … + input| Index
    Index --> CLIParser
    Index --> Logo
    CLIParser --> Tasks
    Tasks --> FS
    FS -->|copy template/* to new-project/| TemplateStore
    Tasks -->|variable substitution| FS
    Tasks --> NPM
    Tasks -->|optional| Git
    NPM --> NPMReg
    Git --> GitSystem
    Tasks -->|print next steps| User

    click Index "https://github.com/rio-cloud/create-frontend/blob/main/index.js"
    click CLIParser "https://github.com/rio-cloud/create-frontend/blob/main/src/cli.js"
    click Tasks "https://github.com/rio-cloud/create-frontend/blob/main/src/tasks.js"
    click Util "https://github.com/rio-cloud/create-frontend/blob/main/src/util.js"
    click Logo "https://github.com/rio-cloud/create-frontend/blob/main/src/rioLogo.js"
    click TemplateStore "https://github.com/rio-cloud/create-frontend/tree/main/template/"
    click Docs "https://github.com/rio-cloud/create-frontend/tree/main/docs/"
    click Pkg "https://github.com/rio-cloud/create-frontend/blob/main/package.json"
    click Biome "https://github.com/rio-cloud/create-frontend/blob/main/biome.json"
    click Readme "https://github.com/rio-cloud/create-frontend/blob/main/README.md"

    classDef user fill:#aaffaa,stroke:#333,stroke-width:1px
    classDef cli fill:#bbddff,stroke:#333,stroke-width:1px
    classDef template fill:#ddffdd,stroke:#333,stroke-width:1px
    classDef fs fill:#eeeeee,stroke:#333,stroke-width:1px
    classDef child fill:#ffeb99,stroke:#333,stroke-width:1px
    classDef external fill:#ffcccc,stroke:#333,stroke-width:1px
```
