Inside LUMASYNC: Deep dive into the sync engine architecture

When you connect Luma to your Google Drive, we don't just dump a binary blob of data. We create a structured, readable file system that mirrors your local bookmarks.

This post explores what happens inside the LUMASYNC folder and why we designed it this way.

The Folder Structure

Upon your first sync, Luma searches your Drive for a folder which is created by Luma named LUMASYNC. If it doesn't exist, we create it.

Inside this folder, you won't find a complex database file. Instead, you will find thousands of small files with two specific extensions:

• .folder: Represents a directory in Luma.
• .page: Represents a bookmark or chat.

The filename corresponds exactly to the File ID in our local IndexedDB.

Why Custom Extensions?

Using .folder and .page isn't just cosmetic. It allows our sync engine to quickly target specific types of data.

• Need to update a folder color? We target its ID in the with the .folder extension.
• Need to delete a specific bookmark? We target its ID with the .page extension.

This simple convention keeps our query logic extremely fast and efficient.

The Permission Scope: drive.file

Security starts with permissions. Luma requests the drive.file scope from Google.

This is a restricted scope that grants Luma access only to the files and folders that Luma itself has created. We cannot see your photos, your personal documents, or files created by other apps. We live strictly inside our own sandbox within your Drive.

The Case for Plain Text: Why No Encryption?

If you open one of these .page files with a text editor, you will see standard JSON data.

{
  "id": "1234-5678",
  "name": "My Cool Bookmark",
  "url": "https://example.com",
  "parentId": "root",
  "type": "page"
}

You might wonder: Why isn't this encrypted?

Fun fact: This was one of our oldest debates while building Luma.

Ultimately, we decided on a plain-text approach rooted in Performance and Transparency.

1. Performance: Encryption is computationally expensive. For standard bookmarks—which are simply URLs and titles—the overhead of encrypting and decrypting thousands of items on the client side would noticeably degrade the "instant" feel of the app. Since your data lives securely in your own Google Drive (which is already encrypted at rest by Google) and on your local machine, we chose speed.

2. Transparency & Trust: We want you to know exactly what Luma is doing. By storing data in plain JSON, you can audit the files yourself. You don't have to trust us blindly; you can verify that we are only saving the bookmarks you explicitly added and nothing else.

3. Data Ownership: Plain text means true ownership. You can write your own scripts to parse these files, migrate them to another service, or back them up independently, all without needing Luma's permission or decryption keys.

But this is not the end of the story. we are planning something...

The Future: The Vault

While we believe transparency is the right default for bookmarks, we understand that some data is sensitive.

We are actively planning a Vault feature. Items moved to the Vault will be client-side encrypted before they ever touch the LUMASYNC folder. This will offer a balanced approach: raw speed and transparency for your daily browsing, and end-to-end encryption for your private data.

Conclusion

We built Luma to be a tool that we would want to use—one that respects your privacy and your data.

By keeping the LUMASYNC folder open and transparent, we are handing the keys back to you. It is your Drive, your files, and your data. We are just the interface.