How mvcds/hubi works
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