chore(docs): add more app documentation

seed-hypermedia · Jan 19, 2023 · 3590667 · 3590667
1 parent efac2b8
commit 3590667
Show file tree

Hide file tree

Showing 50 changed files with 1,013 additions and 109 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,18 @@
+# Mintter Documentation
+
+Because the Mintter Data structure is not production-ready yet, we are creating some public documentation about the Product and the company here on this repo. Please feel free to ask any questions and give some feedback to [us]([email protected]). In the future, all the Mintter documentation wil be available via Mintter or the Mintter community server
+
+- [What is Mintter?](./what-is-mintter.md)
+- [Technical Guide](./technical-guide.md)
+- [Developer Project Setup](./dev-setup.md)
+
+## Frontend Technical Documentation
+
+- [Frontend App Architecture](./frontend-app.md)
+- [Frontend Gateway Architecture](./frontend-gateway.md)
+- [Frontend Shared Packages Architecture](./frontend-shared-packages.md.md)
+- [Frontend Testing](./frontend-testing.md)
+
+## Backend Technical Documentation
+
+- [DID and UCAN](./did-and-ucan.md)
diff --git a/docs/assets/Mintter_IPFS_Camp_2022 1.gif b/docs/assets/Mintter_IPFS_Camp_2022 1.gif
diff --git a/docs/assets/Mintter_IPFS_Camp_2022.gif b/docs/assets/Mintter_IPFS_Camp_2022.gif
diff --git a/docs/assets/Screenshot_2023-01-03_at_16.39.42.png b/docs/assets/Screenshot_2023-01-03_at_16.39.42.png
diff --git a/docs/assets/diagram-app-architecture.png b/docs/assets/diagram-app-architecture.png
diff --git a/docs/assets/diagram-document-connections.png b/docs/assets/diagram-document-connections.png
diff --git a/docs/assets/diagram-ipfs-pointer.png b/docs/assets/diagram-ipfs-pointer.png
diff --git a/docs/assets/diagram-triplestore-table.png b/docs/assets/diagram-triplestore-table.png
diff --git a/docs/assets/encryption-callout.png b/docs/assets/encryption-callout.png
diff --git a/docs/frontend/assets/draft-item-menu.png → docs/assets/frontend-app-draft-item-menu.png b/docs/frontend/assets/draft-item-menu.png → docs/assets/frontend-app-draft-item-menu.png
diff --git a/docs/frontend/assets/app-menu.png → docs/assets/frontend-app-menu.png b/docs/frontend/assets/app-menu.png → docs/assets/frontend-app-menu.png
diff --git a/...frontend/assets/publication-item-menu.png → ...ts/frontend-app-publication-item-menu.png b/...frontend/assets/publication-item-menu.png → ...ts/frontend-app-publication-item-menu.png
diff --git a/docs/assets/minnter-technical-guide-1.png b/docs/assets/minnter-technical-guide-1.png
diff --git a/docs/assets/ui-inbox.png b/docs/assets/ui-inbox.png
diff --git a/docs/assets/ui-publication-and-activity.png b/docs/assets/ui-publication-and-activity.png
diff --git a/docs/assets/ui-publication.png b/docs/assets/ui-publication.png
diff --git a/docs/assets/ui-transclusions.png b/docs/assets/ui-transclusions.png
diff --git a/docs/assets/what-is-mintter-1.png b/docs/assets/what-is-mintter-1.png
diff --git a/docs/assets/what-is-mintter-10.png b/docs/assets/what-is-mintter-10.png
diff --git a/docs/assets/what-is-mintter-11.png b/docs/assets/what-is-mintter-11.png
diff --git a/docs/assets/what-is-mintter-12.png b/docs/assets/what-is-mintter-12.png
diff --git a/docs/assets/what-is-mintter-13.png b/docs/assets/what-is-mintter-13.png
diff --git a/docs/assets/what-is-mintter-14.png b/docs/assets/what-is-mintter-14.png
diff --git a/docs/assets/what-is-mintter-15.png b/docs/assets/what-is-mintter-15.png
diff --git a/docs/assets/what-is-mintter-16.png b/docs/assets/what-is-mintter-16.png
diff --git a/docs/assets/what-is-mintter-17.png b/docs/assets/what-is-mintter-17.png
diff --git a/docs/assets/what-is-mintter-18.png b/docs/assets/what-is-mintter-18.png
diff --git a/docs/assets/what-is-mintter-19.png b/docs/assets/what-is-mintter-19.png
diff --git a/docs/assets/what-is-mintter-2.png b/docs/assets/what-is-mintter-2.png
diff --git a/docs/assets/what-is-mintter-20.png b/docs/assets/what-is-mintter-20.png
diff --git a/docs/assets/what-is-mintter-3.png b/docs/assets/what-is-mintter-3.png
diff --git a/docs/assets/what-is-mintter-4.png b/docs/assets/what-is-mintter-4.png
diff --git a/docs/assets/what-is-mintter-5.png b/docs/assets/what-is-mintter-5.png
diff --git a/docs/assets/what-is-mintter-6.png b/docs/assets/what-is-mintter-6.png
diff --git a/docs/assets/what-is-mintter-7.png b/docs/assets/what-is-mintter-7.png
diff --git a/docs/assets/what-is-mintter-8.png b/docs/assets/what-is-mintter-8.png
diff --git a/docs/assets/what-is-mintter-9.png b/docs/assets/what-is-mintter-9.png
diff --git a/docs/assets/what-is-mintter.png b/docs/assets/what-is-mintter.png
diff --git a/docs/dev-setup.md b/docs/dev-setup.md
@@ -2,6 +2,8 @@
 
 ## Building On Unix-Like Systems
 
