forked from
tokono.ma/diffuse
A music player that connects to your cloud/distributed storage.
chore: add DESIGN doc
+38
+38
DESIGN.md
+38
DESIGN.md
···
1
+
# Design
2
+
3
+
## Architecture
4
+
5
+
Diffuse provides a set of custom (DOM) elements (aka. web components) that can be combined into a working audio player or media browser living in a web view.
6
+
7
+
8
+
### Components / Elements
9
+
10
+
There are various categories of these elements, and may have subcategories. Each element lives in its own directory, containing the code, documentation and other assets associated with that element. The directory for the elements is `src/components/`, each subdirectory is a category which in turn may have one or more subcategories. If a directory has an `element.js` then that directory represents the element, not a subcategory.
11
+
12
+
A few examples:
13
+
- `src/components/engine/audio/element.js`: Category = engine, element = audio
14
+
- `src/components/output/polymorphic/indexed-db/element.js`: Category = output, subcategory = polymorphic, element = indexed-db
15
+
- `src/components/transformer/output/refiner/default/element.js`: Category = transformer, subcategory 1 = output, subcategory 2 = refiner, element = default
16
+
17
+
Most categories of components are independent, they do not rely on other components. There are a few exceptions:
18
+
19
+
- The category named 'orchestrator'. These are compositions of other components, meaning they consume other components. These have attributes ending with `-selector` which is a DOM selector that points at the component that is the dependency.
20
+
- The category named 'configurator'. These take other components as DOM children with the same actions/methods as the configurator itself. They serve to delegate or combine.
21
+
22
+
23
+
### Definitions
24
+
25
+
`src/definitions/` are lexicons, JSON schemas that describe data in the system.
26
+
27
+
28
+
### Themes
29
+
30
+
Like orchestrator components, these are compositions of elements. Unlike orchestrators however, it doesn't compose by the use of selectors, instead we write the custom elements as HTML and use the DOM as the composition layer. Alternatively, custom elements can be created in Javascript and then added to the DOM from there.
31
+
32
+
33
+
### Other directories
34
+
35
+
- `src/common`: Common Javascript code shared by various components and/or themes.
36
+
- `src/styles`: Common CSS shared by themes, the index page or constituents (part of themes).
37
+
- `src/favicons`, `src/fonts`, `src/images` are binary assets for themes and the index page (`src/index.vto`)
38
+
- `src/_components` and `src/_includes` are templates used in `.vto` templates, again themes and index page.