Skip to content

Key Flows

Jump to bottom
Parnian Hajian edited this page Apr 23, 2026 · 1 revision

Key Flows

This page documents the step-by-step sequences behind solid.drive’s core operations. Understanding these flows is essential for contributing to the infrastructure layer or debugging unexpected behaviour in the Solid protocol integration.

Upload

The upload flow is the most complex operation in the app. Every step after the binary upload is a write to the Pod. If any step fails, the entire container is deleted to ensure no half-written resources are left behind.

1.  User selects a file and fills in the required metadata fields
2.  App validates metadata against SHACL constraints (loaded from public/tbox.ttl)
3.  App resolves the schema.org class from the file's MIME type
4.  App creates a new LDP BasicContainer on the Pod
5.  App uploads the binary into the container
6.  App writes index.ttl (schema.org metadata) into the container
7.  App appends a dcat:Dataset entry to catalog.ttl via SPARQL PATCH
8.  First upload only: app writes the catalog URI to the user's WebID profile
         so other Solid applications can discover it
ℹ️
 If validation fails at step 2, no network requests are made. If any step from 6 onward fails, the container created at step 4 is deleted in full.

Delete

Delete is deliberately thorough; every resource that upload created is removed. No orphaned containers, binaries, or catalog entries are left on the Pod.

1.  User clicks Delete and confirms the prompt
2.  App removes the file's dcat:Dataset entry from catalog.ttl via SPARQL PATCH
3.  App deletes index.ttl from the file container
4.  App deletes the binary from the file container
5.  App deletes the file container itself

Share a File

Sharing operates at the file container level. When access is granted, two things happen: the ACL is updated, and a private catalog entry is written for the recipient so they can discover the file.

1.  User opens the Share panel on a file card
2.  User clicks Grant next to a contact
3.  App adds acl:Read for the contact's WebID to the file container's .acl
4.  App writes (or updates) .shared-<contact-webid>.ttl with the file's catalog entry
5.  App sets the .acl on .shared-<contact-webid>.ttl
         so only that contact can read it

Revoke Access

Revocation is the mirror of sharing: the ACL entry is removed and the shared catalog entry is cleaned up.

1.  User opens the Share panel and clicks Revoke next to a contact
2.  App removes the contact's WebID from the file container's .acl
3.  App removes the file's entry from .shared-<contact-webid>.ttl

After revocation, the contact can no longer access the file by URL. The Pod enforces the ACL on every request.

Access Request Flow

The access request system uses the Solid LDP inbox as a messaging channel between users. No application server mediates the exchange; messages travel directly between Pods.

User A wants to see User B's catalog:

1.  A clicks "Request Access" on B's contact entry in the Profile sidebar
2.  App writes an access request message to B's LDP inbox
3.  B's app polls the inbox and surfaces the pending request in the sidebar
4.  B reviews the request and clicks Accept or Deny

    Accept path:
    └── App grants acl:Read on B's catalog.ttl to A's WebID
        └── A's "Shared with Me" section now shows B's shared files

    Deny path:
    └── App writes a rejection notification to A's LDP inbox
        └── A's app reads the notification and shows a "Denied" state
            next to B's name in the contacts list
        └── A can re-request at any time, restarting the flow

Shared With Me: Loading

The "Shared with Me" section loads file entries from contacts' Pods without any intermediary.

For each contact in the user's profile:

1.  App attempts to fetch .shared-<own-webid>.ttl from the contact's Pod
2.  If found: reads dcat:Dataset entries from the per-contact shared catalog
3.  If not found: falls back to the contact's main catalog.ttl
         (this handles files shared before the per-contact catalog system was introduced)
4.  Entries from all contacts are merged and displayed as
         read-only file cards in the "Shared with Me" section
💡
 If a contact’s files do not appear, check that they have granted access and that their Pod is reachable. The fallback to the main catalog ensures that older shares still surface correctly." still and adoc support numbers you dont have to number them

Clone this wiki locally