+> Checkout the [Build System Document](./build-system.md)
+
 The setup is simplified by using the [Nix Package Manager](https://nixos.org/nix), and [Direnv](https://direnv.net). You should use this setup on Unix-like systems, instead of trying to manually install the required tools.
 
 ### Prerequisites
@@ -10,6 +12,8 @@ You must have the C toolchain installed globally on your machine. It can be `gcc
 
 ### Install Nix
 
+> checkout the [Nix](./nix.md) documentation for more context
+
 Nix is a package manger for Unix-like systems, which is very strict about isolating packages. It will not mess around with your existing system packages. Ideally Nix would be the only piece of software needed to build Mintter, but unfortunately some OpenGL packages, and some system libraries don't work quite well. We still leverage Nix to manage other tools and runtimes required to work with Mintter.
 
 So, install Nix by following the [official documentation](https://nixos.org/download.html) for your system.

diff --git a/docs/frontend-app.md b/docs/frontend-app.md
@@ -0,0 +1,34 @@
+# App Main Architecture
+
+in a normal frontend application, the page route is a crucial part. It's the source of truth of that and what not to render. In Mintter is not that important.
+
+Mintter have three main components that needed to render depending on the state its coming from, for example, when we create a new Document and open a new window.
+
+## Main page machine
+
+the app is controlled by one machine: The main page machine. this machine is in charge of a couple of things:
+
+1. [Open new windows](#open-a-new-window)
+2. [Create new Drafts](#create-new-drafts)
+3. [Store Current file reference](#store-current-file)
+
+### Open a New Window
+
+All the new window creation is handled by Tauri. we just create the draft and calls the open window function. Tauri will check if the document is currently open in any of its available windows. If there's one window available, it will focus that window. If not, it will create a new window with the new URL.
+
+There are multiple ways a user can create a new window. For every way, the one that controls the actions is the main-machine.
+
+You will find multiple buttons and context menu items throughout the app that triggers the creation of a new window, but those can be summarize into a couple of Scenarios:
+
+1. **Open a Publication**: We pass the Publication's URL to the open function
+1. **Open a Draft**: We pass the Draft's URL to the open function
+1. **Create a new Draft**: In this case, the main-machine will create a new draft, generates the new URL and then call the open function with the generated URL.
+1. **Edit a Publication**: In this case, the main-machine will create a new draft from the current publication, generates the new URL and then call the open function with the generated URL.
+
+### Create new Drafts
+
+WIP
+
+### Store Current File
+
+WIP
diff --git a/docs/frontend/gateway.md → docs/frontend-gateway.md b/docs/frontend/gateway.md → docs/frontend-gateway.md
diff --git a/docs/frontend-shared-packages.md b/docs/frontend-shared-packages.md
@@ -0,0 +1,3 @@
+# Frontend shared packages
+
+Now we have two main frontend projects: [the local application](./frontend-app.md) and [the web gateway](./frontend-gateway.md)
diff --git a/docs/frontend/assets/embed-context-menu.png b/docs/frontend/assets/embed-context-menu.png
diff --git a/docs/frontend/assets/publication-list.png b/docs/frontend/assets/publication-list.png
diff --git a/docs/frontend/routing.md b/docs/frontend/routing.md
diff --git a/docs/frontend/shared-packages.md b/docs/frontend/shared-packages.md
diff --git a/docs/technical-guide.md b/docs/technical-guide.md
@@ -0,0 +1,45 @@
+# Mintter technical guide
+
+## Introduction
+
+Mintter is a decentralized knowledge collaboration application. It’s built on [IPFS](https://ipfs.tech), it’s peer-to-peer (P2P), and strives to be [local-first](https://www.inkandswitch.com/local-first/). This document assumes that readers are at least somewhat familiar with the mentioned concepts, and with what Mintter is about.
+
+## Mintter Documents
+
+Mintter Documents are containers of content blocks, arranged in hierarchical tree structures.
+
+Anyone can create content blocks, edit them, move around blocks or whole subtrees of blocks.
+
+Published documents can be linked from other documents, and you can bring in portion of some document into your own document, always keeping the trace to the original. This is called a Transclusion.
+
+![Untitled](assets/minnter-technical-guide-1.png)
+
+Many of the challenges we faced trying to develop such a system on top a decentralized network like IPFS didn’t have easy plug-and-play solutions at the time. This includes:
+
+- Decentralized Identity
+- Version Control
+- Multi-Device
+- Rich Hypertext Capabilities
+
+## High-Level Architecture
+
+### Local-First
+
+As mentioned in the introduction, we want our app to follow the principles of the local-first software. The original paper (linked above) is a highly recommended read.
+
+We believe that P2P technology could enable superior local-first experiences, and we bet on IPFS and Libp2p to become major parts of this journey.
+
+### Desktop App
+
+Mintter is a desktop app. Here’re some images and videos (click to expand).
+
+![Mintter App Architecture](assets/diagram-app-architecture.png)
+
+Here are some screenshots of the current application
+
+![Page: Inbox](assets/ui-inbox.png)
+![Page: One Publication](assets/ui-publication.png)
+![Page: Publication with transclusions](assets/ui-transclusions.png)
+![Page: Publication page with the activity panel](assets/ui-publication-and-activity.png)
+
+We created this [Mintter Showcase Video Playlist](https://www.youtube.com/playlist?list=PL_Q4x-stM4VLRlMN3xxtN_uj5KesC6DNU) to show some of the core features you can find in the current Desktop app.
diff --git a/docs/what-is-mintter.md b/docs/what-is-mintter.md
@@ -0,0 +1,171 @@
+# What is Mintter
+
+Mintter is a decentralized application for collaboration and publishing powered by a syncable knowledge graph. The purpose of the Company is to augment human intelligence decentralising web collaboration.
+
+### Introduction to the problem
+
+In 1989, Tim Berners-Lee created the web in CERN, the European scientific center in Switzerland and commercialised by Marc Andreessen with Netscape.
+
+![Untitled](assets/what-is-mintter.png)
+
+Decentralized publishing was the key success factor of the web in the 90s.
+
+**The Internet has more than 5 billion users**
+
+![Untitled](assets/what-is-mintter-1.png)
+
+But it's limited hypertext capabilities makes decentralized collaboration impossible. Something as simple as adding a comment to an image needs a central server.
+
+**Cristiano and Maradona do not own this picture!**
+
+![Untitled](assets/what-is-mintter-2.png)
+
+**A central authority owns your pictures and social interactions**
+
+![Untitled](assets/what-is-mintter-3.png)
+
+And not only your family pics, but your ideas too, and the connection between them. Google is the only entity in the world that knows who is referring to whom.
+
+![Untitled](assets/what-is-mintter-4.png)
+
+![Untitled](assets/what-is-mintter-5.png)
+
+The Central Authority incentive is the advert not the collaboration, creating the Attention Economy. The social dialogue needed to bring learning and progress to society is fragmented, noisy and hostile.
+
+**Experts are leaving Online Communities everywhere:**
+
+![Untitled](assets/what-is-mintter-6.png)
+
+### To better understand the problem, we embarked on a fascinating journey back to 1945, where we traced the origins of hypertext.
+
+![Untitled](assets/what-is-mintter-7.png)
+
+### In 1945, Vannevar Bush wrote As We May Think, the conception of Hypertext
+
+The Memex stores the **associations of our minds** in a machine, that you can **share.** Vannevar called them **Trails**.
+
+![Untitled](assets/what-is-mintter-8.png)
+
+### **In the 60s, Doug Engelbart creates the first Hypertext system to ‘Augment Human Intellect’**
+
+Fine-grained linking—everything is addressable , of hierarchical documents, in an Open Hypertext System will boost our collective intellect.
+
+![Untitled](assets/what-is-mintter-9.png)
+
+### **and Ted Nelson coins the word ‘Hypertext’ and creates Xanadu**
+
+Hypertext properties essential for human collaboration: distributed storage system, bidirectional, transclusions, micropayments, visible connections, parallel pages.
+
+![Untitled](assets/what-is-mintter-10.png)
+
+### **And we found the web missing features to enable decentralized collaboration**
+
+- Authorship
+- Distributed file system providing permanent content
+- Better links:
+    - Everything should be linkable at the character level
+    - Bidirectional linking
+    - Unbreakable links
+- Block-based hierarchical document
+- Versionable and editable pages
+- Annotations and discussions
+- A micropayment system: The only viable business model for the web is the attention economy. The incentive is clicking an ad instead of knowledge creation and progress.
+
+We need a new generation of digital tools, that brings collaboration to the decentralized web. The missing hypertext properties will upgrade the web. Mintter will be part of the change.
+
+**Ted & Doug scream horrified missing them**
+
+![Untitled](assets/what-is-mintter-11.png)
+
+## Mintter
+
+### Create a p2p collaboration space for your knowledge community.
+
+Scientist groups, citizen movements, or tech communities, can discuss and build knowledge bases without central authorities or gatekeepers. Build your knowledge community with direct connections to your peers and enjoy permission-less participation with no risk of de-platforming.
+
+**The web of sovereign peers, bring back experts to Online communities**
+
+![Untitled](assets/what-is-mintter-12.png)
+
+**IPFS, p2p filesystem**
+
+Mintter App includes an IPFS, a distributed filesystem, where you share directly to your peers with no gatekeepers.
+
+### Share your ideas and content retaining your authorship / ownership
+
+Publish anything—from research papers to video game guides—and watch as other users read, disseminate and discuss your material online, building upon your original. Every piece of content, text or media, is cryptographically signed. Own your content while sharing it with your peers.
+
+**Identity and Wallet**
+
+![Untitled](assets/what-is-mintter-13.png)
+
+Bip39 digital identity, Content digital signatures, Multi-device, Contacts, Verify contacts, Manage contacts, Micropayments, Lightning Node, Lightning Transactions, Lightning Balance
+
+### Write and change your articles
+
+Mintter Documents are containers of content blocks arranged in hierarchical tree structures. Collaborate on documents using a decentralized network of computers where updates are recorded as an immutable set of changes.
+
+**Version Control System for Documents**
+
+![Untitled](assets/what-is-mintter-14.png)
+
+A CRDT (Conflict-free Replicated Data Type) is a data structure that can be used in distributed systems to ensure that data is automatically replicated across multiple nodes, without the need for a central authority.
+
+### Create and transfer knowledge with a better collaboration UX
+
+Address permanent content down to character level. Information immutability and fine-grained link will boost the knowledge generation of your open community. Let backlinks find different perspectives. To express your ideas you need to reuse other people’s ideas. Annotate and discuss anything. Social Commentaries and Annotations in the context. Knowledge Collaboration needs Commentary.
+
+**Rich Hypertext Capabilites**
+
+![Untitled](assets/what-is-mintter-15.png)
+
+**Comment and Discuss anything in with your peers**
+
+![Untitled](assets/what-is-mintter-16.png)
+
+**Multiple windows**
+
+The citation process with multiple windows is much more accessible, boosting the linking between texts.
+
+![Untitled](assets/what-is-mintter-17.png)
+
+### Control what you see and how you see it at an incredible speed
+
+Browsing experience 10x faster than the web. Local first application were users control their interfaces and the information they see: fast, multi-device, offline, collaboration, longevity, user-control.
+
+**Local First application**
+
+![Untitled](assets/what-is-mintter-16.png)
+
+### **Publish to the Web with versioning, authorship, and royalties**
+
+Access to worldwide audience and collaboration by publishing to the web all your documents and updates become your own publisher with your own the authority that gives your own domain.
+Publish to the web with one click to [mintter.com](http://mintter.com/) or to your own website. You can also share your content in social media, through mail or you favourite p2p networks.
+
+**Royalties**
+
+Micropayments are splitting among the different authors of a document.
+
+![Untitled](assets/what-is-mintter-18.png)
+
+### A new distribution channel for your ideas with a fair copyright system for the web
+
+Reuse fragments of content keeping the authorship of the original author. Your peers will discover the new content thanks to the reusability, making transclusions a new distribution change without gatekeepers.
+Easily compose trails of content from your communities and peers.
+
+**Transclude content keeping attribution and royalties**
+
+Ted Nelson created the concept of transfusions, allowing digital reusability with an easy copyright.
+
+![Untitled](assets/what-is-mintter-19.png)
+
+### **Build your own media publisher or Wikipedia-style knowledge base**
+
+Create from your own personal blog or academic paper to your community’s knowledge base, wiki, media outlet, or repository of documents in the web.
+Become your own publisher with versioning, authorship and accept micropayments in the web or mintter app creating your own repository of content.
+
+**Graph Database**
+
+A set of Mintter Documents build a syncable local graph database
+
+![Untitled](assets/what-is-mintter-20.png)
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Frontend shared packages

		Now we have two main frontend projects: [the local application](./frontend-app.md) and [the web gateway](./frontend-gateway.md)