Onlyever documentation

👀 Preface

⚠️ WARNING: This document is under construction and is subject to change.

💬 INFO: This document is designed to offer fundamental insights into the workings of the system. We’ve crafted the documentation with simplicity in mind, ensuring that individuals with non-technical backgrounds can grasp the essence of the system. This is why, some technical terminologies are loosely used. While this approach facilitates understanding for beginners, individuals with technical expertise may find that certain details are presented in a simplified manner that diverges from precise technical terminology and the norm.

🔖 Terminologies

COLLABORATORS: Non developers associates and maintainers of this project.
DEVS: Developers that have access to the code base.
CLIENT SIDE: OnlyEver Obsidian plugin. For simplicity we’ll be referring to Obsidian plugin as the client side.
SERVER SIDE: Atlas app services. For simplicity we’ll be referring to Atlas app services and its functions as the server side.

📖 Reading this document

Each topic if necessary starts with a image of the procedure being described.

COLLABORATORS: We recommend using the image and the summary below (if exists) the to understand the topic. You can skip reading the ‘For Developers’ section.
DEVS: All classes and methods will be documented as necessary. All classes and methods in this document will be embedded links that redirect to the documentation of said module. Please read predecissing sections marked ‘For Collaborators’ as well.

🚥 Getting Started

🥶 Beta version setup

Testers and developers might wanna test older versions or versions currently under development. Beta versions are installable through Obsidian BRAT plugin.

☕ Prerequisites

  1. Obsidian app
  2. Obsidian BRAT

👾 Steps

  1. Open Obsidian app.
  2. Open Obsidian BRAT.
  3. Click on ‘Add Beta plugin with frozen version’.
  4. Add the following:
  1. Click on ‘Add Plugin’.
  2. Done.

📂 Project setup

Contributors and maintainers need to have a copy of this repository to get started. Here’s a simple breakdown of ‘how to’ if you do not know already.

☕ Prerequisites

  1. Obsidian app. ( This is a given, how else would you see your changes. )
  2. Hot Reload. ( To maintain your sanity you will need this. Basically reloads your plugin with changes implemented on save. )
  3. Git. ( If you’re reading this, I’m sure you know your ways around Git and Github. )
  4. Node. ( You will need node. )
  5. NPM. ( You will need )

⚠️ Hot Reload will sometime introduce unexpected behavior by not immediately implementing changes or making multiple function calls of same function. I think this is because Hot Reload is caching some things behind the scene( probably). When faced with this issue just restart Obsidian. “How do I know its a Hot Reload issue?” You just will.

👾 Steps

  1. Create an Obsidian vault.

  2. Open the folder where your Obsidian vault is located.

  3. Open .obsidian hidden folder.

  4. Open plugins folder.

  5. Clone your repo to the plugins folder with the following command:

    git clone git@github.com:OnlyEver/onlyever_obsidian_sync.git

  6. Cd into the directory.

  7. Run npm install to install node packages.

  8. Run npm run dev to transpile your plugin from main.ts to main.js and run the project.

  9. Open your Obsidian application.

  10. In the Community plugins tab of Settings, reload the installed plugin section to see the ‘Obsidian-Onlyever-plugin’.

  11. Turn on the toggle button for ‘Obsidian-Onlyever-plugin’.

🆗 Using Hot Reload.

  • During development you will soon realize that the plugin needs to be manually refreshed and reloaded in order for the changes to be implemented.
  • This is super ineffective.
  • Install the Hot Reload.
  • Enable Hot Reload.
  • Refresh Plugins.
  • Enable Onlyever Obsidian Sync plugin.
  • Done. Now the code changes will be implemented on save.

📚 System breakdown

🧿 System design

Syncing Obsidian notes to Only Ever library at its core, is a very simple concept.Given an Only Ever app user with valid Obsidian API token, the user is allowed to sync Obsidian notes to his/her/their Only Ever library.

Caption: System block diagram
Caption: System block diagram

FOR COLLABORATORS

  1. Request validation happens on the server side.
  2. Internal link resolution (mapping slugs and id) happens on the server side.
  3. Image resolution (generating remote image url) happens client side.
  4. Heading parsing happens on client side.
  5. Content parsing happens on client side.

FOR DEVS

  1. Read above block. No additional info required for this section.

🧿 Plugin design

This topic deals with breaking down the internals of the plugin on a abstract level.

Caption: Plugin module block diagram
Caption: Plugin module block diagram

FOR COLLABORATORS

  1. main : This is the entry point of our plugin. This module is acts as an interface for our code and the obsidian ecosystem(native API). This module handles the plugin lifecycle, event listening and handling, loading other modules, etc.
  2. onlyever api : This module contains code that is responsible for communicating with Atlas serverless functions.
  3. settings tab : This module contains code that registers features to the setting tab of onlyever_obsidian_sync plugin.
  4. overwrite popup : This module contains code that shows overwrite popup when an overwrite condtion is met.
  5. file collection : This is a module contains the following submodules with their own responsibilities:
    • file manager: Uses Obsidaian native API to access the vault and the files within the vault.
    • file processor: Parent to file parser. Validates and provides required notes for file parser to parse.
    • file parser: Performs all necessary parsing needed to create a valid payload for onlyever api module to use.

🧠 Understanding Syncing

🧿 Plugin side

Caption: Client side sync DFD diagram
Caption: Client side sync DFD diagram

FOR COLLABORATORS

⚠️ WARNING:This section is under construction.

FOR DEVS

⚠️ WARNING:This section is under construction.

🧿 Atlas side

Caption: Server side sync DFD diagram
Caption: Server side sync DFD diagram

FOR COLLABORATORS

⚠️ WARNING:This section is under construction.

FOR DEVS

⚠️ WARNING:This section is under construction.