drives initial plan

docs/drives-phase-1.md

@@ -0,0 +1,69 @@
+# Phase 1: Data Model & Setup
+
+## Objective
+Establish the database schema and directory infrastructure that underpin the entire drive system. This is a prerequisite for all subsequent work.
+
+## Concepts
+
+### Drives and Containers
+Users organize storage into named "Drives". Each drive acts as a logical folder scoped to the owner.
+
+```text
+{data_directory}/drives/{user_id}/{drive_name}/{opaque_hash}
+```
+
+- `{drive_name}`: Human-readable scope (e.g., "My Projects").
+- `{opaque_hash}`: Auto-generated alphanumeric string (UUID or SHA prefix).
+
+### Disk Hashing Strategy
+Physical filenames are opaque hashes that do not map deterministically to database IDs, preventing enumeration attacks on the filesystem level. Renaming files updates only the database record; the physical file remains untouched.
+
+## Tasks
+
+### 1.1 Define Database Models
+
+Append the following models to `backend/src/database.py`:
+
+```python
+class Drive(models.Model):
+    id = fields.IntField(pk=True)
+    user = fields.ForeignKeyField("models.User", related_name="drives")
+    name = fields.CharField(max_length=255)
+    created_at = fields.DatetimeField(auto_now_add=True)
+
+class DriveFile(models.Model):
+    id = fields.IntField(pk=True)
+    drive = fields.ForeignKeyField("models.Drive", related_name="files")
+    
+    filename = fields.CharField(max_length=500)       # Readable name (DB only)
+    disk_hash = fields.CharField(max_length=64)       # Internal disk identifier
+    mime_type = fields.CharField(max_length=255)      # Content type
+    size_bytes = fields.BigIntField()                 # Physical size
+    
+    accessed_at = fields.DatetimeField(null=True)     # Last access timestamp
+    created_at = fields.DatetimeField(auto_now_add=True)
+    
+    class Meta:
+        table = "drive_files"
+```
+
+**Design Notes:**
+- Ownership is enforced via foreign key chain (`User` → `Drive` → `File`).
+- Indexes on `drive_id` and `user_id` ensure fast listing queries.
+
+### 1.2 Run Migrations
+
+Execute:
+```bash
+python -m tortoise.makemigrations --config tortoise_config --name add_drives
+python -m tortoise.migrate --config tortoise_config
+```
+
+### 1.3 Initialize Directory Structure
+
+In `backend/src/app.py`, call the drive initialization during startup:
+```python
+await app.init_drives(data_directory)
+```
+
+Ensure this happens after any DB connection is established so that `DRIVES_ROOT` can reference the data path correctly.