[WIP] desired architecture & structure

[jkowalleck]

🚧 this description is WIP 🚧

---

desired architecture could be like:

dist: the library for use

all compiled/usabe JavaScript code is under the dist/dist.<target> directory.

these MUST be shipped with a dist-build/release.
in case the content of dist is generated from other souces, the dist/dist.<target> dir may be part of the repository.

src: sources

there might be a src directory if the code is compiled from source code to JavaScript.

these may be intended to be shipped with a dist-build/release

there might be sub-folders for sub-modules

there must be no sub-folders for sub-packages in the src folder

packages: sub-packages

there might be a packages directory if the code is derived in multiple sub-packages.
each sub-folder of packages represents a sub-package, and therefore must contain a package.json file that is a node package manifest.

these may be intended to be shipped with a dist-build/release

there might be sub-folders for sources, resources, ...

resources

resources like schema files and others are in the res directory.

there must be a README file in the folder that explains where the files stem from, and describe the purpose, and if/how they were processed/modified.

if resources are used in the library (not only in tests), then:
resources MUST to be shipped with a dist-build/release

tests

tests are in the test/tests directory.
files might be called *.spec.js, *.test.js. File extensions might be .js, .cjs, .mjs .
tests must test the final distribution. tests may test original source code if the lib is transpiled.

resources not intended to be shipped with a dist-build/release

docs: documentations and other related

there may be a folder doc/docs that holds all docs

the content may be shipped with a dist-build

---

the following describes internals of the library (and source, if it applies)

models

the core feature of the library are data models.

models are instances of domain specific objects that hold the state of their domain. each CDX data structure is intended to be an own model.
data models dont have any business logic that is outside of their domain. they are plain state models with properties.
all properties are (pseudo-)type-safe. preferred with getters/setters to assure type safety and internal business logic of the respective domain.

implementation can be class- or prototype-based.
usage must be object-oriented.

models are in a sub-folder called models.
there is exactly one model definition exported per file. files are called as the exported model.
there can be additional export for model-specific data structures, if needed.

factories & builders

since data models do not have any outside-business-logic it is possible to provide this code in factories and builders.

factories are in a sub-folder called factories. Files are called by purpose/use-case of its internals. there can be multiple factories in a single file.
builders are in a sub-folder called builders. Files are called by purpose/use-case of its internals. there can be multiple builders in a single file.

(de)serilizers / (de)normalizers

normalization from/to JSON and XML is done outside the data model classes.

related files are in a sub-folder called serialize which then can hold all the different (sub-)folders and structures

implementation can be object-oriented or functional.

---

see also: CycloneDX/cyclonedx-node-module#226