mirror of
https://github.com/AppFlowy-IO/AppFlowy.git
synced 2024-08-30 18:12:39 +00:00
Removed duplicate documentation now found on Gitbook
CONTRIBUTING.md now points to Gitbook
This commit is contained in:
MikeWallaceDev
parent
44af890f05
commit
1cd1d49c07
@ -1,26 +0,0 @@
|
||||
# About
|
||||
|
||||
AppFlowy is an open-source Notion alternative.
|
||||
You are in charge of your data and customizations.
|
||||
|
||||
## Built for teams that need more control and flexibility
|
||||
### 100% data control
|
||||
* You can host AppFlowy wherever you want; no vendor lock-in.
|
||||
### Unlimited customizations
|
||||
* Design and modify AppFlowy your way with an open core codebase.
|
||||
### One codebase supporting multiple platforms
|
||||
* AppFlowy is built with Flutter and Rust. What does this mean? Faster development, better native experience, and more reliable performance.
|
||||
|
||||
## Built for individuals who care about data security and mobile experience
|
||||
### 100% control of your data
|
||||
* Download and install AppFlowy on your local machine. You own and control your personal data.
|
||||
### Extensively extensible
|
||||
* For those with no coding experience, AppFlowy enables you to create apps that suit your needs. It's built on a community-driven toolbox, including templates, plugins, themes, and more.
|
||||
### Truely native experience
|
||||
* Faster, more stable with support for offline mode. It's also better integrated with different devices. Moreover, AppFlowy enables users to access features and possibilities not available on the web.
|
||||
|
||||
## Community for hackers | Community for creators | Community for builders
|
||||
### Let’s democratize the knowledge and wheels of making complex workplace collaboration tools
|
||||
* It takes tremendous resources and expertise to build a great collaborative productivity tool. Don’t reinvent the wheels, let’s create the best open-source building blocks as infra to power others.
|
||||
### We collaboratively create apps that suit others’ needs by developing a versatile toolbox of plugins, templates, and more
|
||||
* Join us to build a toolbox that empowers anyone to create their own system - play and tweak without a glass ceiling on what’s possible.
|
||||
@ -1,71 +0,0 @@
|
||||
# 🥳 AppFlowy - Event Driven System
|
||||
|
||||
* [Goals of the System](#goals-of-the-system)
|
||||
* [Some Design Considerations](#some-design-Considerations)
|
||||
* [High Level Design](#high-level-design)
|
||||
* [Component Design](#component-design)
|
||||
|
||||
## 🎯 Goals of the System
|
||||
The AppFlowy project is an attempt to build a high performance application. Here are the top-level requirements for our system.
|
||||
|
||||
1. **High Performance.**
|
||||
2. **Cross-platform.**
|
||||
3. **Reliability.**
|
||||
4. **Safety.**
|
||||
|
||||
|
||||
## 🤔 Some Design Considerations
|
||||
|
||||
## 📜 High Level Design
|
||||
|
||||
## 📚 Component Design
|
||||
|
||||
### 📙 Event Dispatch
|
||||
|
||||
```
|
||||
Frontend FLowySDK
|
||||
│ ┌─────────┐
|
||||
│ ┌7─▶│Handler A│
|
||||
│ │ └─────────┘
|
||||
│ ┌─────────┐ │ ┌─────────┐
|
||||
┌──────┐ ┌────┐ ┌──────────────┐ │ ┌───▶│Module A │──┼──▶│Handler B│
|
||||
│Widget│─1─▶│Bloc│─2─▶│ Repository A │─3─┐ │ │ └─────────┘ │ └─────────┘
|
||||
└──────┘ └────┘ └──────────────┘ │ │ │ │ ┌─────────┐
|
||||
┌──────────────┐ │ ┌───────┐ ┌─┴──┐ ┌───────────┐ │ ┌─────────┐ └──▶│Handler C│
|
||||
│ Repository B │───┼───▶│ Event │─4─▶│FFI │─5──▶│Dispatcher │─6─┼───▶│Module B │ └─────────┘
|
||||
└──────────────┘ │ └───────┘ └─┬──┘ └───────────┘ │ └─────────┘
|
||||
┌──────────────┐ │ │ │
|
||||
│ Repository C │───┘ │ │ ┌─────────┐
|
||||
└──────────────┘ │ └───▶│Module C │
|
||||
│ └─────────┘
|
||||
│
|
||||
│
|
||||
```
|
||||
Here is the event flow:
|
||||
1. User click on the `Widget`(The user interface) that invokes the `Bloc` actions
|
||||
2. `Bloc` calls the repositories to perform additional operations to handle the actions.
|
||||
3. `Repository` offers the functionalities by combining the event, defined in the `FlowySDK`.
|
||||
4. `Events` will be passed in the `FlowySDK` through the [FFI](https://en.wikipedia.org/wiki/Foreign_function_interface) interface.
|
||||
5. `Dispatcher` parses the event and generates the specific action scheduled in the `FlowySDK` runtime.
|
||||
6. `Dispatcher` find the event handler declared by the modules.
|
||||
7. `Handler` consumes the event and generates the response. The response will be returned to the widget through the `FFI`.
|
||||
|
||||
The event flow will be discussed in two parts: the frontend implemented in flutter and the FlowySDK implemented in Rust.
|
||||
|
||||
#### FlowySDK
|
||||
|
||||
|
||||
|
||||
#### Frontend
|
||||
The Frontend follows the DDD design pattern, you can recap from [**here**](DOMAIN_DRIVEN_DESIGN.md).
|
||||
```
|
||||
┌──────┐ ┌────┐ ┌──────────────┐
|
||||
│Widget│──1────▶│Bloc│──2────▶│ Repository A │─3──┐
|
||||
└──────┘ └────┘ └──────────────┘ │
|
||||
┌──────────────┐ │ ┌───────┐
|
||||
│ Repository B │────┼────▶│ Event │
|
||||
└──────────────┘ │ └───────┘
|
||||
┌──────────────┐ │
|
||||
│ Repository C │────┘
|
||||
└──────────────┘
|
||||
```
|
||||
@ -1,153 +0,0 @@
|
||||
# How to build on Linux, please follow these simple steps.
|
||||
|
||||
Note:
|
||||
* The following steps are verified on
|
||||
- [x] lubuntu 20.04 - X86_64
|
||||
- [ ] ubuntu 20.04 - aarch64
|
||||
- [ ] redhat - X86_64
|
||||
- [x] Arch Linux - X86_64
|
||||
- [ ] Deepin - X86_64
|
||||
- [ ] Raspberry Pi OS - aarch64
|
||||
* You may need to disable hardware 3D acceleration if you are running AppFlowy in a VM. Otherwise, certain GL failures will prevent the app from launching.
|
||||
|
||||
|
||||
## Step 1: Install your build environment
|
||||
------------------------------
|
||||
There's no point continuing if this doesn't work for you. Feel free to ask questions on our Discord so that we may refire this document and make the process as easy as possible for you.
|
||||
|
||||
1. Install system prerequisites
|
||||
```shell
|
||||
#Ubuntu
|
||||
sudo apt-get install curl build-essential libsqlite3-dev libssl-dev clang cmake ninja-build pkg-config libgtk-3-dev unzip
|
||||
# optional, for generating protobuf in step 8 only
|
||||
sudo apt-get install protobuf-compiler
|
||||
```
|
||||
```shell
|
||||
#Arch
|
||||
yay -S curl base-devel sqlite openssl clang cmake ninja pkg-config gtk3 unzip
|
||||
# optional, for generating protobuf in step 8 only
|
||||
#(Caution: protobuf does not work on Arch at the moment.)
|
||||
#yay -S protobuf-compiler
|
||||
```
|
||||
|
||||
2. Install rust on Linux
|
||||
```shell
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
source $HOME/.cargo/env
|
||||
rustup toolchain install stable
|
||||
rustup default stable
|
||||
```
|
||||
|
||||
3. Install flutter according to https://docs.flutter.dev/get-started/install/linux
|
||||
```shell
|
||||
git clone https://github.com/flutter/flutter.git
|
||||
cd flutter
|
||||
echo "export PATH=\$PATH:"`pwd`"/bin" >> ~/.profile
|
||||
export PATH="$PATH:`pwd`/bin"
|
||||
flutter channel stable
|
||||
```
|
||||
4. Enable linux desktop
|
||||
```
|
||||
flutter config --enable-linux-desktop
|
||||
```
|
||||
5. Fix any problems reported by flutter doctor
|
||||
```shell
|
||||
flutter doctor
|
||||
```
|
||||
|
||||
## Step 2: Get the source code
|
||||
------------------------------
|
||||
|
||||
```shell
|
||||
git clone https://github.com/AppFlowy-IO/appflowy.git
|
||||
```
|
||||
|
||||
However, you should fork the code instead if you wish to submit patches.
|
||||
|
||||
## Step 3: Build app_flowy (Flutter GUI application)
|
||||
------------------------------
|
||||
|
||||
1. Change to the frontend directory
|
||||
```shell
|
||||
cd [appflowy/]frontend
|
||||
```
|
||||
2. Install cargo make
|
||||
```shell
|
||||
cargo install --force cargo-make
|
||||
```
|
||||
3. Install duckscript
|
||||
```shell
|
||||
cargo install --force duckscript_cli
|
||||
```
|
||||
4. Check prerequisites
|
||||
```shell
|
||||
cargo make flowy_dev
|
||||
```
|
||||
5. [Optional] Generate protobuf for dart (if you wish to modify the shared-lib's entities)
|
||||
```shell
|
||||
# Caution : Not working on Arch Linux yet
|
||||
# Make sure to install protobuf-compiler at first. See step 1
|
||||
cargo make -p development-linux-x86 pb
|
||||
```
|
||||
6. [Optional] Build flowy-sdk-dev (dart-ffi)
|
||||
```shell
|
||||
# for development
|
||||
cargo make --profile development-linux-x86 flowy-sdk-dev
|
||||
|
||||
# for production
|
||||
cargo make --profile production-linux-x86 flowy-sdk-release
|
||||
```
|
||||
|
||||
7. Build app_flowy
|
||||
```shell
|
||||
# for development
|
||||
cargo make -p development-linux-x86 appflowy-linux-dev
|
||||
|
||||
# for production, find binary from app_flowy/product/<version>/linux/<build type>/AppFlowy/
|
||||
cargo make -p production-linux-x86 appflowy-linux
|
||||
```
|
||||
|
||||
## Step 4: Run the application
|
||||
------------------------------
|
||||
|
||||
```
|
||||
cd [frontend/]app_flowy/product/0.0.2/linux/Debug/AppFlowy/app_flowy
|
||||
./app_flowy
|
||||
```
|
||||
# run Linux GUI application through x11 on windows (use MobaXterm)
|
||||
# for instance:
|
||||
# export DISPLAY=localhost:10
|
||||
|
||||
## Step 5: Edit and run the application
|
||||
[VS Code]
|
||||
1. Open the app_flowy folder located at xx/appflowy/frontend/app_flowy with VS Code.
|
||||
|
||||
2. Edit the frontend/scripts/build_sdk.sh file and select the correct script by commenting out the macos line and uncommenting the correct Linux line.
|
||||
|
||||
```shell
|
||||
# for macOS
|
||||
#cargo make --profile development-mac flowy-sdk-dev
|
||||
|
||||
# for Windows
|
||||
#cargo make --profile development-windows flowy-sdk-dev
|
||||
|
||||
# for Linux x86
|
||||
cargo make --profile development-linux-x86 flowy-sdk-dev
|
||||
|
||||
# for Linux aarch64
|
||||
#cargo make --profile development-linux-aarch64 flowy-sdk-dev
|
||||
```
|
||||
|
||||
3. Go to the Run and Debug tab and then click the run button.
|
||||
|
||||
|
||||
* If you encounter any issues, have a look at [Troubleshooting](https://github.com/AppFlowy-IO/appflowy/wiki/Troubleshooting) first. If your issue is not included in the page, please create an [issue](https://github.com/AppFlowy-IO/appflowy/issues/new/choose) or ask on [Discord](https://discord.gg/9Q2xaN37tV).
|
||||
|
||||
------------------------------
|
||||
|
||||
## [TBD] Step 6: Build Server side application (if you need to host web service locally)
|
||||
------------------------------
|
||||
|
||||
Note: You can launch postgresql server by using docker container
|
||||
|
||||
TBD
|
||||
@ -1,77 +0,0 @@
|
||||
## How to build on Windows, please follow these simple steps.
|
||||
|
||||
## Step 1: Get source code
|
||||
------------------------------
|
||||
|
||||
```shell
|
||||
git clone https://github.com/AppFlowy-IO/appflowy.git
|
||||
```
|
||||
|
||||
## Step 2: Build app_flowy (Flutter GUI application)
|
||||
------------------------------
|
||||
|
||||
Note:
|
||||
* Both Windows cmd and powershell can be used for running commands
|
||||
* Following steps are verified on
|
||||
- [ ] Windows 10 X86_64
|
||||
- [ ] Windows 10 arm64
|
||||
- [ ] Windows 11 X86_64
|
||||
- [ ] Windows 11 arm64
|
||||
|
||||
### Detail steps
|
||||
1. Install Visual Studio 2022 build tools. Download from https://visualstudio.microsoft.com/downloads/
|
||||
- In section of "All Downloads" => "Tools for Visual Studio 2022" => Build Tools for Visual Studio 2022, hit Download button to get it.
|
||||
- Launch "vs_BuildTools.exe" to install
|
||||
2. Install vcpkg according to https://github.com/microsoft/vcpkg#quick-start-windows. Make sure to add vcpkg installation folder to PATH env var.
|
||||
3. Install flutter according to https://docs.flutter.dev/get-started/install/windows
|
||||
```shell
|
||||
flutter channel stable
|
||||
flutter doctor
|
||||
```
|
||||
4. Install rust
|
||||
```shell
|
||||
# Download rustup.exe from https://win.rustup.rs/x86_64
|
||||
# Call rustup.exe from powershell or cmd
|
||||
.\rustup-init.exe --default-toolchain stable --default-host x86_64-pc-windows-msvc -y
|
||||
# Note: you probably need to re-open termial to get cargo command be available in PATH var
|
||||
```
|
||||
5. Install cargo make
|
||||
```shell
|
||||
cd appflowy/frontend
|
||||
cargo install --force cargo-make
|
||||
```
|
||||
6. Install duckscript
|
||||
```shell
|
||||
cargo install --force duckscript_cli
|
||||
```
|
||||
7. Check prerequisites
|
||||
```shell
|
||||
cargo make flowy_dev
|
||||
```
|
||||
8. [Optional] Generate protobuf for dart (optional, if you modify the shared-lib's entities)
|
||||
```shell
|
||||
# Need to download protoc tools and add it's bin folder into PATH env var.
|
||||
# Download protoc from https://github.com/protocolbuffers/protobuf/releases. The latest one is protoc-3.19.1-win64.zip
|
||||
cargo make -p development-windows pb
|
||||
```
|
||||
9. [Optional] Build flowy-sdk (dart-ffi), step 10 covers this step
|
||||
```shell
|
||||
# for development
|
||||
cargo make --profile development-windows-x86 flowy-sdk-dev
|
||||
# for production
|
||||
cargo make --profile production-windows-x86 flowy-sdk-release
|
||||
```
|
||||
10. Build app_flowy
|
||||
```shell
|
||||
# for development
|
||||
cargo make -p development-windows-x86 appflowy-windows-dev
|
||||
# for production
|
||||
cargo make -p production-windows-x86 appflowy-windows
|
||||
```
|
||||
|
||||
## [Optional] Step 3: Build Server side application (optional if you don't need to host web service locally)
|
||||
------------------------------
|
||||
|
||||
Note: You can launch postgresql server by using docker container
|
||||
|
||||
TBD
|
||||
@ -1,97 +1,7 @@
|
||||
<p align="center"><img src="imgs/appflowy_title_and_logo.png" alt="The Open Source Notion Alternative." width="500px" /></p>
|
||||
|
||||
|
||||
# Contributing to AppFlowy
|
||||
|
||||
Hello, and welcome! Whether you are trying to report a bug, proposing a feature request, thinking about getting involved in the project, or submitting a patch, this document is for you! It intends to be both an entry point for newcomers to AppFlowy's community (with various backgrounds), and a guide/reference for contributors.
|
||||
Hello, and welcome! Whether you are trying to report a bug, proposing a feature request, or want to work on the code you should go visit [our documentation](https://appflowy.gitbook.io)
|
||||
|
||||
Consult the Table of Contents below, and jump to the desired section.
|
||||
|
||||
## Table of Contents
|
||||
- [Contributing](#contributing)
|
||||
- [Feedback](#feedback)
|
||||
- [Non-coding Contributions](#non-coding-contributions)
|
||||
- [Coding Contributions](#coding-contributions)
|
||||
- [Sponsor](#sponsor)
|
||||
- [Contributor T-shirt](#contributor-t-shirt)
|
||||
- [Code of Conduct](#code-of-conduct)
|
||||
- [Sign the CLA Agreement](#sign-the-cla-agreement)
|
||||
|
||||
|
||||
## Contributing
|
||||
There are many ways in which you can contribute to the project. You can be involved just a little, or a whole lot! Every lit bit helps and is very appreciated by everyone.
|
||||
|
||||
### Feedback
|
||||
|
||||
Not feeling quite up to working on the project yet? Tell us your suggestions!
|
||||
- Submit [feature requests](https://github.com/AppFlowy-IO/appflowy/issues). We'd love to hear your ideas!
|
||||
- Report [bugs](https://github.com/AppFlowy-IO/appflowy/issues). This really helps a lot!
|
||||
- Provide your suggestions on the [forum](https://github.com/AppFlowy-IO/appflowy/discussions)
|
||||
- Review [Pull Requests](https://github.com/AppFlowy-IO/appflowy/pulls)
|
||||
- Provide feedback to [proposed features](https://github.com/AppFlowy-IO/appflowy/issues)
|
||||
|
||||
[Back to TOC](#table-of-contents)
|
||||
|
||||
### Non-coding Contributions
|
||||
|
||||
You want to work on the project, but you're not a developer? You can help in multiple ways - even if you don't write code! You can still give back your love to our community. Here are a few ideas:
|
||||
|
||||
- Answer questions having ""General help wanted" or "Technical help wanted" labels on the [forum](https://github.com/AppFlowy-IO/appflowy/discussions)
|
||||
- Improve the documentation.
|
||||
- Be an AppFlowy ambassador or evangelist! Proprietary software companies often have dedicated marketing teams to get more users, but luckily we have something better: you! Share your experience with AppFlowy! This can be anything:
|
||||
- Write a life-hacks-style blog post on how you or your company use AppFlowy to get things done.
|
||||
- Spread the word on all social media platforms to get more people to join the community. To name a few channels, Product Hunt, Hacker Noon, Quora, Reddit, and Stack Overflow are good choices.
|
||||
- Give a lightning talk at your local hackerspace on why you love AppFlowy.
|
||||
- Write a review of the pros and cons of similar open source apps.
|
||||
|
||||
[Back to TOC](#table-of-contents)
|
||||
|
||||
### Coding Contributions
|
||||
|
||||
So you want to submit code, documentation, or graphical expertise? Welcome to the club! We will try to give you all the help you need to get up and running.
|
||||
- Join our [Discord](https://discord.com/invite/9Q2xaN37tV). Here you will be able to chat with all of our contributors and the heads of the project.
|
||||
- Read the documentation. You should start at the main README.md where you will find information on how to setup your computer to develop with Flutter and Rust.
|
||||
- Read the technical wiki. This is where you will find all of our design documentation. (TBD)
|
||||
- Submit a Patch. We love to receive Pull Requests. If you are a beginner or a newcomer, here are some tasks for you to get ramped up:
|
||||
- Fix a typo in the code.
|
||||
- Fix a typo in the documentation.
|
||||
- Awesome issues for [beginners or newcomers](https://github.com/AppFlowy-IO/appflowy/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue+for+devs%22).
|
||||
- Provide feedback [proposed features](https://github.com/AppFlowy-IO/appflowy/issues)
|
||||
- Review [Pull Requests](https://github.com/AppFlowy-IO/appflowy/pulls)
|
||||
- If you are ready to code (maybe a lot), please submit a [patch](https://github.com/AppFlowy-IO/appflowy/pulls)!
|
||||
- (WIP: guidelines)
|
||||
- (WIP: Code Style)
|
||||
|
||||
[Back to TOC](#table-of-contents)
|
||||
|
||||
## Sponsor
|
||||
|
||||
Sponsoring is another great way to contribute to the community.
|
||||
- Buy us a coffee on [ko-fi](https://ko-fi.com/appflowy)
|
||||
|
||||
[Back to TOC](#table-of-contents)
|
||||
|
||||
## Contributor T-Shirt
|
||||
|
||||
If your Pull Request was accepted as it fixes a bug, adds functionality, or makes AppFlowy's codebase significantly easier to use or understand, congratulations! You are now an official contributor to AppFlowy. Get in touch with us ([link](https://tally.so/r/mKP5z3)) to receive the very special Contributor T-shirt!
|
||||
|
||||
Proudly wear your T-shirt and show it to us by tagging [@appflowy](https://twitter.com/appflowy) on Twitter.
|
||||
|
||||
[Back to TOC](#table-of-contents)
|
||||
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
Please report a code of conduct violation to annie@appflowy.io.
|
||||
Let's encourage the behavior we want to see in the world and constantly foster a welcoming environment!
|
||||
|
||||
[Contributor Covenant](https://www.contributor-covenant.org/version/2/0/code_of_conduct/)
|
||||
|
||||
|
||||
[Back to TOC](#table-of-contents)
|
||||
|
||||
## Sign the CLA Agreement
|
||||
|
||||
TBD
|
||||
|
||||
[Back to TOC](#table-of-contents)
|
||||
We look forward to hearing from you!
|
||||
|
||||
@ -1,238 +0,0 @@
|
||||
|
||||
# 🍔 Domain Driven Design
|
||||
|
||||
For many architects, the process of data modeling is driven by intuition. However, there are well-formulated methodologies
|
||||
for approaching it more formally. I recommend the [Domain-Driven Design](https://en.wikipedia.org/wiki/Domain-driven_design)
|
||||
and choose it as AppFlowy architecture.
|
||||
|
||||
## 💥 Layered architecture
|
||||
The most common architecture pattern is the layered architecture pattern, known as the n-tier architecture pattern.
|
||||
Partition the software into `layers` to reduce the complexity. Each layer of the layered architecture pattern has a
|
||||
specific role and responsibility.`DDD` consists of four layers.
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────┐ ─────────▶
|
||||
│ Presentation Layer │──┐ Dependency
|
||||
└──────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
▼ │
|
||||
┌──────────────────────────────────────────────────┐ │
|
||||
│ Application Layer │ │
|
||||
└──────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
▼ │
|
||||
┌──────────────────────────────────────────────────┐ │
|
||||
│ Domain Layer │◀─┘
|
||||
└──────────────────────────────────────────────────┘
|
||||
▲
|
||||
│
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ Infrastructure Layer │
|
||||
└──────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Presentation Layer**:
|
||||
* Responsible for presenting information to the user and interpreting user commands.
|
||||
* Consists of Widgets and also the state of the Widgets.
|
||||
|
||||
**Application Layer**:
|
||||
* Defines the jobs the software is supposed to do. (Shouldn't find any UI code or network code)
|
||||
* Coordinates the application activity and delegates work to the next layer down.
|
||||
* It doesn't contain any complex business logic but the basic validation on the user input before
|
||||
passing to the other layer.
|
||||
|
||||
**Domain Layer**:
|
||||
* Responsible for representing concepts of the business.
|
||||
* Manages the business state or delegated to the infrastructure layer.
|
||||
* Self contained and it doesn't depend on any other layers. Domain should be well isolated from the
|
||||
other layers.
|
||||
|
||||
**Infrastructure Layer**:
|
||||
|
||||
* Provides generic technical capabilities that support the higher layers. It deals with APIs, persistence and network, etc.
|
||||
* Implements the repository interface and hides the complexity of the Domain layer.
|
||||
|
||||
As you see, the `Complexity` and `Abstraction` of these layers are depicted in the following diagram. Software system are composed in layers,
|
||||
where higher layers use the facilities provided by lower layers. Each layer provides a different abstraction from the layer above
|
||||
and below it. As developers, we should pull the complexity downwards. Simple interfaces and powerful implementations (Think about the
|
||||
[open](https://man7.org/linux/man-pages/man2/open.2.html) function). Another way of expressing this idea is that it is more important
|
||||
for a module to have a simple interface than a simple implementation.
|
||||
|
||||
|
||||
```
|
||||
▲
|
||||
│
|
||||
Level of ├───────────────────┐
|
||||
Abstraction │ Presentation │
|
||||
├───────────────────┴───────┐
|
||||
│ Application │
|
||||
├───────────────────────────┴─────────┐
|
||||
│ Domain │
|
||||
├─────────────────────────────────────┴────────┐
|
||||
│ Infrastructure │
|
||||
└──────────────────────────────────────────────┴─────▶
|
||||
Complexity
|
||||
```
|
||||
|
||||
|
||||
### Data Model
|
||||
DDD classifies data as referenceable objects, or entities, and non-referenceable objects, or value objects. Let's introduce some DDD terminology.
|
||||
|
||||
**Entity**
|
||||
|
||||
`Entities` are plain objects that carry an identity which allows us to reference them. e.g. user, order, book, etc.
|
||||
You use `entities` to express your business model and encapsulate them into Factory that provides a simple API to create Entities.
|
||||
|
||||
**Value Object**
|
||||
|
||||
`Value Object` can't be referenced. They can be only included into entities and serve as attributes. Value objects could be simple and treat as immutable. e.g. email, phone number, name, etc.
|
||||
|
||||
**Aggregate**
|
||||
|
||||
`Entities` and `Value objects` can be grouped into aggregates. Aggregates can simplify the model by accessing the entire aggregate.
|
||||
For instance, Table has lots of rows. Each row using the table_id to reference to the
|
||||
table. TableAggregate includes two entities: Table and the Row.
|
||||
|
||||
```
|
||||
TableAggregate
|
||||
┌────────────────────────────────────────────────────────────────┐
|
||||
│ │
|
||||
│ ┌────────────────────┐ ┌─────────────────────────┐ │
|
||||
│ │struct Table { │ │struct Row { │ │
|
||||
│ │ id: String, │ │ table_id: String, │ │
|
||||
│ │ desc: String, │◀▶───────│} │ │
|
||||
│ │} │ │ │ │
|
||||
│ └────────────────────┘ └─────────────────────────┘ │
|
||||
│ │
|
||||
└────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Service**
|
||||
|
||||
When a significant process of transformation in the domain is not a natural responsibility of an `Entity` or `Value object`, add an operation to the model as standalone interface declared as a Service. For instance: The `Value object` EmailAddress uses the function `validateEmailAddress` to verify if the email address is valid or not. `Service` exists in Application, Domain and Infrastructure.
|
||||
|
||||
```
|
||||
class EmailAddress {
|
||||
final Either<Failure<String>, String> value;
|
||||
|
||||
factory EmailAddress(String? input) {
|
||||
return EmailAddress._(
|
||||
validateEmailAddress(input),
|
||||
);
|
||||
}
|
||||
|
||||
const EmailAddress._(this.value);
|
||||
}
|
||||
|
||||
|
||||
Either<Failure<String>, String> validateEmailAddress(String? input) {
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
**Repository**
|
||||
|
||||
Repositories offer an interface to retrieve and persist aggregates and entities. They hide the database or network details from the domain.
|
||||
|
||||
Repository interfaces are declared in the Domain Layer, but the repositories themselves are implemented in the Infrastructure Layer.
|
||||
You can replace the interface implementation without impacting the domain layer.
|
||||
|
||||
For instance:
|
||||
|
||||
```
|
||||
// Interface:
|
||||
abstract class AuthInterface {
|
||||
...
|
||||
}
|
||||
|
||||
// Implementation
|
||||
class AuthRepository implements AuthInterface {
|
||||
...
|
||||
}
|
||||
```
|
||||
> More often than not, the repository interface can be divided into sub-repository in order to reduce the complexity.
|
||||
|
||||
### Relation
|
||||
The diagram below is a navigational map. It shows the patterns that form the building blocks of Domain Driven Design and how they relate to each other.
|
||||
](imgs/domain_model_relation.png)
|
||||
|
||||
|
||||
## Operation Flow
|
||||
|
||||
```
|
||||
|
||||
presentation │ Application domain Infrastructure
|
||||
│ │
|
||||
7 Data Model
|
||||
┌──────────────────────────────┐ │ ┌────────────────────────┐ │ ┌─────────────────────┐
|
||||
│ │ │ │ ┌─────────────┐ │ │ Network Service │
|
||||
▼ Bloc │ │ │ │ Aggregate │ │ │ └─────────────────────┘
|
||||
┌─────────────┐ │ ┌─────────────────┴─────┐ │ └─────────────┘ │ ▲
|
||||
────────▶ Widget │ │ ┌────────┐ ┌────────┐ │ 2 │ ┌────────┐ │ │ │ 6
|
||||
└─────────────┘ │ │ │ Event │ │ State │ │────┬───▶│ │ Entity │ │ ┌─────────────────────┐
|
||||
User │ │ └────────┘ └────────┘ │ │ │ │ └────────┘ │ │ │ Persistence Service │
|
||||
interaction │ │ └──────▲────────────────┘ │ │ ┌─────────────────┐ │ └─────────────────────┘
|
||||
│ │ │ │ │ │ Value Object │ │ │ ▲
|
||||
└──────────┼────────┘ │ │ └─────────────────┘ │ │ 5
|
||||
1 │ │ └────────────◈───────────┘ │ ┌─────────────────────┐
|
||||
│ │ │contain │ Unit of Work │
|
||||
│ │ ┌────────────────────┐ │ └─────────────────────┘
|
||||
│ │ │ Service │ ▲
|
||||
│ │ └────────────────────┘ │ │
|
||||
│ │ │ 4
|
||||
│ │ Repository │ │
|
||||
│ │ ┌─────────────────────────────────────────────┴───────────────┐
|
||||
│ │ │ ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐ 3 ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐ │
|
||||
│ └───┤ Interface ────▶ Implementation │
|
||||
│ │ └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘ └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘ │
|
||||
│ └─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
```
|
||||
|
||||
|
||||
1. Widget accepts user interaction and translates the interactions into specific Events. The events will be sent to the Application layer, handled by the specific `bloc`. The `bloc` sends the states changed by the events back to the widget, and finally the `Widget` updates the UI according to the state. The pattern is depicted in this diagram. (More about the flutter [bloc](https://bloclibrary.dev/#/coreconcepts?id=bloc))
|
||||
```
|
||||
┌──────────── State ────────────┐
|
||||
│ │
|
||||
▼ Bloc │
|
||||
┌─────────────┐ ┌─────────────┼─────────┐
|
||||
────────▶│ Widget │ │ ┌────────┐ ┌┴───────┐ │
|
||||
└─────────────┘ │ │ Event │ │ State │ │
|
||||
User interaction │ │ └────────┘ └────────┘ │
|
||||
│ └───────────────────────┘
|
||||
│ ▲
|
||||
│ │
|
||||
└────────── Event ────────────┘
|
||||
|
||||
```
|
||||
|
||||
2. The `bloc` processes the events using the services provided by the `Domain` layer.
|
||||
1. Convert DTO (Data Transfer Object) to domain model and Domain Model to DTO.
|
||||
2. Domain model is the place where all your business logic, business validation and business behaviors will be implemented.
|
||||
The Aggregate Roots, Entities and Value Objects will help to achieve the business logic.
|
||||
|
||||
|
||||
3. Calling repositories to perform additional operations. The repositories interfaces are declared in the `Domain` layer and are implemented in the `Infrastructure` layer.
|
||||
You can reimplement the repository interface with different languages, such as `Rust`, `C++` or `Dart`. etc.
|
||||
```
|
||||
Domain Infrastructure
|
||||
|
||||
Repository A │
|
||||
┌────────────────────────────┼────────────────────────────────┐
|
||||
│ ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐ │ ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐ │
|
||||
│ Interface ──┼─▶ Implementation │
|
||||
│ └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘ │ └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘ │
|
||||
└────────────────────────────┼────────────────────────────────┘
|
||||
Repository B │
|
||||
┌────────────────────────────┼────────────────────────────────┐
|
||||
│ ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐ │ ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐ │
|
||||
│ Interface ──┼─▶ Implementation │
|
||||
│ └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘ │ └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘ │
|
||||
└────────────────────────────┴────────────────────────────────┘
|
||||
```
|
||||
4. The responsibility of [Unit of Work](https://martinfowler.com/eaaCatalog/unitOfWork.html) is to maintain a list of objects affected by a business transaction and coordinates the writing out of changes and the resolution of concurrency problems((No intermediate state)).
|
||||
If any one persistence service fails, the whole transaction will be failed so, roll back operation will be called to put the object
|
||||
back in initial state.
|
||||
|
||||
5. Handling operations (INSERT, UPDATE and DELETE) with SQLite to persis the data.
|
||||
6. Saving or querying the data in the cloud to finish the operation.
|
||||
@ -1,75 +0,0 @@
|
||||
|
||||
|
||||
```
|
||||
// Widget Element RenderObject
|
||||
//
|
||||
// │ │
|
||||
//
|
||||
// ┌─────────────────────┐ │ ┌────────────────────────┐ │ ┌─────────────────────────┐
|
||||
// │ RenderObjectWidget │◀────────────│ _TextLineElement │─────▶│ RenderEditableTextLine │
|
||||
// └─────────────────────┘ │ └────────────────────────┘ │ └─────────────────────────┘
|
||||
// △ │ │
|
||||
// │ │ │ │ ┌─────────▽────────┐
|
||||
// │ ▽ │RenderEditableBox │
|
||||
// ┌────────────────────┐ │ ┌──────────────────────┐ │ └──────────────────┘
|
||||
// ┌──│ EditableTextLine │ │ RenderObjectElement │ │
|
||||
// │ └────────────────────┘ │ └──────────────────────┘ │ ▽
|
||||
// │ ┌────────────┐
|
||||
// │ │ │ │ RenderBox │
|
||||
// │ └────────────┘
|
||||
// │ body ┌────────────┐ │ │ │
|
||||
// ├──────────▶│ TextLine │ ▽
|
||||
// │ └────────────┘ │ │ ┌─────────────┐
|
||||
// │ │RenderObject │
|
||||
// │ ┌────────────┐ │ │ └─────────────┘
|
||||
// └──────────▶│ Line │
|
||||
// └────────────┘ │ │
|
||||
//
|
||||
// │ │ Layout, size, painting and
|
||||
// Widget: holds the config for a Represents an actual comositing
|
||||
// piece of UI. │ piece of UI │
|
||||
//
|
||||
//
|
||||
```
|
||||
|
||||
|
||||
```
|
||||
// ┌────────────────────────┐ ┌──────────────────┐
|
||||
// │ RawGestureDetector │─▶│ RenderEditor │──┐
|
||||
// └────────────────────────┘ └──────────────────┘ │
|
||||
// │
|
||||
// 1. pass the gesture event │
|
||||
// │
|
||||
// │
|
||||
// ┌───────────────────────────────────┐ │ ┌────────────────┐ ┌──────────────────┐ ┌──────────────────────────────┐
|
||||
// │RawEditorStateTextInputClientMixin │──┼──▶│QuillController │◀──listen────│ RenderState │──▶│ _didChangeTextEditingValue │
|
||||
// └───────────────────────────────────┘ │ └────────────────┘ └──────────────────┘ └──────────────────────────────┘
|
||||
// │ │ ▲ │
|
||||
// 1. pass the text input event │ │ │ ▼
|
||||
// │ └─────2. notify change──────────┘ ┌─────────────────────────────────┐
|
||||
// │ │ _onChangeTextEditingValue │
|
||||
// ┌─────────────────────────────┐ │ └─────────────────────────────────┘
|
||||
// │ RawEditorStateKeyboardMixin │───┘ │
|
||||
// └─────────────────────────────┘ ▼
|
||||
// ┌──────────────────────┐ Update the ScrollController's pos after
|
||||
// 1. pass the keyboard cur/ delete/ shortcut event │ _showCaretOnScreen │ post frame
|
||||
// └──────────────────────┘
|
||||
// │
|
||||
// ▼
|
||||
// ┌──────────────────────┐
|
||||
// │ Config cursor timer │
|
||||
// └──────────────────────┘
|
||||
// │
|
||||
// ▼
|
||||
// ┌───────────────────────┐ ┌───────────────────────────────────┐
|
||||
// │ addPostFrameCallback │─▶│_updateOrDisposeSelectionOverlayIfN│
|
||||
// └───────────────────────┘ └───────────────────────────────────┘
|
||||
// │
|
||||
// │
|
||||
// ▼
|
||||
// ┌────────────┐
|
||||
// │ setState │ make the RenderState to rebuild
|
||||
// └────────────┘
|
||||
|
||||
|
||||
```
|
||||
@ -1,31 +0,0 @@
|
||||
# TRANSLATION
|
||||
|
||||
You can help Appflowy in supporting various languages by contributing. Follow the steps below sequentially to contribute translations.
|
||||
|
||||
## Steps to modify an existing translation
|
||||
Translation files are located in : `frontend/app_flowy/assets/translations/`
|
||||
|
||||
1. Modify the specific translation file.
|
||||
2. Run `flutter pub run easy_localization:generate -S assets/translations/`
|
||||
3. Run `flutter pub run easy_localization:generate -f keys -o locale_keys.g.dart -S assets/translations`
|
||||
4. Verify that the translation has changed appropriately by compiling and running the app.
|
||||
|
||||
## Steps to add new language
|
||||
|
||||
**NOTE: Translation files SHOULD be** `json` **files named in the format** `<lang_code>-<country_code>.json` **or just** `<lang_code>.json`**. eg:**`en.json`**,** `en-UK.json`
|
||||
|
||||
1. Add language key-value json file to `frontend/app_flowy/assets/translations/`. Refer `en.json` for format and keys.
|
||||
2. Run `flutter pub run easy_localization:generate -S assets/translations/`
|
||||
3. Run `flutter pub run easy_localization:generate -f keys -o locale_keys.g.dart -S assets/translations`
|
||||
4. Open the `frontend/app_flowy/lib/startup/tasks/application_widget.dart` file.
|
||||
5. In the `AppWidgetTask` class, add the locale of the language you just created (eg: `Locale('en', 'IN')`, `Locale('en')`) to the `supportedLocales` List :
|
||||
|
||||
```dart
|
||||
runApp(
|
||||
EasyLocalization(
|
||||
supportedLocales: const [Locale('en'), Locale('zh_CN')], // <---- Add locale to this list
|
||||
path: 'assets/translations',
|
||||
fallbackLocale: const Locale('en'),
|
||||
child: app),
|
||||
);
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user