# rsv-ink/ink_components architecture

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

- Interactive diagram: https://gitdiagram.com/rsv-ink/ink_components
- Repository: https://github.com/rsv-ink/ink_components

## Overview

##### Project type and purpose
- InkComponents is an open-source Ruby gem that implements a design system for Rails using ViewComponent.
- It functions as a Rails Engine, packaging a library of UI components (built with Flowbite/Tailwind) that host applications can install and render via helper methods.

##### File structure
- Top-level:
- app/             → Rails Engine’s MVC-style structure
- lib/             → Engine definition, version, installers, rake tasks
- config/          → Routes, engine mounting, initializers
- app/assets & app/javascript → CSS (Tailwind) and JS entry for component assets
- spec/dummy/      → A dummy Rails app used to exercise and preview the engine
- spec/            → RSpec test suite for engine and components
- docs/            → Usage and integration guides
- Key patterns:
- Rails Engine (lib/ink_components/engine.rb)
- Component-based UI (app/components) using ViewComponent
- Asset pipeline integration (app/assets, tailwind.config.js, package.json)
- Generators & installers (lib/install, rake tasks) for host-app integration

##### Insights from README
- Describes the gem’s purpose: provide reusable Flowbite components.
- Installation generates Tailwind config, mounts the engine, and builds CSS.
- Offers a “Lookbook Preview” served by the dummy app at /ink_components/lookbook.

a. Main components
- Host Rails Application
- InkComponents Engine (the gem)
– ViewComponent-based UI components
– Asset definitions (Tailwind CSS, JavaScript)
– Generators & Rake tasks
– Engine routes (Lookbook preview)
- Asset Build Pipeline
– Tailwind CLI (yarn build:css)
– Webpacker / importmap (app/javascript)
- Test Harness
– RSpec suite
– Dummy Rails app for integration and Lookbook
b. Relationships and interactions
- Host App “requires” the gem → Bundler loads lib/ink_components/engine.rb
- Engine mounts its routes into the host (e.g., /ink_components/lookbook)
- Host views call helper wrappers → invoke ViewComponent render methods
- Asset build process pulls in engine’s Tailwind config & CSS into host’s build
- Rake tasks & generators scaffold configuration in host (tailwind.config.js)
- Tests exercise components inside a dummy app simulating a real host
c. Architectural patterns and principles
- Rails Engine modularity: self-contained plugin with its own MVC and assets
- Component-oriented UI via ViewComponent for encapsulation and reusability
- Generator pattern for seamless host-app integration
- Asset pipelining with Tailwind and standard Rails asset conventions
d. Key technologies/frameworks
- Ruby on Rails Engine
- ViewComponent gem
- Tailwind CSS (via yarn & tailwind.config.js)
- RSpec & dummy Rails app for testing
- Lookbook for live component previews

