Improve documentation for architecture
- Simplify `README.md` by creating and moving some documentation to `architecture.md`. - Add more documentation for state handling between layers. - Improve some documentation to use clearer language.
This commit is contained in:
undergroundwires
@@ -1,44 +1,45 @@
|
||||
# Application
|
||||
|
||||
- It's mainly responsible for
|
||||
- creating and event based [application state](#application-state)
|
||||
- [parsing](#parsing) and [compiling](#compiling) [application data](#application-data)
|
||||
- Consumed by [presentation layer](./presentation.md)
|
||||
Application layer is mainly responsible for:
|
||||
|
||||
- creating an event-based and mutable [application state](#application-state),
|
||||
- [parsing and compiling](#parsing-and-compiling) the [application data](#application-data).
|
||||
|
||||
📖 Refer to [architecture.md | Layered Application](./architecture.md#layered-application) to read more about the layered architecture.
|
||||
|
||||
## Structure
|
||||
|
||||
- [`/src/` **`application/`**](./../src/application/): Contains all application related code.
|
||||
- [**`collections/`**](./../src/application/collections/): Holds [collection files](./collection-files.md)
|
||||
- [**`Common/`**](./../src/application/Common/): Contains common functionality that is shared in application layer.
|
||||
- `..`: other classes are categorized using folders-by-feature structure
|
||||
Application layer code exists in [`/src/application`](./../src/application/) and includes following structure:
|
||||
|
||||
- [**`collections/`**](./../src/application/collections/): Holds [collection files](./collection-files.md).
|
||||
- [**`Common/`**](./../src/application/Common/): Contains common functionality in application layer.
|
||||
- `...`: rest of the application layer source code organized using folders-by-feature structure.
|
||||
|
||||
## Application state
|
||||
|
||||
- [ApplicationContext.ts](./../src/application/Context/ApplicationContext.ts) holds the [CategoryCollectionState](./../src/application/Context/State/CategoryCollectionState.ts) for each OS
|
||||
- Uses [state pattern](https://en.wikipedia.org/wiki/State_pattern)
|
||||
- Same instance is shared throughout the application to ensure consistent state
|
||||
- 📖 See [Application State | Presentation layer](./presentation.md#application-state) to read more about how the state should be managed by the presentation layer.
|
||||
- 📖 See [ApplicationContext.ts](./../src/application/Context/ApplicationContext.ts) to start diving into the state code.
|
||||
It uses [state pattern](https://en.wikipedia.org/wiki/State_pattern) with context and state objects. [`ApplicationContext.ts`](./../src/application/Context/ApplicationContext.ts) the "Context" of state pattern provides an instance of [`CategoryCollectionState.ts`](./../src/application/Context/State/CategoryCollectionState.ts) (the "State" of the state pattern) for every supported collection.
|
||||
|
||||
Presentation layer uses a singleton (same instance of) [`ApplicationContext.ts`](./../src/application/Context/ApplicationContext.ts) throughout the application to ensure consistent state.
|
||||
|
||||
📖 Refer to [architecture.md | Application State](./architecture.md#application-state) to get an overview of event handling and [presentation.md | Application State](./presentation.md#application-state) for deeper look into how the presentation layer manages state.
|
||||
|
||||
## Application data
|
||||
|
||||
- Compiled to [`Application`](./../src/domain/Application.ts) domain object.
|
||||
- The scripts are defined and controlled in different data files per OS
|
||||
- Enables [data-driven programming](https://en.wikipedia.org/wiki/Data-driven_programming) and easier contributions
|
||||
- Application data is defined in collection files and
|
||||
- 📖 See [Application data | Presentation layer](./presentation.md#application-data) to read how the application data is read by the presentation layer.
|
||||
- 📖 See [collection files documentation](./collection-files.md) to read more about how the data files are structured/defined and see [collection yaml files](./../src/application/collections/) to directly check the code.
|
||||
Application data is collection files using YAML. You can refer to [collection-files.md](./collection-files.md) to read more about the scheme and structure of application data files. You can also check the source code [collection yaml files](./../src/application/collections/) to directly see the application data using that scheme.
|
||||
|
||||
## Parsing
|
||||
Application layer [parses and compiles](#parsing-and-compiling) application data into [`Application`](./../src/domain/Application.ts)). Once parsed, application layer provides the necessary functionality to presentation layer based on the application data. You can read more about how presentation layer consumes the application data in [presentation.md | Application Data](./presentation.md#application-data).
|
||||
|
||||
- Application data is parsed to domain object [`Application.ts`](./../src/domain/Application.ts)
|
||||
- Steps
|
||||
1. (Compile time) Load application data from [collection yaml files](./../src/application/collections/) using webpack loader
|
||||
2. (Runtime) Parse and compile application and make it available to presentation layer by [`ApplicationFactory.ts`](./../src/application/ApplicationFactory.ts)
|
||||
Application layer enables [data-driven programming](https://en.wikipedia.org/wiki/Data-driven_programming) by leveraging the data to the rest of the source code. It makes it easy for community to contribute on the project by using a declarative language used in collection files.
|
||||
|
||||
### Compiling
|
||||
### Parsing and compiling
|
||||
|
||||
- Parsing the application files includes compiling scripts using [collection file defined functions](./collection-files.md#function)
|
||||
- To extend the syntax:
|
||||
1. Add a new parser under [SyntaxParsers](./../src/application/Parser/Script/Compiler/Expressions/SyntaxParsers) where you can look at other parsers to understand more.
|
||||
2. Register your in [CompositeExpressionParser](./../src/application/Parser/Script/Compiler/Expressions/Parser/CompositeExpressionParser.ts)
|
||||
Application layer parses the application data to compile the domain object [`Application.ts`](./../src/domain/Application.ts).
|
||||
|
||||
A webpack loader loads (or injects) application data ([collection yaml files](./../src/application/collections/)) into the application layer in compile time. Application layer ([`ApplicationFactory.ts`](./../src/application/ApplicationFactory.ts)) parses and compiles this data in runtime.
|
||||
|
||||
Application layer compiles templating syntax during parsing to create the end scripts. You can read more about templating syntax in [templating.md](./templating.md) and how application data uses them through functions in [collection-files.md | Function](./collection-files.md#function).
|
||||
|
||||
The steps to extend the templating syntax:
|
||||
|
||||
1. Add a new parser under [SyntaxParsers](./../src/application/Parser/Script/Compiler/Expressions/SyntaxParsers) where you can look at other parsers to understand more.
|
||||
2. Register your in [CompositeExpressionParser](./../src/application/Parser/Script/Compiler/Expressions/Parser/CompositeExpressionParser.ts).
|
||||
|
||||
68
docs/architecture.md
Normal file
68
docs/architecture.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# Architecture overview
|
||||
|
||||
This repository consists of:
|
||||
|
||||
- A [layered application](#layered-application).
|
||||
- [AWS infrastructure](#aws-infrastructure) as code and instructions to host the website.
|
||||
- [GitOps](#gitops) practices for development, maintenance and deployment.
|
||||
|
||||
## Layered application
|
||||
|
||||
Application is
|
||||
|
||||
- powered by **TypeScript**, **Vue.js** and **Electron** 💪,
|
||||
- and driven by **Domain-driven design**, **Event-driven architecture**, **Data-driven programming** concepts.
|
||||
|
||||
Application uses highly decoupled models & services in different DDD layers:
|
||||
|
||||
- presentation layer (see [presentation.md](./presentation.md)),
|
||||
- application layer (see [application.md](./application.md)),
|
||||
- and domain layer.
|
||||
|
||||
Application layer depends on and consumes domain layer. [Presentation layer](./presentation.md) consumes and depends on application layer along with domain layer. Application and presentation layers can communicate through domain model.
|
||||
|
||||
|
||||
|
||||
### Application state
|
||||
|
||||
State handling uses an event-driven subscription model to signal state changes and special functions to register changes. It does not depend on third party packages.
|
||||
|
||||
Each layer treat application layer differently.
|
||||
|
||||
|
||||
|
||||
*[Presentation layer](./presentation.md)*:
|
||||
|
||||
- Each component holds their own state about presentation-related data.
|
||||
- Components register shared state changes into application state using functions.
|
||||
- Components listen to shared state changes using event subscriptions.
|
||||
- 📖 Read more: [presentation.md | Application state](./presentation.md#application-state).
|
||||
|
||||
*[Application layer](./application.md)*:
|
||||
|
||||
- Stores the application-specific state.
|
||||
- The state it exposed for read with getter functions and set using setter functions, setter functions also fire application events that allows other parts of application and the view in presentation layer to react.
|
||||
- So state is mutable, and fires related events when mutated.
|
||||
- 📖 Read more: [application.md | Application state](./application.md#application-state).
|
||||
|
||||
It's comparable with flux ([`redux`](https://redux.js.org/)) or flux-like ([`vuex`](https://vuex.vuejs.org/)) patterns. Flux component "view" is [presentation layer](./presentation.md) in Vue. Flux functions "dispatcher", "store" and "action creation" functions lie in the [application layer](./application.md). A difference is that application state in privacy.sexy is mutable and lies in single flux "store" that holds app state and logic. The "actions" mutate the state directly which in turns act as dispatcher to notify its own event subscriptions (callbacks).
|
||||
|
||||
## AWS infrastructure
|
||||
|
||||
The web-site runs on serverless AWS infrastructure. Infrastructure is open-source and deployed as code. [aws-static-site-with-cd](https://github.com/undergroundwires/aws-static-site-with-cd) project includes the source code.
|
||||
|
||||
[](https://github.com/undergroundwires/aws-static-site-with-cd)
|
||||
|
||||
The design priorities highest security then minimizing cloud infrastructure costs.
|
||||
|
||||
This project includes [GitHub Actions](../.github/workflows/) to automatically provision the infrastructure with zero-touch and without any "hidden" steps, ensuring everything is open-source and transparent. Git repositories includes all necessary instructions and automation with [GitOps](#gitops) practices.
|
||||
|
||||
## GitOps
|
||||
|
||||
CI/CD is fully automated using different Git events and GitHub actions. This repository uses [bump-everywhere](https://github.com/undergroundwires/bump-everywhere) to automate versioning, tagging, creation of [`CHANGELOG.md`](./../CHANGELOG.md) and GitHub releases. A dedicated [workflow](./../.github/workflows/release.desktop.yaml) creates desktop installers and executables and attaches them into GitHub releases.
|
||||
|
||||
Everything that's merged in the master goes directly to production.
|
||||
|
||||
📖 Refer to [ci-cd.md](./ci-cd.md) to read more on CI/CD pipelines.
|
||||
|
||||
[](../.github/workflows/)
|
||||
@@ -1,53 +1,63 @@
|
||||
# Presentation layer
|
||||
|
||||
- Consists of Vue.js components and other UI-related code.
|
||||
- Desktop application is created using [Electron](https://www.electronjs.org/).
|
||||
- Event driven as in components simply listens to events from the state and act accordingly.
|
||||
Presentation layer consists of UI-related code. It uses Vue.js as JavaScript framework and includes Vue.js components. It also includes [Electron](https://www.electronjs.org/) to provide functionality to desktop application.
|
||||
|
||||
It's designed event-driven from bottom to top. It listens user events (from top) and state events (from bottom) to update state or the GUI.
|
||||
|
||||
📖 Refer to [architecture.md (Layered Application)](./architecture.md#layered-application) to read more about the layered architecture.
|
||||
|
||||
## Structure
|
||||
|
||||
- [`/src/` **`presentation/`**](./../src/presentation/): Contains all presentation related code including Vue and Electron configurations
|
||||
- [**`bootstrapping/`**](./../src/presentation/bootstrapping/): Registers Vue global objects including components and plugins.
|
||||
- [**`components/`**](./../src/presentation/components/): Contains all Vue components and their helper classes.
|
||||
- [**`Shared/`**](./../src/presentation/components/Shared): Contains Vue components and component helpers that are shared across other components.
|
||||
- [**`assets/`**](./../src/presentation/assets/styles/): Contains assets that will be processed by webpack.
|
||||
- [**`Shared/`**](./../src/presentation/components/Shared): Contains Vue components and component helpers that other components share.
|
||||
- [**`assets/`**](./../src/presentation/assets/styles/): Contains assets that webpack will process.
|
||||
- [**`fonts/`**](./../src/presentation/assets/fonts/): Contains fonts
|
||||
- [**`styles/`**](./../src/presentation/assets/styles/): Contains shared styles used throughout different components.
|
||||
- [**`components/`**](./../src/presentation/assets/styles/components): Contains styles that are reusable and tightly coupled a Vue/HTML component.
|
||||
- [**`components/`**](./../src/presentation/assets/styles/components): Contains reusable styles coupled to a Vue/HTML component.
|
||||
- [**`vendors-extensions/`**](./../src/presentation/assets/styles/third-party-extensions): Contains styles that override third-party components used.
|
||||
- [**`main.scss`**](./../src/presentation/assets/styles/main.scss): Primary Sass file, passes along all other styles, should be the only file used from other components.
|
||||
- [**`main.scss`**](./../src/presentation/assets/styles/main.scss): Primary Sass file, passes along all other styles, should be the single file used from other components.
|
||||
- [**`main.ts`**](./../src/presentation/main.ts): Application entry point that mounts and starts Vue application.
|
||||
- [**`electron/`**](./../src/presentation/electron/): Electron configuration for the desktop application.
|
||||
- [**`main.ts`**](./../src/presentation/main.ts): Main process of Electron, started as first thing when app starts.
|
||||
- [**`/public/`**](./../public/): Contains static assets that will directly be copied and not go through webpack.
|
||||
- [**`/vue.config.js`**](./../vue.config.js): Global Vue CLI configurations loaded by `@vue/cli-service`
|
||||
- [**`/postcss.config.js`**](./../postcss.config.js): PostCSS configurations that are used by Vue CLI internally
|
||||
- [**`/babel.config.js`**](./../babel.config.js): Babel configurations for polyfills used by `@vue/cli-plugin-babel`
|
||||
- [**`/public/`**](./../public/): Contains static assets that are directly copied and do not go through webpack.
|
||||
- [**`/vue.config.js`**](./../vue.config.js): Global Vue CLI configurations loaded by `@vue/cli-service`.
|
||||
- [**`/postcss.config.js`**](./../postcss.config.js): PostCSS configurations used by Vue CLI internally.
|
||||
- [**`/babel.config.js`**](./../babel.config.js): Babel configurations for polyfills used by `@vue/cli-plugin-babel`.
|
||||
|
||||
## Application data
|
||||
|
||||
- Components and should use [ApplicationFactory](./../src/application/ApplicationFactory.ts) singleton to reach the application domain.
|
||||
- [Application.ts](../src/domain/Application.ts) domain model is the stateless application representation including
|
||||
- available scripts, collections as defined in [collection files](./collection-files.md)
|
||||
- package information as defined in [`package.json`](./../package.json)
|
||||
- 📖 See [Application data | Application layer](./presentation.md#application-data) where application data is parsed and compiled.
|
||||
Components (should) use [ApplicationFactory](./../src/application/ApplicationFactory.ts) singleton to reach the application domain to avoid [parsing and compiling](./application.md#parsing-and-compiling) the application again.
|
||||
|
||||
[Application.ts](../src/domain/Application.ts) is an immutable domain model that represents application state. It includes:
|
||||
|
||||
- available scripts, collections as defined in [collection files](./collection-files.md),
|
||||
- package information as defined in [`package.json`](./../package.json).
|
||||
|
||||
You can read more about how application layer provides application data to he presentation in [application.md | Application data](./application.md#application-data).
|
||||
|
||||
## Application state
|
||||
|
||||
- Stateful components mutate or/and react to state changes in [ApplicationContext](./../src/application/Context/ApplicationContext.ts).
|
||||
- Stateless components that does not handle state extends `Vue`
|
||||
- Stateful components that depends on the collection state such as user selection, search queries and more extends [`StatefulVue`](./../src/presentation/components/Shared/StatefulVue.ts)
|
||||
- The single source of truth is a singleton of the state created and made available to presentation layer by [`StatefulVue`](./../src/presentation/components/Shared/StatefulVue.ts)
|
||||
- `StatefulVue` includes abstract `handleCollectionState` that is fired once the component is loaded and also each time [collection](./collection-files.md) is changed.
|
||||
- Do not forget to subscribe from events when component is destroyed or if needed [collection](./collection-files.md) is changed.
|
||||
- 💡 `events` in base class [`StatefulVue`](./../src/presentation/components/Shared/StatefulVue.ts) makes lifecycling easier
|
||||
- 📖 See [Application state | Application layer](./presentation.md#application-state) where the state is implemented using using state pattern.
|
||||
Inheritance of a Vue components marks whether it uses application state . Components that does not handle application state extends `Vue`. Stateful components mutate or/and react to state changes (such as user selection or search queries) in [ApplicationContext](./../src/application/Context/ApplicationContext.ts) extend [`StatefulVue`](./../src/presentation/components/Shared/StatefulVue.ts) class to access the context / state.
|
||||
|
||||
[`StatefulVue`](./../src/presentation/components/Shared/StatefulVue.ts) functions include:
|
||||
|
||||
- Creating a singleton of the state and makes it available to presentation layer as single source of truth.
|
||||
- Providing virtual abstract `handleCollectionState` callback that it calls when
|
||||
- the Vue loads the component,
|
||||
- and also every time when state changes.
|
||||
- Providing `events` member to make lifecycling of state subscriptions events easier because it ensures that components unsubscribe from listening to state events when
|
||||
- the component is no longer used (destroyed),
|
||||
- an if [ApplicationContext](./../src/application/Context/ApplicationContext.ts) changes the active [collection](./collection-files.md) to a different one.
|
||||
|
||||
📖 Refer to [architecture.md | Application State](./architecture.md#application-state) to get an overview of event handling and [application.md | Application State](./presentation.md#application-state) for deeper look into how the application layer manages state.
|
||||
|
||||
## Modals
|
||||
|
||||
- [Dialog.vue](./../src/presentation/components/Shared/Dialog.vue) is a shared component that can be used to show modal windows
|
||||
- Simply wrap the content inside of its slot and call `.show()` method on its reference.
|
||||
- Example:
|
||||
[Dialog.vue](./../src/presentation/components/Shared/Dialog.vue) is a shared component that other components used to show modal windows.
|
||||
|
||||
You can use it by wrapping the content inside of its `slot` and call `.show()` function on its reference. For example:
|
||||
|
||||
```html
|
||||
<Dialog ref="testDialog">
|
||||
@@ -58,15 +68,15 @@
|
||||
|
||||
## Sass naming convention
|
||||
|
||||
- Use lowercase for variables/functions/mixins e.g.
|
||||
- Use lowercase for variables/functions/mixins, e.g.:
|
||||
- Variable: `$variable: value;`
|
||||
- Function: `@function function() {}`
|
||||
- Mixin: `@mixin mixin() {}`
|
||||
- Use - for a phrase/compound word e.g.
|
||||
- Use - for a phrase/compound word, e.g.:
|
||||
- Variable: `$some-variable: value;`
|
||||
- Function: `@function some-function() {}`
|
||||
- Mixin: `@mixin some-mixin() {}`
|
||||
- Grouping and name variables from generic to specific e.g.
|
||||
- Grouping and name variables from generic to specific, e.g.:
|
||||
- ✅ `$border-blue`, `$border-blue-light`, `$border-blue-lightest`, `$border-red`
|
||||
- ❌ `$blue-border`, `$light-blue-border`, `$lightest-blue-border`, `$red-border`
|
||||
|
||||
Reference in New Issue
Block a user