feat: nested folder hierarchy with parent_id, root_only filter, recursive delete

app/api/documents.py

@@ -102,11 +102,17 @@ async def get_document_status(
 @router.get("/")
 async def list_documents(
     folder_id: Optional[str] = None,
+    root_only: bool = False,
     document_service: DocumentService = Depends(get_document_service),
     current_user: User = Depends(get_current_user),
 ):
-    """List all documents."""
-    documents = await document_service.list_documents(current_user, folder_id)
+    """
+    List documents.
+    - GET /documents/                    → all documents
+    - GET /documents/?folder_id=X        → documents in folder X
+    - GET /documents/?root_only=true     → only documents with no folder (root level)
+    """
+    documents = await document_service.list_documents(current_user, folder_id, root_only)
     return [_doc_response(doc) for doc in documents]
 
 

app/api/folders.py

@@ -1,11 +1,11 @@
-"""Folders API endpoints."""
+"""Folders API — full nested folder support (real file manager)."""
 from fastapi import APIRouter, Depends, HTTPException, status
 from pydantic import BaseModel
 from sqlalchemy.orm import Session
 from app.database import get_db
 from app.auth import get_current_user
 from app.models import User, Folder, Document
-from typing import Optional
+from typing import Optional, List
 import logging
 
 logger = logging.getLogger(__name__)
@@ -14,6 +14,7 @@ router = APIRouter(prefix="/folders", tags=["folders"])
 
 class CreateFolderRequest(BaseModel):
     name: str
+    parent_id: Optional[str] = None   # None = root level
 
 
 class RenameFolderRequest(BaseModel):
@@ -22,198 +23,303 @@ class RenameFolderRequest(BaseModel):
 
 class MoveDocumentRequest(BaseModel):
     document_id: str
-    folder_id: Optional[str] = None  # None = move to root
 
 
+class MoveFolderRequest(BaseModel):
+    parent_id: Optional[str] = None   # None = move to root
+
+
+# ── Create ────────────────────────────────────────────────────────────────────
+
 @router.post("/", status_code=status.HTTP_201_CREATED)
 async def create_folder(
     request: CreateFolderRequest,
     db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
+    current_user: User = Depends(get_current_user),
 ):
-    """Create a new folder."""
-    # Check for duplicate name in same org
+    """Create a folder. Pass parent_id to create a subfolder."""
+    # Validate parent exists and belongs to same org
+    if request.parent_id:
+        parent = db.query(Folder).filter(
+            Folder.id == request.parent_id,
+            Folder.org_id == current_user.org_id,
+        ).first()
+        if not parent:
+            raise HTTPException(status_code=404, detail="Parent folder not found")
+
+    # Duplicate name check within same parent
     existing = db.query(Folder).filter(
         Folder.org_id == current_user.org_id,
-        Folder.name == request.name
+        Folder.name == request.name.strip(),
+        Folder.parent_id == request.parent_id,
     ).first()
     if existing:
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"Folder '{request.name}' already exists"
+            detail=f"A folder named '{request.name}' already exists here",
         )
 
-    folder = Folder(name=request.name, org_id=current_user.org_id)
+    folder = Folder(
+        name=request.name.strip(),
+        org_id=current_user.org_id,
+        parent_id=request.parent_id,
+    )
     db.add(folder)
     db.commit()
     db.refresh(folder)
-
     return _folder_response(folder, db)
 
 
