# svobik7/next-roots architecture

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

- Interactive diagram: https://gitdiagram.com/svobik7/next-roots
- Repository: https://github.com/svobik7/next-roots

## Overview

##### Overall Project Type and Purpose
- This is an open‑source CLI tool and library designed to integrate with Next.js (v15+) and generate localized routes.
- Its primary goal is to read original route definitions from a “roots” directory, apply i18n translations (via static/dynamic “i18n.js/ts files”), and produce a new “app” directory containing localized routes.
- It further provides a strongly typed Router class which offers helper methods (such as getHref, getLocaleFromHref, and getRouteFromHref) for linking and route management.

##### Main Architectural Components
- CLI Interface & Commands:
– The src/cli folder contains commands (like generate and watch) that trigger route generation.
– Commands such as “generateDeclarationFile,” “generateRouterSchemaFile,” etc. are used to compile, translate, and update files.
- Configuration Module:
– The roots.config.js (or roots.config.cjs for ESM) holds configuration parameters (originDir, localizedDir, locales, defaultLocale, prefixDefaultLocale, etc.) that control the generation process.
- Route Generation Engine:
– This module scans the “roots” directory structure, reads translation files (i18n.js/ts, i18n.mjs) alongside route directories, and applies rules to build the “app” folder structure.
– It interacts with file system utilities (found in src/utils and src/cli/utils) to handle file copying, transformation, and deletion (for wiping the “app” folder).
- i18n Translation Module:
– Supports both static and dynamic translation, reading route translation definitions from i18n files placed close to route pages.
– Uses esbuild to compile these translation files, ensuring that both synchronous and async translation modes are supported.
- Router Module/Library:
– Encapsulated in the src/router folder (and tested in router.test.ts) and included as part of the exported API.
– Provides methods for generating URLs based on the generated route schema and is strongly typed using TypeScript.
- File System & Build Integration:
– Contains utilities (e.g., fs-utils, path-utils, rewrite-utils) that manage paths, file operations, and dynamic routing rewrites.
– Integration with build pipelines is supported via GitHub workflows, ESLint, Husky pre-commit hooks, and an example manifest provided in the file tree.
- Testing & Examples:
– A series of examples (e.g., basic, basic-esm, with-preferred-language-catchall, with-preferred-language-middleware) illustrate various usage scenarios.
– End-to-end tests (using Cypress for the “basic” example), Vitest configuration, and mocks in the __mocks__ folder are used to verify functionality.

##### Relationships & Data Flow Between Components
- The CLI Interface reads the configuration via the configuration module.
- The Route Generation Engine then scans the “roots” folder for route definitions and corresponding translation (i18n) files.
- Using file system utilities, it generates or updates the “app” folder (the output) with localized routes.
- The Router Module leverages a generated schema (from the route generation process) to perform link generation, locale detection, and route mapping at runtime.
- The overall data flow is: Configuration → Route Scanner/Generator (with i18n translation) → File Generation in “app” → Runtime Router for link mapping.
- Integration with Next.js happens through generated route files which include additional props (like locale, pageHref) passed down to pages and layouts.

##### Architectural Patterns & Design Principles
- Separation of Concerns: The project clearly distinguishes between static configuration, dynamic route generation, CLI operations, and runtime routing.
- Modular Design: Each folder (CLI, src/utils, src/router, src/cli/templates) represents a separate module/functionality.
- Extensibility: The tooling supports both static and dynamic translations and allows custom post-generation actions via afterGenerate callbacks.
- Strong Typing: The use of TypeScript and detailed type definitions enhances reliability (for example, in the Router class methods).
- Build Integration: Use of esbuild for compiling i18n files and integration with GitHub workflows for CI/CD underscores modern build practices.

##### Elements
– “CLI Interface (src/cli)”
– “Configuration Module (roots.config.js)”
– “Route Scanner & Generator Engine”
– “i18n Translation Handler”
– “File System Utilities”
– “Router Module (src/router)”
– “Generated App Folder (Output)”
– From the “Configuration Module” into the “Route Generator.”
– From the “Route Generator” into file creation, updating the “app” folder.
– From the “Router Module” referencing the generated route schema and then feeding pages.
– Another for core processing (route generation, i18n translation).
– A third for runtime components (Router, Next.js integration).
- Optionally, include integration points (ESLint, Husky, GitHub workflows) as side modules that affect quality and deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLI["CLI Interface (src/cli)"]:::cli
    Config["Configuration Module (roots.config.js)"]:::config
    Generator["Route Generation Engine (src/cli/generators)"]:::generator
    I18n["i18n Translation Handler (src/cli/compilers/compileI18n.ts)"]:::i18n
    FS["File System Utilities (src/utils)"]:::fs
    App["Generated App Folder (Output)"]:::output

    subgraph "Runtime Components"
        Router1["Router Module (router.ts)"]:::runtime
        Router2["Static Router Module (static-router.ts)"]:::runtime
    end

    Examples["Testing & Examples (examples)"]:::examples

    CLI -->|"reads"| Config
    Config -->|"supplies-settings"| Generator
    Generator -->|"applies-i18n"| I18n
    Generator -->|"utilizes"| FS
    FS -->|"generates"| App
    App -->|"feeds-schema"| Router1
    App -->|"feeds-schema"| Router2
    Router1 -->|"supports"| Examples

    click CLI "https://github.com/svobik7/next-roots/tree/master/src/cli"
    click Config "https://github.com/svobik7/next-roots/blob/master/roots.config.js"
    click Generator "https://github.com/svobik7/next-roots/tree/master/src/cli/generators"
    click I18n "https://github.com/svobik7/next-roots/blob/master/src/cli/compilers/compileI18n.ts"
    click FS "https://github.com/svobik7/next-roots/tree/master/src/utils"
    click Router1 "https://github.com/svobik7/next-roots/blob/master/src/router/router.ts"
    click Router2 "https://github.com/svobik7/next-roots/blob/master/src/router/static-router.ts"
    click Examples "https://github.com/svobik7/next-roots/tree/master/examples"

    classDef cli fill:#F0E68C,stroke:#000,stroke-width:2px;
    classDef config fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef generator fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef i18n fill:#87CEEB,stroke:#000,stroke-width:2px;
    classDef fs fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef output fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef runtime fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef examples fill:#FFDEAD,stroke:#000,stroke-width:2px;
```
