# mvcds/hubi architecture

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

- Interactive diagram: https://gitdiagram.com/mvcds/hubi
- Repository: https://github.com/mvcds/hubi

## Overview

##### Project type and purpose
- **Type**: A command‐line tool (CLI) that implements a Domain‐Driven Design (DDD) “ubiquitous language” engine.
- **Purpose**: Read versioned YAML domain files, parse them into an internal model, apply translation strategies (e.g., Joi schemas, HTML docs, log output), and write code or documentation across multiple repositories in a consistent, versioned way.

##### File structure
- **Top‐level scripts**:
- index.js, package.json → CLI entry point and config
- scripts/coverage.sh → test & coverage tasks
- docs/ & assets/ → user documentation & examples
- **src/** broken into:
- CLI (src/CLI/*) → hubi commands (hubi-log, hubi-save)
- Domain (src/Domain/*) → Entities, Objects (parsers & translators), Services (business logic), UseCases (application workflows)
- **Configuration & metadata**:
- .releaserc.yaml, .travis.yml, .huskyrc, commitlint.config.js, .gitignore, .editorconfig, etc.

##### Key insights from the README
- Hubi is inspired by database migrations but for domain language files
- Core API in docs/api.md; domain file guide in docs/domain-file-guide.md
- Features: reading domain YAML, generating outputs via translators, watching for file changes, running tests

##### Main components
a. **CLI Layer** (External boundary)
- Commands: `hubi save`, `hubi log`, etc.
- Parses user flags & options → invokes UseCases
b. **Application Layer**
- **UseCases** (e.g., SaveUbiquitousLanguageIntoFile, LogUbiquitousLanguageIntoConsole)
- Coordinates Services & Translators
c. **Domain Layer**
- **Services** (e.g., LoadsTokens, UsesTranslator, NormalizeName)
- **Entities** (UbiquitousToken)
- **Objects**:
- AttributeParser (builds attribute objects from YAML + decorators)
- Translation (dependency graph of terms)
- Translator implementations (JoiTranslator, SiteTranslator, LogTranslator, UbiTranslator)
d. **Infrastructure / I/O**
- File System: reads `.yml` domain files, writes generated files (code, docs, logs)
- External test fixtures for BDD/tests
e. **Auxiliary**
- Config & Build Tools (Travis CI, Husky, commitlint)
- Documentation (docs/api.md, index.html)

##### Relationships and data flow
1. **User** runs `hubi` CLI →
2. **CLI Layer** interprets flags → calls appropriate **UseCase**
3. **UseCase** loads domain files via **LoadsTokens** service → builds domain entities using **AttributeParser**
4. **UseCase** passes entities to **UsesTranslator** service, selecting appropriate **Translator** (Joi, Site, Log, Ubi)
5. **Translator** modules render templates (Pug files + data) → output code/docs
6. **UseCase** instructs file I/O: write to disk or console
7. Optional: **WatchForChanges** UseCase monitors FS for live updates

##### Architectural patterns & design principles
- **Hexagonal / Ports & Adapters**:
- Ports: UseCases define application API
- Adapters: CLI adapter, FileSystem adapter, Translator adapters
- **Layered architecture**: clear separation between CLI, application (UseCases), domain, and infrastructure
- **Dependency Inversion**: high‐level UseCases depend on abstract Services & Translators

##### Essential elements to capture
- **CLI entry point** (`index.js`) and commands
- **UseCases** as orchestrators
- **Domain Services** (LoadsTokens, UsesTranslator, etc.)
- **Translators** (JoiTranslator, SiteTranslator, LogTranslator, UbiTranslator)
- **AttributeParser** sub‐components (factory, decorators)
- **File input/output** interactions (read `.yml`, write code/docs)
- **Testing / fixtures** as part of validation workflow
- **Configuration & CI/CD** tools at the perimeter

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["index.js"]:::cli
        HUBI["hubi"]:::cli
        HUBI_LOG["hubi-log"]:::cli
        HUBI_SAVE["hubi-save"]:::cli
    end

    %% Application Layer
    subgraph "Application Layer"
        SaveUC["SaveUbiquitousLanguageIntoFile"]:::app
        LogUC["LogUbiquitousLanguageIntoConsole"]:::app
        TransUC["TranslateDomainFilesToUbiquitousLanguage"]:::app
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        subgraph Services
            LoadsTokens["LoadsTokens"]:::domain
            UsesTranslator["UsesTranslator"]:::domain
            NormalizeName["NormalizeName"]:::domain
            LogConditionally["LogConditionally"]:::domain
            RequiresAttribute["RequiresAttribute"]:::domain
        end
        subgraph Entities
            UbiToken["UbiquitousToken"]:::domain
        end
        subgraph Objects
            AttributeParser["AttributeParser"]:::domain
            TranslationGraph["TranslationGraph"]:::domain
        end
    end

    %% Translators
    subgraph "Translator Adapters"
        JoiT["JoiTranslator"]:::translator
        SiteT["SiteTranslator"]:::translator
        LogT["LogTranslator"]:::translator
        UbiT["UbiTranslator"]:::translator
    end

    %% Infrastructure Layer
    subgraph "Infrastructure / I/O"
        FileSystem["File System I/O"]:::infra
        Docs["Documentation & Guides"]:::infra
        CI["CI/CD & Config"]:::infra
    end

    %% Connections
    CLI -->|entry point| HUBI
    HUBI -->|parse flags| HUBI_SAVE
    HUBI -->|parse flags| HUBI_LOG
    HUBI -->|parse flags| TransUC

    HUBI_SAVE -->|"invoke UseCase"| SaveUC
    HUBI_LOG -->|"invoke UseCase"| LogUC
    TransUC -->|"invoke UseCase"| TransUC

    SaveUC -->|"load domain files"| LoadsTokens
    LogUC -->|"load domain files"| LoadsTokens
    TransUC -->|"load domain files"| LoadsTokens

    LoadsTokens -->|"build entities"| UbiToken
    LoadsTokens -->|"parse attributes"| AttributeParser
    LoadsTokens -->|"build graph"| TranslationGraph

    SaveUC -->|"select translator"| UsesTranslator
    LogUC -->|"select translator"| UsesTranslator
    TransUC -->|"select translator"| UsesTranslator

    UsesTranslator -->|"Joi strategy"| JoiT
    UsesTranslator -->|"Site strategy"| SiteT
    UsesTranslator -->|"Log strategy"| LogT
    UsesTranslator -->|"Ubi strategy"| UbiT

    JoiT -->|"render templates"| FileSystem
    SiteT -->|"render templates"| FileSystem
    LogT -->|"output log"| FileSystem
    UbiT -->|"generate code"| FileSystem

    SaveUC -->|"write files"| FileSystem
    LogUC -->|"write to console"| FileSystem
    TransUC -->|"write outputs"| FileSystem

    FileSystem --> Docs
    CI --> Docs

    %% Click Events
    click CLI "https://github.com/mvcds/hubi/blob/master/index.js"
    click HUBI "https://github.com/mvcds/hubi/tree/master/src/CLI/hubi"
    click HUBI_LOG "https://github.com/mvcds/hubi/tree/master/src/CLI/hubi-log"
    click HUBI_SAVE "https://github.com/mvcds/hubi/tree/master/src/CLI/hubi-save"
    click LogUC "https://github.com/mvcds/hubi/blob/master/src/Domain/UseCases/LogUbiquitousLanguageIntoConsole/index.js"
    click SaveUC "https://github.com/mvcds/hubi/blob/master/src/Domain/UseCases/SaveUbiquitousLanguageIntoFile/index.js"
    click TransUC "https://github.com/mvcds/hubi/blob/master/src/Domain/UseCases/TranslateDomainFilesToUbiquitousLanguage/index.js"
    click UbiToken "https://github.com/mvcds/hubi/blob/master/src/Domain/Entities/UbiquitousToken/index.js"
    click LoadsTokens "https://github.com/mvcds/hubi/blob/master/src/Domain/Services/LoadsTokens/index.js"
    click UsesTranslator "https://github.com/mvcds/hubi/blob/master/src/Domain/Services/UsesTranslator/index.js"
    click NormalizeName "https://github.com/mvcds/hubi/blob/master/src/Domain/Services/NormalizeName/index.js"
    click LogConditionally "https://github.com/mvcds/hubi/blob/master/src/Domain/Services/LogConditionally/index.js"
    click RequiresAttribute "https://github.com/mvcds/hubi/blob/master/src/Domain/Services/RequiresAttribute/index.js"
    click AttributeParser "https://github.com/mvcds/hubi/blob/master/src/Domain/Objects/AttributeParser/index.js"
    click TranslationGraph "https://github.com/mvcds/hubi/blob/master/src/Domain/Objects/Translation/index.js"
    click JoiT "https://github.com/mvcds/hubi/blob/master/src/Domain/Objects/Translator/JoiTranslator/index.js"
    click SiteT "https://github.com/mvcds/hubi/blob/master/src/Domain/Objects/Translator/SiteTranslator/index.js"
    click LogT "https://github.com/mvcds/hubi/blob/master/src/Domain/Objects/Translator/LogTranslator/index.js"
    click UbiT "https://github.com/mvcds/hubi/blob/master/src/Domain/Objects/Translator/UbiTranslator/index.js"

    %% Styles
    classDef cli fill:#D0E6FF,stroke:#003D99
    classDef app fill:#DFFFE0,stroke:#008000
    classDef domain fill:#FFE5B4,stroke:#CC8400
    classDef translator fill:#E5D0FF,stroke:#8000FF
    classDef infra fill:#E0E0E0,stroke:#666666
```