##### Final advice
- Every logical module: components library, asset config, installers, tests
- Don’t overcomplicate: represent each folder/group as a component if it has its own responsibility

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Application
    subgraph "Host Rails Application" 
        HostApp["Host Rails Application"]:::runtime
    end

    %% InkComponents Engine
    subgraph "InkComponents Engine (Gem)"
        GemEntry["Gem Entry Point"]:::runtime
        EngineDef["Engine Definition"]:::runtime
        Version["Version Management"]:::runtime
        UIComponents["UI Components Library"]:::runtime
        AssetManifest["Asset Manifest"]:::runtime
        TailwindCSS["Tailwind CSS Stylesheet"]:::runtime
        Images["Component Images & Icons"]:::runtime
        JS["JavaScript Entry Point"]:::runtime
        Routes["Engine Routes (Lookbook Preview)"]:::runtime
        Controllers["Controllers (Engine namespace)"]:::runtime
        ViewHelpers["View Helpers"]:::runtime
        FormBuilder["Form Builder Helpers"]:::runtime
        subgraph "Generators & Installers" 
            InstallLib["Generators & Installers"]:::build
            InstallFile["install.rb"]:::build
            LookbookGen["lookbook.html.erb"]:::build
            TailwindGen["tailwind.config.js"]:::build
            RakeGen["tailwind.rake"]:::build
            ConfigGen["tailwind_config_generator.rb"]:::build
        end
        RakeTasks["Rake Tasks for Host Integration"]:::build
        Gemspec["Gem Specification"]:::runtime
    end

    %% Asset Pipeline
    subgraph "Asset Build Pipeline"
        TailwindCLI["Tailwind CLI (yarn build:css)"]:::build
        Webpacker["Webpacker / importmap"]:::build
        EngineTailwindConfig["Engine Tailwind Config"]:::build
    end

    %% Test Harness
    subgraph "Test Harness & Preview"
        DummyApp["Dummy Rails App"]:::test
        RSpecSuite["RSpec Test Suite"]:::test
        LookbookPreview["Lookbook Preview"]:::test
    end

    %% Documentation
    subgraph "Documentation"
        README["README & Docs"]:::docs
    end

    %% Relationships
    HostApp -->|"requires"| GemEntry
    GemEntry --> EngineDef
    EngineDef -->|"mounts routes"| HostApp
    HostApp -->|"renders helpers"| ViewHelpers
    ViewHelpers --> UIComponents
    AssetManifest --> HostApp
    TailwindCSS --> TailwindCLI
    JS --> Webpacker
    TailwindCLI -->|"reads config"| EngineTailwindConfig
    TailwindCLI -->|"builds CSS"| HostApp
    Webpacker --> HostApp
    EngineDef --> InstallLib
    InstallLib --> TailwindGen
    InstallLib --> RakeGen
    InstallLib --> ConfigGen
    EngineDef --> RakeTasks
    TestHarnessInteractions1 --> RSpecSuite
    DummyApp --> RSpecSuite
    DummyApp --> EngineDef
    DummyApp --> HostApp
    LookbookPreview --> DummyApp

    %% Click Events
    click EngineDef "https://github.com/rsv-ink/ink_components/blob/main/lib/ink_components/engine.rb"
    click GemEntry "https://github.com/rsv-ink/ink_components/blob/main/lib/ink_components.rb"
    click Version "https://github.com/rsv-ink/ink_components/blob/main/lib/ink_components/version.rb"
    click UIComponents "https://github.com/rsv-ink/ink_components/tree/main/app/components/ink_components"
    click AssetManifest "https://github.com/rsv-ink/ink_components/blob/main/app/assets/config/ink_components_manifest.js"
    click TailwindCSS "https://github.com/rsv-ink/ink_components/blob/main/app/assets/stylesheets/ink_components/application.tailwind.css"
    click Images "https://github.com/rsv-ink/ink_components/tree/main/app/assets/images/ink_components"
    click JS "https://github.com/rsv-ink/ink_components/blob/main/app/javascript/index.js"
    click Routes "https://github.com/rsv-ink/ink_components/blob/main/config/routes.rb"
    click Controllers "https://github.com/rsv-ink/ink_components/blob/main/app/controllers/ink_components/application_controller.rb"
    click ViewHelpers "https://github.com/rsv-ink/ink_components/blob/main/app/helpers/ink_components/view_helper.rb"
    click FormBuilder "https://github.com/rsv-ink/ink_components/blob/main/app/helpers/ink_components/form_builder.rb"
    click InstallLib "https://github.com/rsv-ink/ink_components/tree/main/lib/install/"
    click InstallFile "https://github.com/rsv-ink/ink_components/blob/main/lib/install/install.rb"
    click LookbookGen "https://github.com/rsv-ink/ink_components/blob/main/lib/install/lookbook.html.erb"
    click TailwindGen "https://github.com/rsv-ink/ink_components/blob/main/lib/install/tailwind.config.js"
    click RakeGen "https://github.com/rsv-ink/ink_components/blob/main/lib/install/tailwind.rake"
    click ConfigGen "https://github.com/rsv-ink/ink_components/blob/main/lib/install/tailwind_config_generator.rb"
    click RakeTasks "https://github.com/rsv-ink/ink_components/blob/main/lib/tasks/ink_components_tasks.rake"
    click DummyApp "https://github.com/rsv-ink/ink_components/tree/main/spec/dummy/"
    click RSpecSuite "https://github.com/rsv-ink/ink_components/tree/main/spec/"
    click EngineTailwindConfig "https://github.com/rsv-ink/ink_components/blob/main/tailwind.config.js"
    click README "https://github.com/rsv-ink/ink_components/blob/main/README.md"
    click README "https://github.com/rsv-ink/ink_components/tree/main/docs/"

    %% Styles
    classDef runtime fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef build fill:#FFEFD5,stroke:#FFA500,color:#CC8400
    classDef test fill:#E6FFE6,stroke:#28A745,color:#1E7F24
    classDef docs fill:#F3F4F6,stroke:#6A737D,color:#6A737D
```
