goDrive Architecture¶

goDrive is a self-hosted file manager built around one core rule: the filesystem is the source of truth. SQLite stores rebuildable or operational metadata, while user files remain normal files and directories on disk.

Components¶

Data Model¶

User files live under configured user home roots. SQLite stores:

• users, password hashes, sessions, and CSRF/session state
• file index rows for search and fast listing metadata
• trash records that point to moved files under appdata
• resumable upload records
• webhook subscriptions and delivery metadata
• admin job state

The file index and preview cache are rebuildable. Durable appdata, especially the database and trash directory, should be backed up.

Request Flow¶

Browser and mobile clients authenticate through POST /api/auth/login. The server returns a bearer token and a browser session cookie. Cookie-authenticated mutating requests require X-CSRF-Token; bearer-token requests skip CSRF.

Most file operations go through internal/files.Service, which resolves user-relative paths against the user's home root before touching disk. This path confinement is the main boundary that prevents traversal and symlink escape bugs.

Upload Flow¶

goDrive uses TUS for resumable uploads:

1. POST /api/tus creates an upload record and staging file.
2. PATCH /api/tus/{id} appends chunks from web or mobile clients.
3. The final chunk atomically moves the staged file into the target folder with conflict-safe naming.
4. The server updates the file index, starts preview generation where supported, and emits upload webhooks.

Incomplete uploads are cleaned up by a periodic TTL job.

Indexing And Watcher¶

The file index is an optimization, not the source of truth. It can be rebuilt by an admin reindex job. A filesystem watcher and periodic reconciliation scan keep the index aligned with external changes from SMB, rsync, shell access, or other tools.

WebDAV operates directly on the filesystem and should either trigger index refreshes after writes or rely on watcher/reconciliation delay, depending on the final WebDAV support policy.

Preview Pipeline¶

Preview generation classifies files by kind and uses native Go handling plus external tools where needed:

• images and SVGs
• RAW photos where tooling is available
• video poster frames
• PDF previews
• Office document previews through LibreOffice
• text, Markdown, CSV, and code previews
• 3D file viewing in the web UI

Preview outputs live in appdata and are safe to delete. They are regenerated on demand or through warmup jobs.

Web UI¶

The web app is a Svelte SPA served by the backend. Direct navigation to /, /files, and /files/* returns the app shell. API calls use typed wrappers in web/src/lib/api.ts.

Heavy web features are lazy-loaded:

• CodeMirror editor bundles load only when text edit mode is opened.
• 3D thumbnail and viewer code loads only for 3D files.

Mobile¶

The Flutter app shares the same REST/TUS backend contract. Android and iOS include platform upload helpers for background-friendly uploads, while the Dart app handles auth, browsing, search, preview navigation, and admin screens.

The OpenAPI contract in docs/openapi.yaml is used to reduce drift between backend handlers, web types, and mobile models.

WebDAV¶

WebDAV is mounted under /dav/ for native clients such as Finder, iOS Files, and rclone. Basic and bearer authentication are the preferred modes. Browser cookie auth is accepted for reads, but mutating WebDAV requests require CSRF protection.

WebDAV intentionally does not expose every web/admin feature. It is a file-access protocol surface, not a full API replacement.

Demo Mode¶

Demo mode is designed for public evaluation, not real user data. It uses disposable seed data, blocks dangerous admin/write surfaces, constrains uploads, shows a public-data banner, and resets through deployment/container lifecycle controls.

The demo image uses the full production preview toolchain so the public demo exercises the real preview path.

Security Boundaries¶

Important boundaries:

• user home-root confinement for all filesystem operations
• authentication and CSRF separation between browser cookies and bearer/API clients
• login and auth rate limiting
• webhook egress controls to avoid SSRF into private networks by default
• preview tool timeouts, isolated temp directories, and resource limits
• demo-mode blocks for admin mutations, writes, WebDAV, webhooks, and API keys

goDrive is intended for small private self-hosted deployments. Treat public multi-tenant exposure as out of scope unless the architecture is revisited.

Performance¶

Baseline measured on a 400k-file (830k index entry) dataset using make perf-test:

Key design decisions behind these numbers:

• Directory listing joins against document_snippets (B-tree, PRIMARY KEY (user_id, path)) instead of document_fts (FTS5 virtual table). FTS5 with UNINDEXED columns does a full scan per row; the plain table gives O(log n) lookup.
• Reindex uses max(numCPU-2, 1) workers, merged transactions (batch 2000), and defers FTS5 and document staging to the finalization phase so per-file overhead stays low.
• vipsthumbnail is invoked with --vips-concurrency=1 to prevent per-process thread pools from multiplying RAM usage under parallel preview workers.

Local Quality Gates¶

Use local checks before hosted CI:

make test
make web-check
make web-test
make web-build
make mobile-test
make api-contract

Use act for Linux workflow validation where practical. GitHub-hosted runners are reserved for release publishing, scheduled security checks, and iOS/macOS builds.