The minimalistic document archiving platform.
feat(docs): add architecture documentation (#543)
Corentin Thomasset3d49962ca559
diff --git a/apps/docs/src/content/docs/05-architecture/document-deduplication.mdx b/apps/docs/src/content/docs/05-architecture/document-deduplication.mdxnew file mode 100644index 00000000..033e292b--- /dev/null+++ b/apps/docs/src/content/docs/05-architecture/document-deduplication.mdx@@ -0,0 +1,40 @@+---+title: Document Deduplication+description: How Papra prevents duplicate documents and saves storage space.+slug: architecture/document-deduplication+---++## Overview++Papra automatically detects and prevents duplicate documents per organization using content hashing. This ensures that if the same file is uploaded multiple times, only one copy is stored, saving storage space and reducing clutter.++## How It Works++When a document is added to an organization (upload, email ingestion, folder sync, ...), the server computes a **SHA-256 hash** of the file content and checks if a document with the same hash already exists in that organization.++- If there is **no document with the same hash** in the organization, the new document is added as usual+- If a document **with same content exists**, the upload is rejected+- If a document **with same content was previously deleted** (in trash), it is restored instead of creating a new copy, the metadata is updated to match the newly added document+++## Technical Details++### Hash Algorithm++- Papra uses **SHA-256** for content hashing.+- Computed during streaming upload (no extra I/O)+- 64-character hexadecimal string stored in the database++### Database Constraint++The database enforces uniqueness with a composite index:++```sql+UNIQUE (organization_id, original_sha256_hash)+```++This guarantees no two active documents in the same organization can have identical content.++### File Content Only++Only the **file content** is hashed and used for deduplication, filenames, upload dates, and metadata don't affect deduplication. Two files are considered duplicates if and only if their content is strictly identical.diff --git a/apps/docs/src/content/docs/05-architecture/no-mutation-principle.mdx b/apps/docs/src/content/docs/05-architecture/no-mutation-principle.mdxnew file mode 100644index 00000000..8bfffea8--- /dev/null+++ b/apps/docs/src/content/docs/05-architecture/no-mutation-principle.mdx@@ -0,0 +1,38 @@+---+title: No-Mutation Principle+description: Why Papra never modifies your original documents and the architectural decisions behind this choice.+slug: architecture/no-mutation-principle+---++## Core Philosophy++Papra follows a fundamental principle: **documents are never mutated after upload**. When you input a document, you can always retrieve it exactly as it was uploaded.++## The Design Choice++An archiving platform should guarantee users they can retrieve their documents in their original form. This means:++- No conversion to different formats+- No metadata injection into the file itself+- No overlay of OCR-ed content on scanned PDFs+- No processing that modifies the original file++The simple mental model is: **"If I input X, I'll retrieve X"**++## Why This Matters++### Trust and Reliability++When archiving important documents, users need absolute confidence that their files remain untouched. Whether it's a legal document, a medical record, or a personal photo, the original should be sacrosanct.++### Simplicity++This approach eliminates the mental overhead of wondering "what happened to my file?" Users don't need to understand concepts like:+- Original vs. processed versions+- Format conversions+- OCR overlays+- Metadata injection++### Flexibility for the Future++While Papra currently doesn't mutate documents, the architecture leaves room for future enhancements. If needed, a "processed" version concept could be added alongside originals, giving users the choice without forcing a particular model.diff --git a/apps/docs/src/content/docs/05-architecture/organization-deletion-purge.mdx b/apps/docs/src/content/docs/05-architecture/organization-deletion-purge.mdxnew file mode 100644index 00000000..6f79522b--- /dev/null+++ b/apps/docs/src/content/docs/05-architecture/organization-deletion-purge.mdx@@ -0,0 +1,62 @@+---+title: Organization Deletion & Purge+description: How Papra handles organization deletion with a grace period and eventual purge.+slug: architecture/organization-deletion-purge+---++## Overview++Papra implements a two-phase deletion process for organizations: soft deletion followed by hard deletion (purge). This provides a grace period for recovery while ensuring eventual cleanup of resources.++## Deletion Process++### Who Can Delete++Only the **organization owner** can delete an organization. Admins and members do not have this permission.++### What Happens During Deletion++When an organization is deleted:++1. **Members are removed** - All organization members are stripped from the organization, leaving them dangling+2. **Invitations are removed** - All pending invitations are deleted+3. **Metadata is recorded**:+ - `deletedAt`: Timestamp when the deletion occurred+ - `deletedBy`: ID of the user (owner) who deleted the organization+ - `scheduledPurgeAt`: Future date when hard deletion will occur (default: 30 days)++The organization itself remains in the database in a soft-deleted state, allowing for potential restoration.++## Purge Process++### When Purge Occurs++Hard deletion (purge) happens when `scheduledPurgeAt` is reached. By default, this is **30 days** after the deletion date.++### What Gets Purged++When an organization is purged:++- **All documents** are deleted from storage+- **All database records** related to the organization are removed (cascade handles related records, like Tags, Intake Emails, etc.)+- The organization itself is permanently deleted++The process handles documents in batches using an iterator to avoid memory issues with large organizations.++### Background Task++Purging is handled by a periodic background task that:++1. Queries for organizations with `scheduledPurgeAt` in the past+2. For each expired organization:+ - Deletes all document files from storage+ - Hard deletes the organization (cascade handles related records)+3. Logs the process for monitoring and debugging++The task continues even if individual file deletions fail, logging errors without blocking the entire purge operation.++## Recovery++Organizations can be restored before the `scheduledPurgeAt` date is reached, but only by the user who deleted them (the previous owner). After this date, recovery is no longer possible, even if the purge has not yet occurred.++> Note: After recovery, the organization owner must re-invite members as they were removed during deletion.\ No newline at end of filediff --git a/apps/docs/src/content/navigation.ts b/apps/docs/src/content/navigation.tsindex 4e1fc14b..7dd0b291 100644--- a/apps/docs/src/content/navigation.ts+++ b/apps/docs/src/content/navigation.ts@@ -41,6 +41,23 @@ export const sidebar = [},],},+ {+ label: 'Architecture',+ items: [+ {+ label: 'No-Mutation Principle',+ slug: 'architecture/no-mutation-principle',+ },+ {+ label: 'Document Deduplication',+ slug: 'architecture/document-deduplication',+ },+ {+ label: 'Organization Deletion',+ slug: 'architecture/organization-deletion-purge',+ },+ ],+ },{label: 'Resources',items: [