+# ── List ──────────────────────────────────────────────────────────────────────
+
 @router.get("/")
 async def list_folders(
+    parent_id: Optional[str] = None,   # None = root level; pass id for children
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    """
+    List folders.
+    - GET /folders/          → root-level folders
+    - GET /folders/?parent_id=X → subfolders of X
+    """
+    query = db.query(Folder).filter(
+        Folder.org_id == current_user.org_id,
+        Folder.parent_id == parent_id,
+    ).order_by(Folder.created_at.desc())
+
+    return [_folder_response(f, db) for f in query.all()]
+
+
+@router.get("/tree")
+async def folder_tree(
     db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
+    current_user: User = Depends(get_current_user),
 ):
-    """List all folders with document counts."""
-    folders = db.query(Folder).filter(
+    """Return the full folder tree (all folders with nesting info)."""
+    all_folders = db.query(Folder).filter(
         Folder.org_id == current_user.org_id
     ).order_by(Folder.created_at.desc()).all()
 
-    return [_folder_response(f, db) for f in folders]
+    def build_tree(parent_id: Optional[str]) -> List[dict]:
+        nodes = [f for f in all_folders if f.parent_id == parent_id]
+        return [
+            {
+                **_folder_response(f, db),
+                "children": build_tree(f.id),
+            }
+            for f in nodes
+        ]
+
+    return build_tree(None)
 
 
+# ── Get single ────────────────────────────────────────────────────────────────
+
 @router.get("/{folder_id}")
 async def get_folder(
     folder_id: str,
     db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
+    current_user: User = Depends(get_current_user),
 ):
-    """Get a folder with its documents."""
-    folder = _get_folder_or_404(folder_id, current_user.org_id, db)
+    """Get folder details + its direct documents + subfolders."""
+    folder = _get_or_404(folder_id, current_user.org_id, db)
+
+    subfolders = db.query(Folder).filter(
+        Folder.parent_id == folder_id,
+        Folder.org_id == current_user.org_id,
+    ).order_by(Folder.created_at.desc()).all()
 
     documents = db.query(Document).filter(
         Document.folder_id == folder_id,
-        Document.org_id == current_user.org_id
+        Document.org_id == current_user.org_id,
     ).order_by(Document.created_at.desc()).all()
 
+    # Build breadcrumb path
+    path = _build_path(folder, db)
+
     return {
         **_folder_response(folder, db),
-        "documents": [_doc_response(d) for d in documents]
+        "path": path,
+        "subfolders": [_folder_response(f, db) for f in subfolders],
+        "documents": [_doc_response(d) for d in documents],
     }
 
 
+# ── Rename ────────────────────────────────────────────────────────────────────
+
 @router.patch("/{folder_id}")
 async def rename_folder(
     folder_id: str,
     request: RenameFolderRequest,
     db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
+    current_user: User = Depends(get_current_user),
 ):
-    """Rename a folder."""
-    folder = _get_folder_or_404(folder_id, current_user.org_id, db)
+    folder = _get_or_404(folder_id, current_user.org_id, db)
 
-    # Check duplicate name
+    # Duplicate check within same parent
     existing = db.query(Folder).filter(
         Folder.org_id == current_user.org_id,
-        Folder.name == request.name,
-        Folder.id != folder_id
+        Folder.name == request.name.strip(),
+        Folder.parent_id == folder.parent_id,
+        Folder.id != folder_id,
     ).first()
     if existing:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"Folder '{request.name}' already exists"
-        )
+        raise HTTPException(400, detail=f"A folder named '{request.name}' already exists here")
 
-    folder.name = request.name
+    folder.name = request.name.strip()
     db.commit()
     db.refresh(folder)
-
     return _folder_response(folder, db)
 
 
-@router.post("/{folder_id}/move-document")
-async def move_document_to_folder(
+# ── Move folder ───────────────────────────────────────────────────────────────
+
+@router.patch("/{folder_id}/move")
+async def move_folder(
     folder_id: str,
-    request: MoveDocumentRequest,
+    request: MoveFolderRequest,
     db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
+    current_user: User = Depends(get_current_user),
 ):
-    """Move a document into this folder (supports drag & drop)."""
-    _get_folder_or_404(folder_id, current_user.org_id, db)
-
-    document = db.query(Document).filter(
-        Document.id == request.document_id,
-        Document.org_id == current_user.org_id
-    ).first()
-    if not document:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Document not found")
-
-    document.folder_id = folder_id
+    """Move a folder to a different parent (or root)."""
+    folder = _get_or_404(folder_id, current_user.org_id, db)
+
+    # Prevent moving into own descendant
+    if request.parent_id:
+        if request.parent_id == folder_id:
+            raise HTTPException(400, detail="Cannot move a folder into itself")
+        if _is_descendant(folder_id, request.parent_id, db):
+            raise HTTPException(400, detail="Cannot move a folder into its own subfolder")
+        parent = db.query(Folder).filter(
+            Folder.id == request.parent_id,
+            Folder.org_id == current_user.org_id,
+        ).first()
+        if not parent:
+            raise HTTPException(404, detail="Target folder not found")
+
+    folder.parent_id = request.parent_id
     db.commit()
+    db.refresh(folder)
+    return _folder_response(folder, db)
 
-    return {"message": "Document moved successfully", "document_id": request.document_id, "folder_id": folder_id}
 
+# ── Move document into folder ─────────────────────────────────────────────────
 
-@router.delete("/{folder_id}/move-document")
-async def remove_document_from_folder(
+@router.post("/{folder_id}/move-document")
+async def move_document_to_folder(
     folder_id: str,
     request: MoveDocumentRequest,
     db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
+    current_user: User = Depends(get_current_user),
 ):
-    """Remove a document from a folder (move to root)."""
-    document = db.query(Document).filter(
+    _get_or_404(folder_id, current_user.org_id, db)
+    doc = db.query(Document).filter(
         Document.id == request.document_id,
         Document.org_id == current_user.org_id,
-        Document.folder_id == folder_id
     ).first()
-    if not document:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Document not found in this folder")
-
-    document.folder_id = None
+    if not doc:
+        raise HTTPException(404, detail="Document not found")
+    doc.folder_id = folder_id
     db.commit()
+    return {"message": "Document moved", "document_id": request.document_id, "folder_id": folder_id}
 
-    return {"message": "Document removed from folder", "document_id": request.document_id}
 
+# ── Delete ────────────────────────────────────────────────────────────────────
 
 @router.delete("/{folder_id}")
 async def delete_folder(
     folder_id: str,
     force: bool = False,
     db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
+    current_user: User = Depends(get_current_user),
 ):
-    """Delete a folder. Use ?force=true to also move documents to root."""
-    folder = _get_folder_or_404(folder_id, current_user.org_id, db)
-
-    doc_count = db.query(Document).filter(Document.folder_id == folder_id).count()
-
-    if doc_count > 0 and not force:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"Folder has {doc_count} document(s). Use ?force=true to delete and move documents to root."
-        )
+    """
+    Delete a folder.
+    - force=false (default): fails if folder has documents or subfolders
+    - force=true: recursively deletes all subfolders and moves documents to root
+    """
+    folder = _get_or_404(folder_id, current_user.org_id, db)
 
     if force:
-        # Move all documents to root
-        db.query(Document).filter(Document.folder_id == folder_id).update({"folder_id": None})
+        _recursive_delete(folder_id, current_user.org_id, db)
+    else:
+        doc_count = db.query(Document).filter(Document.folder_id == folder_id).count()
+        sub_count = db.query(Folder).filter(Folder.parent_id == folder_id).count()
+        if doc_count > 0 or sub_count > 0:
+            raise HTTPException(
+                400,
+                detail=f"Folder is not empty ({doc_count} files, {sub_count} subfolders). Use ?force=true."
+            )
+        db.delete(folder)
+        db.commit()
 
-    db.delete(folder)
-    db.commit()
+    return {"message": "Folder deleted"}
 
-    return {"message": "Folder deleted successfully"}
 
+# ── Helpers ───────────────────────────────────────────────────────────────────
 
-# ── helpers ──────────────────────────────────────────────────────────────────
-
-def _get_folder_or_404(folder_id: str, org_id: str, db: Session) -> Folder:
-    folder = db.query(Folder).filter(
-        Folder.id == folder_id,
-        Folder.org_id == org_id
-    ).first()
-    if not folder:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Folder not found")
-    return folder
+def _get_or_404(folder_id: str, org_id: str, db: Session) -> Folder:
+    f = db.query(Folder).filter(Folder.id == folder_id, Folder.org_id == org_id).first()
+    if not f:
+        raise HTTPException(404, detail="Folder not found")
+    return f
 
 
 def _folder_response(folder: Folder, db: Session) -> dict:
     doc_count = db.query(Document).filter(Document.folder_id == folder.id).count()
+    sub_count = db.query(Folder).filter(Folder.parent_id == folder.id).count()
     return {
         "id": folder.id,
         "name": folder.name,
+        "parent_id": folder.parent_id,
         "document_count": doc_count,
-        "created_at": folder.created_at.isoformat()
+        "subfolder_count": sub_count,
+        "created_at": folder.created_at.isoformat(),
     }
 
 
 def _doc_response(doc: Document) -> dict:
     return {
-        "id": doc.id,
-        "name": doc.name,
-        "size": doc.size,
-        "chunks": doc.chunks,
-        "folder_id": doc.folder_id,
-        "created_at": doc.created_at.isoformat()
+        "id": doc.id, "name": doc.name, "size": doc.size,
+        "chunks": doc.chunks, "status": doc.status,
+        "folder_id": doc.folder_id, "created_at": doc.created_at.isoformat(),
     }
+
+
+def _build_path(folder: Folder, db: Session) -> List[dict]:
+    """Build breadcrumb path from root to this folder."""
+    path = []
+    current = folder
+    while current:
+        path.insert(0, {"id": current.id, "name": current.name})
+        if current.parent_id:
+            current = db.query(Folder).filter(Folder.id == current.parent_id).first()
+        else:
+            break
+    return path
+
+
+def _is_descendant(ancestor_id: str, candidate_id: str, db: Session) -> bool:
+    """Check if candidate_id is a descendant of ancestor_id."""
+    current = db.query(Folder).filter(Folder.id == candidate_id).first()
+    while current and current.parent_id:
+        if current.parent_id == ancestor_id:
+            return True
+        current = db.query(Folder).filter(Folder.id == current.parent_id).first()
+    return False
+
+
+def _recursive_delete(folder_id: str, org_id: str, db: Session) -> None:
+    """Recursively delete folder and all subfolders; move docs to root."""
+    # Move documents to root
+    db.query(Document).filter(Document.folder_id == folder_id).update({"folder_id": None})
+    # Recurse into subfolders
+    children = db.query(Folder).filter(Folder.parent_id == folder_id, Folder.org_id == org_id).all()
+    for child in children:
+        _recursive_delete(child.id, org_id, db)
+    # Delete this folder
+    folder = db.query(Folder).filter(Folder.id == folder_id).first()
+    if folder:
+        db.delete(folder)
+    db.commit()

app/application/document_service.py

@@ -141,10 +141,20 @@ class DocumentService:
 
     # ── Other service methods ─────────────────────────────────────────────────
 
-    async def list_documents(self, user: User, folder_id: Optional[str] = None) -> List[Document]:
+    async def list_documents(
+        self,
+        user: User,
+        folder_id: Optional[str] = None,
+        root_only: bool = False
+    ) -> List[Document]:
         query = self.db.query(Document).filter(Document.org_id == user.org_id)
         if folder_id:
+            # Specific folder
             query = query.filter(Document.folder_id == folder_id)
+        elif root_only:
+            # Only files with no folder (root level)
+            query = query.filter(Document.folder_id == None)
+        # else: no filter = all documents
         return query.order_by(Document.created_at.desc()).all()
 
     async def get_document_status(self, document_id: str, user: User) -> Document:

app/database.py

@@ -59,6 +59,7 @@ def _run_migrations():
         for col_sql in [
             "ALTER TABLE documents ADD COLUMN IF NOT EXISTS status VARCHAR DEFAULT 'done'",
             "ALTER TABLE documents ADD COLUMN IF NOT EXISTS error_message TEXT",
+            "ALTER TABLE folders ADD COLUMN IF NOT EXISTS parent_id VARCHAR REFERENCES folders(id)",
         ]:
             try:
                 conn.execute(__import__('sqlalchemy').text(col_sql))

app/models.py

@@ -31,9 +31,13 @@ class Folder(Base):
     id = Column(String, primary_key=True, default=generate_uuid)
     name = Column(String, nullable=False)
     org_id = Column(String, nullable=False, index=True)
+    # parent_id = None means root-level folder
+    parent_id = Column(String, ForeignKey("folders.id"), nullable=True, index=True)
     created_at = Column(DateTime, default=datetime.utcnow)
     
     documents = relationship("Document", back_populates="folder")
+    # Self-referential: children folders
+    children = relationship("Folder", foreign_keys=[parent_id], lazy="select")
 
 
 class Document(Base):