Files & Drive Module Technical Specifications

How it works: Aeion Files sits above your storage backend as a unified abstraction — upload, download, delete, and metadata operations behave identically whether the bytes live in S3, R2, GCS, Azure Blob, or local disk. Switching backends, or adding a second one, doesn't change how the rest of the platform reads or writes files.

Presigned URLs: Every backend supports secure, time-limited download links (1-hour default expiry, configurable per request). S3-compatible backends use standard presigned URLs, GCS uses v4 signing, and Azure uses SAS tokens — the difference is invisible to your application and your users.

Backend configuration: Configure one or many backends per tenant through the admin UI or API. Missing or invalid credentials are caught and reported at setup time, not at upload time.

Hot/cold storage routing: Set rules so frequently accessed files stay on fast, low-latency storage while older files automatically move to lower-cost archive tiers — configurable per space or per file pattern (e.g. route documents/** to hot storage and archives/** to cold storage).

What runs on every upload:

• Text extraction — OCR for images, native text extraction for documents
• Tag generation — automatic categorization based on content
• Summary generation — a one-to-two sentence summary for quick scanning
• Entity extraction — people, organizations, dates, and other named entities
• Embedding generation — powers semantic (concept-based) search

Processing runs asynchronously in the background and retries automatically if an AI provider is temporarily rate-limited, so uploads never fail because processing is momentarily backed up.

Text extraction by file type: PDFs extract their text layer directly, or run OCR if scanned. Office documents (Word, Excel, PowerPoint) are parsed natively. Images run through OCR. Code and Markdown files are read directly.

Semantic search: Embeddings are stored alongside your file metadata — no separate vector database to stand up or manage. Search queries are embedded the same way, and results are ranked by conceptual relevance, not just keyword match.

Organization suggestions: For every new upload, Aeion Files suggests a destination folder based on how similar content has been organized in the past, along with alternative suggestions and a confidence score for each.

Every version is tracked: version number, size, an integrity checksum, who made the change, when, and an optional comment. Versions can be labeled ("draft", "final", "reviewed") to protect them from automatic cleanup, and the current version is always clearly marked.

Diff between versions: compare any two versions — size change, integrity match, and for text-bearing files, a line-level diff of what was added, removed, or modified, plus a summary of any metadata changes.

Auto-cleanup policies: configure, per space, how many versions to retain and for how long. Versions past the retention window are either archived to cold storage or deleted, based on your policy — cleanup runs on upload, on a daily schedule, or on demand. Identical files (matched by content checksum) share a single stored copy regardless of how many times they're uploaded, so storage is never wasted on duplicates.

Upload flow:

```typescript // Step 1: Initiate upload (returns uploadId + chunk info) POST /api/files/upload/initiate { spaceId: "spa_abc", parentId: "nod_xyz", filename: "report.pdf", size: 52428800, // 50MB mimeType: "application/pdf", checksum: "sha256:abc123...", // Optional integrity check }

// Response: { uploadId: "upl_01HQZWXKM", chunkSize: 5242880, // 5MB per chunk totalChunks: 10, expiresAt: "2026-05-12T10:00:00Z", }

// Step 2: Upload chunks POST /api/files/upload/chunk/{uploadId}/{chunkIndex} Body: <binary data> Headers: Content-Type: application/octet-stream

// Step 3: Complete upload POST /api/files/upload/complete/{uploadId} // → All chunks assembled → SHA-256 verified → stored → version created

// Resume: GET /api/files/upload/status/{uploadId} // → Returns: { uploadedChunks: [0,1,2,4], missingChunks: [3,5,6,7,8,9] } // → Client resumes from missing chunks ```

Deduplication: If the checksum matches an existing file, Aeion Files links to the existing storage object instead of uploading a duplicate — the upload completes instantly and the UI shows "Duplicate detected."

Progress tracking: Upload progress is pushed to the UI in real time as each chunk completes.

Supported methods:

PROPFIND /dav/{spaceId}/path — List directory contents + metadata MKCOL /dav/{spaceId}/path — Create directory GET /dav/{spaceId}/path — Download file PUT /dav/{spaceId}/path — Upload/replace file DELETE /dav/{spaceId}/path — Delete file/folder MOVE /dav/{spaceId}/path — Move/rename COPY /dav/{spaceId}/path — Copy LOCK /dav/{spaceId}/path — Lock file (30-min timeout) UNLOCK /dav/{spaceId}/path — Release lock

PROPFIND response (XML):

xml <D:multistatus xmlns:D="DAV:"> <D:response> <D:href>/dav/space_abc/report.pdf</D:href> <D:propstat> <D:prop> <D:getcontentlength>5242880</D:getcontentlength> <D:getcontenttype>application/pdf</D:getcontenttype> <D:getlastmodified>2026-05-11T10:00:00Z</D:getlastmodified> <D:displayname>report.pdf</D:displayname> <D:resourcetype> <D:collection/> <!-- directory --> </D:resourcetype> </D:prop> </D:propstat> </D:response> </D:multistatus>

Authentication: Uses Aeion session cookies or Bearer tokens (same as REST API). WebDAV clients authenticate with username/password → Aeion validates → creates session.

File locking:

```typescript // LOCK acquires exclusive write lock (30-minute timeout) // UNLOCK releases // If session ends without UNLOCK → automatic release // Concurrent write attempts → 423 Locked response

interface Lock { token: string; // opaquelocktoken:uuid fileId: string; userId: string; createdAt: Date; expiresAt: Date; // 30 minutes } ```

WOPI protocol flow:

Client browser Aeion Files (WOPI Host) Collabora/ONLYOFFICE │ │ │ │ 1. GET /files/editor/{fileId} │ │ │──────────────────────────────────>│ │ │ │ │ │ 2. GET /files/wopi/discovery │ ← WOPI server info │ │──────────────────────────────────>│ │ │ │ │ │ 3. PUT /files/wopi/files/{id}/oper ← Check file info + access │ │──────────────────────────────────>│ │ │ │ │ │ 4. GET /files/wopi/files/{id}/contents ← File content for editor │ │──────────────────────────────────>│ │ │ │ │ │ 5. Open iframe: WOPI_URL?access_token=...&file_url=... │ │─────────────────────────────────────────────>│ │ │ │ │ │ 6. WOPI server fetches: GET /files/wopi/files/{id}/contents │ │─────────────────────────────────────────────>│ │ │ │ │ │ 7. User edits → WOPI saves → PUT /files/wopi/files/{id}/contents │ │─────────────────────────────────────────────>│ │ │ │ │ │ 8. Save complete → refresh preview in browser │ │ │ │

WOPI session tracking: Each editing session tracks the file being edited, the WOPI server handling it, a short-lived access token, who opened the session, and whether it's still active — so concurrent editors and lock state stay consistent.

WOPI operations supported:

• GetFileInfo — file metadata (size, MIME, modified, can edit)
• GetFile — download file content
• PutFile — save edited content back to Files module
• Lock / Unlock — concurrent edit prevention
• GetLock / RefreshLock — lock status