Merge branch 'Refactor/Folder-Layout'

Backend/internal/bootstrap/service.go

@@ -9,9 +9,11 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"sort"
 	"strings"
 	"unicode"
 
+	"github.com/google/uuid"
 	"github.com/jackc/pgx/v5"
 
 	"moku-backend/internal/database"
@@ -38,6 +40,9 @@ const (
 	bootstrapWorkspaceKindDept    = "department"
 	bootstrapWorkspaceKindTeam    = "team"
 	bootstrapWorkspaceKindProject = "project"
+	projectFolderOrderRootKey     = "__root__"
+	projectFolderOrderHierarchy   = "hierarchy"
+	projectFolderOrderTree        = "tree"
 )
 
 var (
@@ -45,6 +50,7 @@ var (
 	ErrAdminNotConfigured        = errors.New("bootstrap admin step has not been completed")
 	ErrProjectNotFound           = errors.New("project not found")
 	ErrProjectFolderNotFound     = errors.New("project folder not found")
+	ErrInvalidProjectFolderMove  = errors.New("invalid project folder move")
 )
 
 type Service struct {
@@ -182,6 +188,7 @@ type namedRecord struct {
 
 type ProjectHierarchyFolderRecord struct {
 	ID       string                         `json:"id"`
+	Path     string                         `json:"path"`
 	Label    string                         `json:"label"`
 	Children []ProjectHierarchyFolderRecord `json:"children"`
 }
@@ -203,6 +210,15 @@ type RenameProjectFolderInput struct {
 	Name      string
 }
 
+type MoveProjectFolderInput struct {
+	ProjectID      string
+	FolderID       string
+	FolderNodeID   string
+	ParentFolderID string
+	ParentNodeID   string
+	TargetIndex    int
+}
+
 type CreateProjectFolderResult struct {
 	ProjectID     string                         `json:"projectId"`
 	CreatedFolder ProjectHierarchyFolderRecord   `json:"createdFolder"`
@@ -210,19 +226,30 @@ type CreateProjectFolderResult struct {
 }
 
 type DeleteProjectFolderResult struct {
-	ProjectID       string                         `json:"projectId"`
+	ProjectID         string                         `json:"projectId"`
-	DeletedFolderID string                         `json:"deletedFolderId"`
+	DeletedFolderID   string                         `json:"deletedFolderId"`
-	Folders         []ProjectHierarchyFolderRecord `json:"folders"`
+	DeletedFolderPath string                         `json:"deletedFolderPath"`
+	Folders           []ProjectHierarchyFolderRecord `json:"folders"`
 }
 
 type RenameProjectFolderResult struct {
-	ProjectID        string                         `json:"projectId"`
+	ProjectID          string                         `json:"projectId"`
-	PreviousFolderID string                         `json:"previousFolderId"`
+	PreviousFolderID   string                         `json:"previousFolderId"`
-	RenamedFolder    ProjectHierarchyFolderRecord   `json:"renamedFolder"`
+	PreviousFolderPath string                         `json:"previousFolderPath"`
-	Folders          []ProjectHierarchyFolderRecord `json:"folders"`
+	RenamedFolder      ProjectHierarchyFolderRecord   `json:"renamedFolder"`
+	Folders            []ProjectHierarchyFolderRecord `json:"folders"`
+}
+
+type MoveProjectFolderResult struct {
+	ProjectID          string                         `json:"projectId"`
+	PreviousFolderID   string                         `json:"previousFolderId"`
+	PreviousFolderPath string                         `json:"previousFolderPath"`
+	MovedFolder        ProjectHierarchyFolderRecord   `json:"movedFolder"`
+	Folders            []ProjectHierarchyFolderRecord `json:"folders"`
 }
 
 type projectHierarchyFolderRow struct {
+	ID         string
 	Path       string
 	ParentPath string
 	Label      string
@@ -886,6 +913,7 @@ func (service *Service) getProjectHierarchyFoldersByRootPath(
 
 	rows, err := service.db.Pool.Query(ctx, `
 		SELECT
+			COALESCE(folder_meta.resource_id, ''),
 			directories.path,
 			COALESCE(directories.parent_path, ''),
 			COALESCE(folder_meta.resource_name, directories.resource_name, '')
@@ -907,7 +935,7 @@ func (service *Service) getProjectHierarchyFoldersByRootPath(
 	var folderRows []projectHierarchyFolderRow
 	for rows.Next() {
 		var row projectHierarchyFolderRow
-		if err := rows.Scan(&row.Path, &row.ParentPath, &row.Label); err != nil {
+		if err := rows.Scan(&row.ID, &row.Path, &row.ParentPath, &row.Label); err != nil {
 			return nil, err
 		}
 		folderRows = append(folderRows, row)
@@ -917,7 +945,10 @@ func (service *Service) getProjectHierarchyFoldersByRootPath(
 		return nil, err
 	}
 
-	return buildProjectHierarchyFolderTree(folderRows, rootParentPath), nil
+	folders := buildProjectHierarchyFolderTree(folderRows, rootParentPath)
+	folderOrder := service.readProjectFolderOrder(project.Slug, rootParentPath)
+
+	return applyProjectHierarchyFolderOrdering(folders, folderOrder), nil
 }
 
 func (service *Service) CreateProjectFolder(ctx context.Context, input CreateProjectFolderInput) (CreateProjectFolderResult, error) {
@@ -944,6 +975,14 @@ func (service *Service) RenameProjectTreeFolder(ctx context.Context, input Renam
 	return service.renameProjectHierarchyFolder(ctx, input, projectTreeRootPath, service.renameProjectTreeFolderOnDisk)
 }
 
+func (service *Service) MoveProjectFolder(ctx context.Context, input MoveProjectFolderInput) (MoveProjectFolderResult, error) {
+	return service.moveProjectHierarchyFolder(ctx, input, projectHierarchyRootPath, service.moveProjectHierarchyFolderOnDisk)
+}
+
+func (service *Service) MoveProjectTreeFolder(ctx context.Context, input MoveProjectFolderInput) (MoveProjectFolderResult, error) {
+	return service.moveProjectHierarchyFolder(ctx, input, projectTreeRootPath, service.moveProjectTreeFolderOnDisk)
+}
+
 func (service *Service) createProjectHierarchyFolder(
 	ctx context.Context,
 	input CreateProjectFolderInput,
@@ -955,6 +994,21 @@ func (service *Service) createProjectHierarchyFolder(
 		return CreateProjectFolderResult{}, err
 	}
 
+	currentFolders, err := service.getProjectHierarchyFoldersByRootPath(ctx, project.ID, rootPath)
+	if err != nil {
+		return CreateProjectFolderResult{}, err
+	}
+
+	parentOrderID := ""
+	trimmedParentFolderID := strings.TrimSpace(input.ParentFolderID)
+	if trimmedParentFolderID != "" {
+		parentFolder, found := findProjectHierarchyFolderByPath(currentFolders, trimmedParentFolderID)
+		if !found {
+			return CreateProjectFolderResult{}, ErrProjectFolderNotFound
+		}
+		parentOrderID = parentFolder.ID
+	}
+
 	createdPath, _, err := createOnDisk(project.Slug, strings.TrimSpace(input.ParentFolderID), input.Name)
 	if err != nil {
 		return CreateProjectFolderResult{}, err
@@ -969,11 +1023,28 @@ func (service *Service) createProjectHierarchyFolder(
 		return CreateProjectFolderResult{}, err
 	}
 
-	createdFolder, ok := findProjectHierarchyFolder(folders, createdPath)
+	createdFolder, ok := findProjectHierarchyFolderByPath(folders, createdPath)
 	if !ok {
 		return CreateProjectFolderResult{}, fmt.Errorf("created project folder missing from projection")
 	}
 
+	folderOrder := service.readProjectFolderOrder(project.Slug, rootPath(project.Slug))
+	seedFolderOrderParent(folderOrder, currentFolders, parentOrderID)
+	insertFolderOrder(folderOrder, parentOrderID, createdFolder.ID, len(folderOrderChildren(folderOrder, parentOrderID)))
+	if err := service.writeProjectFolderOrder(project.Slug, rootPath(project.Slug), folderOrder); err != nil {
+		return CreateProjectFolderResult{}, err
+	}
+
+	folders, err = service.getProjectHierarchyFoldersByRootPath(ctx, project.ID, rootPath)
+	if err != nil {
+		return CreateProjectFolderResult{}, err
+	}
+
+	createdFolder, ok = findProjectHierarchyFolderByPath(folders, createdPath)
+	if !ok {
+		return CreateProjectFolderResult{}, fmt.Errorf("created project folder missing from ordered projection")
+	}
+
 	return CreateProjectFolderResult{
 		ProjectID:     project.ID,
 		CreatedFolder: createdFolder,
@@ -992,6 +1063,16 @@ func (service *Service) deleteProjectHierarchyFolder(
 		return DeleteProjectFolderResult{}, err
 	}
 
+	currentFolders, err := service.getProjectHierarchyFoldersByRootPath(ctx, project.ID, rootPath)
+	if err != nil {
+		return DeleteProjectFolderResult{}, err
+	}
+
+	deletedFolder, found := findProjectHierarchyFolderByPath(currentFolders, strings.TrimSpace(input.FolderID))
+	if !found {
+		return DeleteProjectFolderResult{}, ErrProjectFolderNotFound
+	}
+
 	deletedFolderID, err := deleteOnDisk(project.Slug, input.FolderID)
 	if err != nil {
 		return DeleteProjectFolderResult{}, err
@@ -1006,14 +1087,26 @@ func (service *Service) deleteProjectHierarchyFolder(
 		return DeleteProjectFolderResult{}, err
 	}
 
-	if _, found := findProjectHierarchyFolder(folders, deletedFolderID); found {
+	if _, found := findProjectHierarchyFolderByPath(folders, deletedFolderID); found {
 		return DeleteProjectFolderResult{}, fmt.Errorf("deleted project folder still present in projection")
 	}
 
+	folderOrder := service.readProjectFolderOrder(project.Slug, rootPath(project.Slug))
+	removeFolderOrder(folderOrder, deletedFolder.ID)
+	if err := service.writeProjectFolderOrder(project.Slug, rootPath(project.Slug), folderOrder); err != nil {
+		return DeleteProjectFolderResult{}, err
+	}
+
+	folders, err = service.getProjectHierarchyFoldersByRootPath(ctx, project.ID, rootPath)
+	if err != nil {
+		return DeleteProjectFolderResult{}, err
+	}
+
 	return DeleteProjectFolderResult{
-		ProjectID:       project.ID,
+		ProjectID:         project.ID,
-		DeletedFolderID: deletedFolderID,
+		DeletedFolderID:   deletedFolder.ID,
-		Folders:         folders,
+		DeletedFolderPath: deletedFolderID,
+		Folders:           folders,
 	}, nil
 }
 
@@ -1042,20 +1135,117 @@ func (service *Service) renameProjectHierarchyFolder(
 		return RenameProjectFolderResult{}, err
 	}
 
-	renamedFolder, found := findProjectHierarchyFolder(folders, renamedFolderID)
+	renamedFolder, found := findProjectHierarchyFolderByPath(folders, renamedFolderID)
 	if !found {
 		return RenameProjectFolderResult{}, fmt.Errorf("renamed project folder missing from projection")
 	}
 
-	if _, found := findProjectHierarchyFolder(folders, previousFolderID); found {
+	if _, found := findProjectHierarchyFolderByPath(folders, previousFolderID); found {
 		return RenameProjectFolderResult{}, fmt.Errorf("previous project folder path still present in projection")
 	}
 
 	return RenameProjectFolderResult{
-		ProjectID:        project.ID,
+		ProjectID:          project.ID,
-		PreviousFolderID: previousFolderID,
+		PreviousFolderID:   renamedFolder.ID,
-		RenamedFolder:    renamedFolder,
+		PreviousFolderPath: previousFolderID,
-		Folders:          folders,
+		RenamedFolder:      renamedFolder,
+		Folders:            folders,
+	}, nil
+}
+
+func (service *Service) moveProjectHierarchyFolder(
+	ctx context.Context,
+	input MoveProjectFolderInput,
+	rootPath func(projectSlug string) string,
+	moveOnDisk func(projectSlug, folderID, parentFolderID string) (string, string, error),
+) (MoveProjectFolderResult, error) {
+	project, err := service.loadProjectByID(ctx, strings.TrimSpace(input.ProjectID))
+	if err != nil {
+		return MoveProjectFolderResult{}, err
+	}
+
+	currentFolders, err := service.getProjectHierarchyFoldersByRootPath(ctx, project.ID, rootPath)
+	if err != nil {
+		return MoveProjectFolderResult{}, err
+	}
+
+	currentFolder, found := findProjectHierarchyFolderByPath(currentFolders, strings.TrimSpace(input.FolderID))
+	if !found {
+		return MoveProjectFolderResult{}, ErrProjectFolderNotFound
+	}
+
+	movedFolderOrderID := currentFolder.ID
+	providedFolderNodeID := strings.TrimSpace(input.FolderNodeID)
+	if providedFolderNodeID != "" && providedFolderNodeID != movedFolderOrderID {
+		return MoveProjectFolderResult{}, ErrInvalidProjectFolderMove
+	}
+
+	parentOrderID := ""
+	trimmedParentFolderID := strings.TrimSpace(input.ParentFolderID)
+	providedParentNodeID := strings.TrimSpace(input.ParentNodeID)
+	if trimmedParentFolderID != "" {
+		parentFolder, found := findProjectHierarchyFolderByPath(currentFolders, trimmedParentFolderID)
+		if !found {
+			return MoveProjectFolderResult{}, ErrProjectFolderNotFound
+		}
+		parentOrderID = parentFolder.ID
+		if providedParentNodeID != "" && providedParentNodeID != parentOrderID {
+			return MoveProjectFolderResult{}, ErrInvalidProjectFolderMove
+		}
+	} else if providedParentNodeID != "" {
+		return MoveProjectFolderResult{}, ErrInvalidProjectFolderMove
+	}
+
+	previousFolderID, movedFolderID, err := moveOnDisk(project.Slug, input.FolderID, input.ParentFolderID)
+	if err != nil {
+		return MoveProjectFolderResult{}, err
+	}
+
+	if err := posixproj.NewProjector(service.db, service.posixRoot).Rebuild(ctx); err != nil {
+		return MoveProjectFolderResult{}, fmt.Errorf("rebuild POSIX projection: %w", err)
+	}
+
+	folders, err := service.getProjectHierarchyFoldersByRootPath(ctx, project.ID, rootPath)
+	if err != nil {
+		return MoveProjectFolderResult{}, err
+	}
+
+	movedFolder, found := findProjectHierarchyFolderByPath(folders, movedFolderID)
+	if !found {
+		return MoveProjectFolderResult{}, fmt.Errorf("moved project folder missing from projection")
+	}
+
+	if previousFolderID != movedFolderID {
+		if _, found := findProjectHierarchyFolderByPath(folders, previousFolderID); found {
+			return MoveProjectFolderResult{}, fmt.Errorf("previous project folder path still present in projection")
+		}
+	}
+
+	folderOrder := service.readProjectFolderOrder(project.Slug, rootPath(project.Slug))
+	seedFolderOrderParent(folderOrder, currentFolders, parentOrderID)
+	removeFolderOrderReference(folderOrder, movedFolderOrderID)
+	removeFolderOrderReference(folderOrder, movedFolder.ID)
+	insertFolderOrder(folderOrder, parentOrderID, movedFolder.ID, input.TargetIndex)
+	if err := service.writeProjectFolderOrder(project.Slug, rootPath(project.Slug), folderOrder); err != nil {
+		return MoveProjectFolderResult{}, err
+	}
+
+	folders, err = service.getProjectHierarchyFoldersByRootPath(ctx, project.ID, rootPath)
+	if err != nil {
+		return MoveProjectFolderResult{}, err
+	}
+
+	movedFolder, found = findProjectHierarchyFolderByPath(folders, movedFolderID)
+	if !found {
+		return MoveProjectFolderResult{}, fmt.Errorf("moved project folder missing from ordered projection")
+	}
+
+	return MoveProjectFolderResult{
+		ProjectID:          project.ID,
+		PreviousFolderID:   movedFolder.ID,
+		PreviousFolderPath: previousFolderID,
+		MovedFolder:        movedFolder,
+		Folders:            folders,
 	}, nil
 }
 
@@ -1238,6 +1428,12 @@ func (service *Service) ensureBootstrapPOSIXSkeleton(
 	teamPath := filepath.Join(departmentPath, "teams", slugDir("team", team.Slug))
 	projectPath := filepath.Join(rootPath, "projects", slugDir("project", project.Slug))
 	usersPath := filepath.Join(rootPath, "users")
+	personalName := strings.TrimSpace(admin.DisplayName)
+	if personalName == "" {
+		personalName = defaultPersonalDisplayName
+	}
+	personalSlug := normalizePOSIXSlug(personalName)
+	personalHomePath := filepath.Join(usersPath, "personals", slugDir("personal", personalSlug))
 
 	for _, dirPath := range []string{
 		departmentPath,
@@ -1246,6 +1442,8 @@ func (service *Service) ensureBootstrapPOSIXSkeleton(
 		filepath.Join(projectPath, "children"),
 		filepath.Join(projectPath, "tree"),
 		filepath.Join(usersPath, "personals"),
+		personalHomePath,
+		filepath.Join(personalHomePath, "tree"),
 	} {
 		if err := os.MkdirAll(dirPath, 0o755); err != nil {
 			return fmt.Errorf("create POSIX directory %s: %w", dirPath, err)
@@ -1331,6 +1529,37 @@ func (service *Service) ensureBootstrapPOSIXSkeleton(
 		return fmt.Errorf("write users data.json: %w", err)
 	}
 
+	if err := writeJSONFile(filepath.Join(personalHomePath, "settings.json"), map[string]any{
+		"id":          admin.ID,
+		"name":        personalName,
+		"slug":        personalSlug,
+		"type":        "personal",
+		"ownerUserId": admin.ID,
+		"email":       admin.Email,
+	}); err != nil {
+		return fmt.Errorf("write personal settings.json: %w", err)
+	}
+
+	if err := writeJSONFile(filepath.Join(personalHomePath, "layout.json"), map[string]any{
+		"version": 1,
+		"type":    "personal-layout",
+	}); err != nil {
+		return fmt.Errorf("write personal layout.json: %w", err)
+	}
+
+	if err := writeJSONFile(filepath.Join(personalHomePath, "home.json"), map[string]any{
+		"type":  "personal-home",
+		"title": personalHomeTitle(personalName),
+		"owner": map[string]any{
+			"id":          admin.ID,
+			"email":       admin.Email,
+			"displayName": personalName,
+		},
+		"widgets": []any{},
+	}); err != nil {
+		return fmt.Errorf("write personal home.json: %w", err)
+	}
+
 	return nil
 }
 
@@ -1358,6 +1587,14 @@ func (service *Service) renameProjectTreeFolderOnDisk(projectSlug, folderID, nam
 	return service.renameProjectFolderOnDisk(projectSlug, folderID, name, projectTreeRootPath)
 }
 
+func (service *Service) moveProjectHierarchyFolderOnDisk(projectSlug, folderID, parentFolderID string) (string, string, error) {
+	return service.moveProjectFolderOnDisk(projectSlug, folderID, parentFolderID, projectHierarchyRootPath)
+}
+
+func (service *Service) moveProjectTreeFolderOnDisk(projectSlug, folderID, parentFolderID string) (string, string, error) {
+	return service.moveProjectFolderOnDisk(projectSlug, folderID, parentFolderID, projectTreeRootPath)
+}
+
 func (service *Service) createProjectFolderOnDisk(
 	projectSlug, parentFolderID, name string,
 	rootPathBuilder func(projectSlug string) string,
@@ -1415,7 +1652,10 @@ func (service *Service) createProjectFolderOnDisk(
 		return "", "", fmt.Errorf("create project hierarchy folder: %w", err)
 	}
 
+	folderID := uuid.NewString()
+
 	if err := writeJSONFile(filepath.Join(folderDir, "folder.json"), map[string]any{
+		"id":   folderID,
 		"name": trimmedName,
 		"slug": folderSlug,
 		"type": "folder",
@@ -1539,7 +1779,14 @@ func (service *Service) renameProjectFolderOnDisk(
 		}
 	}
 
+	folderPayload := readJSONFileMap(filepath.Join(destinationDir, "folder.json"))
+	folderMetadataID, _ := folderPayload["id"].(string)
+	if strings.TrimSpace(folderMetadataID) == "" {
+		folderMetadataID = uuid.NewString()
+	}
+
 	if err := writeJSONFile(filepath.Join(destinationDir, "folder.json"), map[string]any{
+		"id":   folderMetadataID,
 		"name": trimmedName,
 		"slug": folderSlug,
 		"type": "folder",
@@ -1550,6 +1797,406 @@ func (service *Service) renameProjectFolderOnDisk(
 	return folderProjectionPath, renamedProjectionPath, nil
 }
 
+func (service *Service) moveProjectFolderOnDisk(
+	projectSlug, folderID, parentFolderID string,
+	rootPathBuilder func(projectSlug string) string,
+) (string, string, error) {
+	posixRoot := strings.TrimSpace(service.posixRoot)
+	if posixRoot == "" {
+		return "", "", fmt.Errorf("POSIX root is not configured")
+	}
+
+	rootProjectionPath := rootPathBuilder(projectSlug)
+	folderProjectionPath := strings.TrimPrefix(filepath.ToSlash(filepath.Clean("/"+strings.TrimSpace(folderID))), "/")
+	if folderProjectionPath == "." || folderProjectionPath == rootProjectionPath || !strings.HasPrefix(folderProjectionPath, rootProjectionPath+"/") {
+		return "", "", ErrProjectFolderNotFound
+	}
+
+	folderDir := filepath.Join(posixRoot, filepath.FromSlash(folderProjectionPath))
+	info, err := os.Stat(folderDir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return "", "", ErrProjectFolderNotFound
+		}
+		return "", "", fmt.Errorf("stat project folder: %w", err)
+	}
+	if !info.IsDir() {
+		return "", "", ErrProjectFolderNotFound
+	}
+
+	trimmedParentFolderID := strings.TrimSpace(parentFolderID)
+	parentChildrenProjectionPath := rootProjectionPath
+	parentDir := filepath.Join(posixRoot, filepath.FromSlash(rootProjectionPath))
+
+	if trimmedParentFolderID != "" {
+		parentProjectionPath := strings.TrimPrefix(filepath.ToSlash(filepath.Clean("/"+trimmedParentFolderID)), "/")
+		if parentProjectionPath == "." || parentProjectionPath == rootProjectionPath || !strings.HasPrefix(parentProjectionPath, rootProjectionPath+"/") {
+			return "", "", ErrProjectFolderNotFound
+		}
+		if parentProjectionPath == folderProjectionPath || strings.HasPrefix(parentProjectionPath, folderProjectionPath+"/children/") {
+			return "", "", ErrInvalidProjectFolderMove
+		}
+
+		parentChildrenProjectionPath = filepath.ToSlash(filepath.Join(parentProjectionPath, "children"))
+		parentDir = filepath.Join(posixRoot, filepath.FromSlash(parentChildrenProjectionPath))
+	}
+
+	parentInfo, err := os.Stat(parentDir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return "", "", ErrProjectFolderNotFound
+		}
+		return "", "", fmt.Errorf("stat project folder parent: %w", err)
+	}
+	if !parentInfo.IsDir() {
+		return "", "", ErrProjectFolderNotFound
+	}
+
+	currentParentDir := filepath.Dir(folderDir)
+	if samePath(currentParentDir, parentDir) {
+		return folderProjectionPath, folderProjectionPath, nil
+	}
+
+	folderPayload := readJSONFileMap(filepath.Join(folderDir, "folder.json"))
+	folderMetadataID, _ := folderPayload["id"].(string)
+	if strings.TrimSpace(folderMetadataID) == "" {
+		folderMetadataID = uuid.NewString()
+	}
+	folderName, _ := folderPayload["name"].(string)
+	if strings.TrimSpace(folderName) == "" {
+		folderName = fallbackFolderLabel(folderProjectionPath)
+	}
+
+	currentBase := filepath.Base(folderDir)
+	baseSlug := strings.TrimPrefix(currentBase, "folder-")
+	if strings.TrimSpace(baseSlug) == "" {
+		baseSlug = normalizePOSIXSlug(folderName)
+	}
+
+	folderSlug := baseSlug
+	folderDirName := slugDir("folder", folderSlug)
+	destinationDir := filepath.Join(parentDir, folderDirName)
+	for attempt := 2; ; attempt += 1 {
+		if _, err := os.Stat(destinationDir); os.IsNotExist(err) {
+			break
+		} else if err != nil {
+			return "", "", fmt.Errorf("stat candidate moved project folder: %w", err)
+		}
+
+		folderSlug = fmt.Sprintf("%s-%d", baseSlug, attempt)
+		folderDirName = slugDir("folder", folderSlug)
+		destinationDir = filepath.Join(parentDir, folderDirName)
+	}
+
+	if err := os.Rename(folderDir, destinationDir); err != nil {
+		return "", "", fmt.Errorf("move project folder: %w", err)
+	}
+
+	folderPayload["id"] = folderMetadataID
+	folderPayload["name"] = folderName
+	folderPayload["slug"] = folderSlug
+	folderPayload["type"] = "folder"
+	if err := writeJSONFile(filepath.Join(destinationDir, "folder.json"), folderPayload); err != nil {
+		return "", "", fmt.Errorf("write moved project folder.json: %w", err)
+	}
+
+	movedProjectionPath := filepath.ToSlash(filepath.Join(parentChildrenProjectionPath, folderDirName))
+	return folderProjectionPath, movedProjectionPath, nil
+}
+
+func samePath(left, right string) bool {
+	cleanLeft := filepath.Clean(left)
+	cleanRight := filepath.Clean(right)
+	if cleanLeft == cleanRight {
+		return true
+	}
+	leftInfo, leftErr := os.Stat(cleanLeft)
+	rightInfo, rightErr := os.Stat(cleanRight)
+	if leftErr == nil && rightErr == nil {
+		return os.SameFile(leftInfo, rightInfo)
+	}
+	return false
+}
+
+func (service *Service) readProjectFolderOrder(projectSlug, rootProjectionPath string) map[string][]string {
+	settingsPath := service.projectSettingsPath(projectSlug)
+	settingsPayload := readJSONFileMap(settingsPath)
+	folderOrderPayload, _ := settingsPayload["folderOrder"].(map[string]any)
+	if folderOrderPayload == nil {
+		return map[string][]string{}
+	}
+
+	scopePayload, _ := folderOrderPayload[projectFolderOrderScope(rootProjectionPath)].(map[string]any)
+	if scopePayload == nil {
+		return map[string][]string{}
+	}
+
+	byParentPayload, _ := scopePayload["byParent"].(map[string]any)
+	if byParentPayload == nil {
+		return map[string][]string{}
+	}
+
+	order := make(map[string][]string, len(byParentPayload))
+	for key, raw := range byParentPayload {
+		for _, id := range stringSliceValue(raw) {
+			trimmedID := strings.TrimSpace(id)
+			if trimmedID == "" || slicesContains(order[key], trimmedID) {
+				continue
+			}
+			order[key] = append(order[key], trimmedID)
+		}
+	}
+
+	return order
+}
+
+func (service *Service) writeProjectFolderOrder(projectSlug, rootProjectionPath string, folderOrder map[string][]string) error {
+	settingsPath := service.projectSettingsPath(projectSlug)
+	settingsPayload := readJSONFileMap(settingsPath)
+	if settingsPayload == nil {
+		settingsPayload = map[string]any{}
+	}
+
+	folderOrderPayload, _ := settingsPayload["folderOrder"].(map[string]any)
+	if folderOrderPayload == nil {
+		folderOrderPayload = map[string]any{}
+	}
+
+	scopeKey := projectFolderOrderScope(rootProjectionPath)
+	scopePayload, _ := folderOrderPayload[scopeKey].(map[string]any)
+	if scopePayload == nil {
+		scopePayload = map[string]any{}
+	}
+
+	byParentPayload := map[string]any{}
+	for key, ids := range folderOrder {
+		if len(ids) == 0 {
+			continue
+		}
+		copied := make([]string, 0, len(ids))
+		for _, id := range ids {
+			trimmedID := strings.TrimSpace(id)
+			if trimmedID == "" || slicesContains(copied, trimmedID) {
+				continue
+			}
+			copied = append(copied, trimmedID)
+		}
+		if len(copied) > 0 {
+			byParentPayload[key] = copied
+		}
+	}
+
+	scopePayload["byParent"] = byParentPayload
+	folderOrderPayload[scopeKey] = scopePayload
+	settingsPayload["folderOrder"] = folderOrderPayload
+
+	if err := writeJSONFile(settingsPath, settingsPayload); err != nil {
+		return fmt.Errorf("write project settings.json: %w", err)
+	}
+
+	return nil
+}
+
+func (service *Service) projectSettingsPath(projectSlug string) string {
+	return filepath.Join(strings.TrimSpace(service.posixRoot), "projects", slugDir("project", projectSlug), "settings.json")
+}
+
+func projectFolderOrderScope(rootProjectionPath string) string {
+	if strings.HasSuffix(rootProjectionPath, "/tree") {
+		return projectFolderOrderTree
+	}
+
+	return projectFolderOrderHierarchy
+}
+
+func applyProjectHierarchyFolderOrdering(folders []ProjectHierarchyFolderRecord, folderOrder map[string][]string) []ProjectHierarchyFolderRecord {
+	return applyProjectHierarchyFolderOrderingForParent(folders, "", folderOrder)
+}
+
+func applyProjectHierarchyFolderOrderingForParent(folders []ProjectHierarchyFolderRecord, parentID string, folderOrder map[string][]string) []ProjectHierarchyFolderRecord {
+	if len(folders) == 0 {
+		return folders
+	}
+
+	nextFolders := make([]ProjectHierarchyFolderRecord, len(folders))
+	copy(nextFolders, folders)
+	for index := range nextFolders {
+		nextFolders[index].Children = applyProjectHierarchyFolderOrderingForParent(nextFolders[index].Children, nextFolders[index].ID, folderOrder)
+	}
+
+	orderIDs := folderOrder[projectFolderOrderParentKey(parentID)]
+	if len(orderIDs) == 0 {
+		return nextFolders
+	}
+
+	rankByID := make(map[string]int, len(orderIDs))
+	for index, id := range orderIDs {
+		if _, exists := rankByID[id]; !exists {
+			rankByID[id] = index
+		}
+	}
+
+	sort.SliceStable(nextFolders, func(left, right int) bool {
+		leftRank, leftOrdered := rankByID[nextFolders[left].ID]
+		rightRank, rightOrdered := rankByID[nextFolders[right].ID]
+		if leftOrdered && rightOrdered {
+			return leftRank < rightRank
+		}
+		if leftOrdered != rightOrdered {
+			return leftOrdered
+		}
+		return false
+	})
+
+	return nextFolders
+}
+
+func removeFolderOrder(folderOrder map[string][]string, folderID string) {
+	removeFolderOrderReference(folderOrder, folderID)
+
+	trimmedFolderID := strings.TrimSpace(folderID)
+	if trimmedFolderID == "" {
+		return
+	}
+
+	delete(folderOrder, projectFolderOrderParentKey(trimmedFolderID))
+}
+
+func removeFolderOrderReference(folderOrder map[string][]string, folderID string) {
+	trimmedFolderID := strings.TrimSpace(folderID)
+	if trimmedFolderID == "" {
+		return
+	}
+
+	for key, ids := range folderOrder {
+		nextIDs := ids[:0]
+		for _, id := range ids {
+			if strings.TrimSpace(id) == trimmedFolderID {
+				continue
+			}
+			nextIDs = append(nextIDs, id)
+		}
+		if len(nextIDs) == 0 {
+			delete(folderOrder, key)
+			continue
+		}
+		folderOrder[key] = append([]string(nil), nextIDs...)
+	}
+}
+
+func insertFolderOrder(folderOrder map[string][]string, parentID, folderID string, index int) {
+	trimmedFolderID := strings.TrimSpace(folderID)
+	if trimmedFolderID == "" {
+		return
+	}
+
+	removeFolderOrderReference(folderOrder, trimmedFolderID)
+
+	parentKey := projectFolderOrderParentKey(parentID)
+	children := append([]string(nil), folderOrder[parentKey]...)
+	if index < 0 {
+		index = 0
+	}
+	if index > len(children) {
+		index = len(children)
+	}
+	children = slicesInsert(children, index, trimmedFolderID)
+	folderOrder[parentKey] = children
+}
+
+func seedFolderOrderParent(folderOrder map[string][]string, folders []ProjectHierarchyFolderRecord, parentID string) {
+	children := folders
+	trimmedParentID := strings.TrimSpace(parentID)
+	if trimmedParentID != "" {
+		parent, found := findProjectHierarchyFolder(folders, trimmedParentID)
+		if !found {
+			return
+		}
+		children = parent.Children
+	}
+
+	parentKey := projectFolderOrderParentKey(trimmedParentID)
+	seeded := make([]string, 0, len(children))
+	for _, child := range children {
+		childID := strings.TrimSpace(child.ID)
+		if childID == "" || slicesContains(seeded, childID) {
+			continue
+		}
+		seeded = append(seeded, childID)
+	}
+
+	if len(seeded) == 0 {
+		delete(folderOrder, parentKey)
+		return
+	}
+
+	folderOrder[parentKey] = seeded
+}
+
+func folderOrderChildren(folderOrder map[string][]string, parentID string) []string {
+	return append([]string(nil), folderOrder[projectFolderOrderParentKey(parentID)]...)
+}
+
+func projectFolderOrderParentKey(parentID string) string {
+	trimmedParentID := strings.TrimSpace(parentID)
+	if trimmedParentID == "" {
+		return projectFolderOrderRootKey
+	}
+
+	return trimmedParentID
+}
+
+func stringSliceValue(value any) []string {
+	items, ok := value.([]any)
+	if !ok {
+		if typed, ok := value.([]string); ok {
+			return typed
+		}
+		return nil
+	}
+
+	result := make([]string, 0, len(items))
+	for _, item := range items {
+		text, ok := item.(string)
+		if ok {
+			result = append(result, text)
+		}
+	}
+
+	return result
+}
+
+func slicesContains(values []string, value string) bool {
+	for _, existing := range values {
+		if existing == value {
+			return true
+		}
+	}
+
+	return false
+}
+
+func slicesInsert(values []string, index int, value string) []string {
+	values = append(values, "")
+	copy(values[index+1:], values[index:])
+	values[index] = value
+	return values
+}
+
+func readJSONFileMap(path string) map[string]any {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return map[string]any{}
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal(data, &payload); err != nil || payload == nil {
+		return map[string]any{}
+	}
+
+	return payload
+}
+
 func buildProjectHierarchyFolderTree(rows []projectHierarchyFolderRow, rootParentPath string) []ProjectHierarchyFolderRecord {
 	if len(rows) == 0 {
 		return nil
@@ -1559,12 +2206,17 @@ func buildProjectHierarchyFolderTree(rows []projectHierarchyFolderRow, rootParen
 	childrenByParent := make(map[string][]string)
 
 	for _, row := range rows {
+		folderID := strings.TrimSpace(row.ID)
+		if folderID == "" {
+			folderID = row.Path
+		}
 		label := strings.TrimSpace(row.Label)
 		if label == "" {
 			label = fallbackFolderLabel(row.Path)
 		}
 		nodesByPath[row.Path] = &ProjectHierarchyFolderRecord{
-			ID:       row.Path,
+			ID:       folderID,
+			Path:     row.Path,
 			Label:    label,
 			Children: []ProjectHierarchyFolderRecord{},
 		}
@@ -1587,6 +2239,7 @@ func buildProjectHierarchyFolderTree(rows []projectHierarchyFolderRow, rootParen
 
 			folder := ProjectHierarchyFolderRecord{
 				ID:       node.ID,
+				Path:     node.Path,
 				Label:    node.Label,
 				Children: build(filepath.ToSlash(filepath.Join(childPath, "children"))),
 			}
@@ -1613,6 +2266,20 @@ func findProjectHierarchyFolder(folders []ProjectHierarchyFolderRecord, folderID
 	return ProjectHierarchyFolderRecord{}, false
 }
 
+func findProjectHierarchyFolderByPath(folders []ProjectHierarchyFolderRecord, folderPath string) (ProjectHierarchyFolderRecord, bool) {
+	for _, folder := range folders {
+		if folder.Path == folderPath {
+			return folder, true
+		}
+
+		if child, ok := findProjectHierarchyFolderByPath(folder.Children, folderPath); ok {
+			return child, true
+		}
+	}
+
+	return ProjectHierarchyFolderRecord{}, false
+}
+
 func projectHierarchyRootPath(projectSlug string) string {
 	return filepath.ToSlash(filepath.Join("projects", slugDir("project", projectSlug), "children"))
 }

Backend/internal/bootstrap/service_test.go

@@ -2,8 +2,10 @@ package bootstrap
 
 import (
 	"encoding/json"
+	"errors"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 )
 
@@ -58,6 +60,10 @@ func TestEnsureBootstrapPOSIXSkeletonInitializesEmptyRoot(t *testing.T) {
 		filepath.Join(rootPath, "users", "settings.json"),
 		filepath.Join(rootPath, "users", "data.json"),
 		filepath.Join(rootPath, "users", "personals"),
+		filepath.Join(rootPath, "users", "personals", "personal-ronald", "settings.json"),
+		filepath.Join(rootPath, "users", "personals", "personal-ronald", "layout.json"),
+		filepath.Join(rootPath, "users", "personals", "personal-ronald", "home.json"),
+		filepath.Join(rootPath, "users", "personals", "personal-ronald", "tree"),
 	}
 
 	for _, path := range requiredPaths {
@@ -101,6 +107,25 @@ func TestEnsureBootstrapPOSIXSkeletonInitializesEmptyRoot(t *testing.T) {
 	if usersSettings["primaryAdminId"] != "admin-1" {
 		t.Fatalf("expected primary admin id admin-1, got %#v", usersSettings["primaryAdminId"])
 	}
+
+	personalSettings := readJSONFileForTest[map[string]any](t, filepath.Join(rootPath, "users", "personals", "personal-ronald", "settings.json"))
+	if personalSettings["type"] != "personal" {
+		t.Fatalf("expected personal settings type personal, got %#v", personalSettings["type"])
+	}
+	if personalSettings["name"] != "Ronald" {
+		t.Fatalf("expected personal name Ronald, got %#v", personalSettings["name"])
+	}
+	if personalSettings["slug"] != "ronald" {
+		t.Fatalf("expected personal slug ronald, got %#v", personalSettings["slug"])
+	}
+
+	personalHome := readJSONFileForTest[map[string]any](t, filepath.Join(rootPath, "users", "personals", "personal-ronald", "home.json"))
+	if personalHome["type"] != "personal-home" {
+		t.Fatalf("expected personal home type personal-home, got %#v", personalHome["type"])
+	}
+	if personalHome["title"] != "Ronald's Home" {
+		t.Fatalf("expected personal home title Ronald's Home, got %#v", personalHome["title"])
+	}
 }
 
 func TestCreateProjectHierarchyFolderOnDiskCreatesExpectedFolderShape(t *testing.T) {
@@ -142,6 +167,9 @@ func TestCreateProjectHierarchyFolderOnDiskCreatesExpectedFolderShape(t *testing
 	}
 
 	folderPayload := readJSONFileForTest[map[string]any](t, filepath.Join(createdFolderPath, "folder.json"))
+	if strings.TrimSpace(asStringForTest(folderPayload["id"])) == "" {
+		t.Fatalf("expected created folder to have stable id, got %#v", folderPayload["id"])
+	}
 	if folderPayload["name"] != "Design System" {
 		t.Fatalf("expected folder name Design System, got %#v", folderPayload["name"])
 	}
@@ -258,6 +286,9 @@ func TestRenameProjectHierarchyFolderOnDiskRenamesFolderShape(t *testing.T) {
 	}
 
 	folderPayload := readJSONFileForTest[map[string]any](t, filepath.Join(renamedFolderPath, "folder.json"))
+	if strings.TrimSpace(asStringForTest(folderPayload["id"])) == "" {
+		t.Fatalf("expected renamed folder to preserve stable id, got %#v", folderPayload["id"])
+	}
 	if folderPayload["name"] != "Platform Design" {
 		t.Fatalf("expected renamed folder name Platform Design, got %#v", folderPayload["name"])
 	}
@@ -310,11 +341,155 @@ func TestRenameProjectTreeFolderOnDiskRenamesFolderShape(t *testing.T) {
 	}
 }
 
+func TestMoveProjectHierarchyFolderOnDiskMovesFolderToNewParent(t *testing.T) {
+	rootPath := filepath.Join(t.TempDir(), "POSIX")
+	service := NewService(nil, rootPath)
+
+	err := service.ensureBootstrapPOSIXSkeleton(
+		InstallationRecord{ID: "installation-1", Name: "MangoPig", Mode: "personal", Access: "local", Protocol: "http", Host: "localhost", IsBootstrapped: true},
+		AdminSummary{ID: "admin-1", Email: "ronald@example.com", DisplayName: "Ronald"},
+		namedRecord{ID: "org-1", Name: "Primary Organization", Slug: "primary-organization"},
+		namedRecord{ID: "dept-1", Name: "Primary Department", Slug: "primary-department"},
+		namedRecord{ID: "team-1", Name: "Primary Team", Slug: "primary-team"},
+		namedRecord{ID: "project-1", Name: "Primary Project", Slug: "primary-project"},
+	)
+	if err != nil {
+		t.Fatalf("ensure bootstrap POSIX skeleton: %v", err)
+	}
+
+	designPath, _, err := service.createProjectHierarchyFolderOnDisk("primary-project", "", "Design")
+	if err != nil {
+		t.Fatalf("create design folder: %v", err)
+	}
+	operationsPath, _, err := service.createProjectHierarchyFolderOnDisk("primary-project", "", "Operations")
+	if err != nil {
+		t.Fatalf("create operations folder: %v", err)
+	}
+	researchPath, _, err := service.createProjectHierarchyFolderOnDisk("primary-project", designPath, "Research")
+	if err != nil {
+		t.Fatalf("create research folder: %v", err)
+	}
+	nestedPath, _, err := service.createProjectHierarchyFolderOnDisk("primary-project", researchPath, "Interview Notes")
+	if err != nil {
+		t.Fatalf("create nested folder: %v", err)
+	}
+
+	previousPath, movedPath, err := service.moveProjectHierarchyFolderOnDisk("primary-project", researchPath, operationsPath)
+	if err != nil {
+		t.Fatalf("moveProjectHierarchyFolderOnDisk: %v", err)
+	}
+	if previousPath != researchPath {
+		t.Fatalf("expected previous path %s, got %s", researchPath, previousPath)
+	}
+	if movedPath != "projects/project-primary-project/children/folder-operations/children/folder-research" {
+		t.Fatalf("unexpected moved path: %s", movedPath)
+	}
+
+	if _, err := os.Stat(filepath.Join(rootPath, filepath.FromSlash(researchPath))); !os.IsNotExist(err) {
+		t.Fatalf("expected previous folder path to be gone, got err=%v", err)
+	}
+
+	movedFolderPath := filepath.Join(rootPath, filepath.FromSlash(movedPath))
+	if _, err := os.Stat(filepath.Join(movedFolderPath, "children", filepath.Base(nestedPath))); err != nil {
+		t.Fatalf("expected nested child folder to move with moved parent: %v", err)
+	}
+
+	folderPayload := readJSONFileForTest[map[string]any](t, filepath.Join(movedFolderPath, "folder.json"))
+	if strings.TrimSpace(asStringForTest(folderPayload["id"])) == "" {
+		t.Fatalf("expected moved folder to preserve stable id, got %#v", folderPayload["id"])
+	}
+	if folderPayload["name"] != "Research" {
+		t.Fatalf("expected moved folder name Research, got %#v", folderPayload["name"])
+	}
+	if folderPayload["slug"] != "research" {
+		t.Fatalf("expected moved folder slug research, got %#v", folderPayload["slug"])
+	}
+	if folderPayload["type"] != "folder" {
+		t.Fatalf("expected moved folder type folder, got %#v", folderPayload["type"])
+	}
+}
+
+func TestMoveProjectTreeFolderOnDiskMovesFolderToNewParent(t *testing.T) {
+	rootPath := filepath.Join(t.TempDir(), "POSIX")
+	service := NewService(nil, rootPath)
+
+	err := service.ensureBootstrapPOSIXSkeleton(
+		InstallationRecord{ID: "installation-1", Name: "MangoPig", Mode: "personal", Access: "local", Protocol: "http", Host: "localhost", IsBootstrapped: true},
+		AdminSummary{ID: "admin-1", Email: "ronald@example.com", DisplayName: "Ronald"},
+		namedRecord{ID: "org-1", Name: "Primary Organization", Slug: "primary-organization"},
+		namedRecord{ID: "dept-1", Name: "Primary Department", Slug: "primary-department"},
+		namedRecord{ID: "team-1", Name: "Primary Team", Slug: "primary-team"},
+		namedRecord{ID: "project-1", Name: "Primary Project", Slug: "primary-project"},
+	)
+	if err != nil {
+		t.Fatalf("ensure bootstrap POSIX skeleton: %v", err)
+	}
+
+	docsPath, _, err := service.createProjectTreeFolderOnDisk("primary-project", "", "Docs")
+	if err != nil {
+		t.Fatalf("create docs folder: %v", err)
+	}
+	archivePath, _, err := service.createProjectTreeFolderOnDisk("primary-project", "", "Archive")
+	if err != nil {
+		t.Fatalf("create archive folder: %v", err)
+	}
+
+	previousPath, movedPath, err := service.moveProjectTreeFolderOnDisk("primary-project", docsPath, archivePath)
+	if err != nil {
+		t.Fatalf("moveProjectTreeFolderOnDisk: %v", err)
+	}
+	if previousPath != docsPath {
+		t.Fatalf("expected previous path %s, got %s", docsPath, previousPath)
+	}
+	if movedPath != "projects/project-primary-project/tree/folder-archive/children/folder-docs" {
+		t.Fatalf("unexpected moved path: %s", movedPath)
+	}
+
+	folderPayload := readJSONFileForTest[map[string]any](t, filepath.Join(rootPath, filepath.FromSlash(movedPath), "folder.json"))
+	if folderPayload["name"] != "Docs" {
+		t.Fatalf("expected moved folder name Docs, got %#v", folderPayload["name"])
+	}
+	if folderPayload["slug"] != "docs" {
+		t.Fatalf("expected moved folder slug docs, got %#v", folderPayload["slug"])
+	}
+}
+
+func TestMoveProjectHierarchyFolderOnDiskRejectsDescendantTarget(t *testing.T) {
+	rootPath := filepath.Join(t.TempDir(), "POSIX")
+	service := NewService(nil, rootPath)
+
+	err := service.ensureBootstrapPOSIXSkeleton(
+		InstallationRecord{ID: "installation-1", Name: "MangoPig", Mode: "personal", Access: "local", Protocol: "http", Host: "localhost", IsBootstrapped: true},
+		AdminSummary{ID: "admin-1", Email: "ronald@example.com", DisplayName: "Ronald"},
+		namedRecord{ID: "org-1", Name: "Primary Organization", Slug: "primary-organization"},
+		namedRecord{ID: "dept-1", Name: "Primary Department", Slug: "primary-department"},
+		namedRecord{ID: "team-1", Name: "Primary Team", Slug: "primary-team"},
+		namedRecord{ID: "project-1", Name: "Primary Project", Slug: "primary-project"},
+	)
+	if err != nil {
+		t.Fatalf("ensure bootstrap POSIX skeleton: %v", err)
+	}
+
+	parentPath, _, err := service.createProjectHierarchyFolderOnDisk("primary-project", "", "Parent")
+	if err != nil {
+		t.Fatalf("create parent folder: %v", err)
+	}
+	childPath, _, err := service.createProjectHierarchyFolderOnDisk("primary-project", parentPath, "Child")
+	if err != nil {
+		t.Fatalf("create child folder: %v", err)
+	}
+
+	_, _, err = service.moveProjectHierarchyFolderOnDisk("primary-project", parentPath, childPath)
+	if !errors.Is(err, ErrInvalidProjectFolderMove) {
+		t.Fatalf("expected ErrInvalidProjectFolderMove, got %v", err)
+	}
+}
+
 func TestBuildProjectHierarchyFolderTreeBuildsNestedStructure(t *testing.T) {
 	rows := []projectHierarchyFolderRow{
-		{Path: "projects/project-primary-project/children/folder-design", ParentPath: projectHierarchyRootPath("primary-project"), Label: "Design"},
+		{ID: "folder-design-id", Path: "projects/project-primary-project/children/folder-design", ParentPath: projectHierarchyRootPath("primary-project"), Label: "Design"},
-		{Path: "projects/project-primary-project/children/folder-design/children/folder-research", ParentPath: "projects/project-primary-project/children/folder-design/children", Label: "Research"},
+		{ID: "folder-research-id", Path: "projects/project-primary-project/children/folder-design/children/folder-research", ParentPath: "projects/project-primary-project/children/folder-design/children", Label: "Research"},
-		{Path: "projects/project-primary-project/children/folder-ops", ParentPath: projectHierarchyRootPath("primary-project"), Label: "Ops"},
+		{ID: "folder-ops-id", Path: "projects/project-primary-project/children/folder-ops", ParentPath: projectHierarchyRootPath("primary-project"), Label: "Ops"},
 	}
 
 	folders := buildProjectHierarchyFolderTree(rows, projectHierarchyRootPath("primary-project"))
@@ -327,6 +502,64 @@ func TestBuildProjectHierarchyFolderTreeBuildsNestedStructure(t *testing.T) {
 	if len(folders[0].Children) != 1 || folders[0].Children[0].Label != "Research" {
 		t.Fatalf("unexpected nested folder structure: %#v", folders[0].Children)
 	}
+	if folders[0].ID != "folder-design-id" || folders[0].Path != "projects/project-primary-project/children/folder-design" {
+		t.Fatalf("expected design folder to retain stable id/path, got %#v", folders[0])
+	}
+	if folders[0].Children[0].ID != "folder-research-id" || folders[1].ID != "folder-ops-id" {
+		t.Fatalf("expected nested/top-level folder ids to be preserved, got %#v / %#v", folders[0].Children[0], folders[1])
+	}
+}
+
+func TestApplyProjectHierarchyFolderOrderingOrdersRootAndChildrenByStableID(t *testing.T) {
+	folders := []ProjectHierarchyFolderRecord{
+		{
+			ID:    "folder-design-id",
+			Path:  "projects/project-primary-project/children/folder-design",
+			Label: "Design",
+			Children: []ProjectHierarchyFolderRecord{
+				{ID: "folder-research-id", Path: "projects/project-primary-project/children/folder-design/children/folder-research", Label: "Research"},
+				{ID: "folder-assets-id", Path: "projects/project-primary-project/children/folder-design/children/folder-assets", Label: "Assets"},
+			},
+		},
+		{ID: "folder-ops-id", Path: "projects/project-primary-project/children/folder-ops", Label: "Ops"},
+		{ID: "folder-qa-id", Path: "projects/project-primary-project/children/folder-qa", Label: "QA"},
+	}
+
+	ordered := applyProjectHierarchyFolderOrdering(folders, map[string][]string{
+		projectFolderOrderRootKey: {"folder-qa-id", "folder-design-id"},
+		"folder-design-id":        {"folder-assets-id", "folder-research-id"},
+	})
+
+	if len(ordered) != 3 {
+		t.Fatalf("expected 3 ordered root folders, got %d", len(ordered))
+	}
+	if ordered[0].ID != "folder-qa-id" || ordered[1].ID != "folder-design-id" || ordered[2].ID != "folder-ops-id" {
+		t.Fatalf("unexpected ordered root ids: %#v", ordered)
+	}
+	if len(ordered[1].Children) != 2 {
+		t.Fatalf("expected design folder children to be preserved, got %#v", ordered[1].Children)
+	}
+	if ordered[1].Children[0].ID != "folder-assets-id" || ordered[1].Children[1].ID != "folder-research-id" {
+		t.Fatalf("unexpected ordered child ids: %#v", ordered[1].Children)
+	}
+}
+
+func TestInsertFolderOrderReordersWithinSameParent(t *testing.T) {
+	folderOrder := map[string][]string{
+		projectFolderOrderRootKey: {"folder-a", "folder-b", "folder-c"},
+	}
+
+	insertFolderOrder(folderOrder, "", "folder-c", 0)
+
+	got := folderOrder[projectFolderOrderRootKey]
+	if len(got) != 3 || got[0] != "folder-c" || got[1] != "folder-a" || got[2] != "folder-b" {
+		t.Fatalf("unexpected reordered root children: %#v", got)
+	}
+}
+
+func asStringForTest(value any) string {
+	text, _ := value.(string)
+	return text
 }
 
 func readJSONFileForTest[T any](t *testing.T, path string) T {

Backend/internal/httpx/api_project_routes.go

@@ -26,6 +26,14 @@ type deleteProjectFolderRequest struct {
 	FolderID string `json:"folderId"`
 }
 
+type moveProjectFolderRequest struct {
+	FolderID       string `json:"folderId"`
+	FolderNodeID   string `json:"folderNodeId"`
+	ParentFolderID string `json:"parentFolderId"`
+	ParentNodeID   string `json:"parentNodeId"`
+	TargetIndex    int    `json:"targetIndex"`
+}
+
 func (routes apiRoutes) handleProjectFolders(w http.ResponseWriter, r *http.Request) {
 	projectID := strings.TrimSpace(chi.URLParam(r, "projectId"))
 	if projectID == "" {
@@ -161,6 +169,49 @@ func (routes apiRoutes) handleRenameProjectFolder(w http.ResponseWriter, r *http
 	})
 }
 
+func (routes apiRoutes) handleMoveProjectFolder(w http.ResponseWriter, r *http.Request) {
+	projectID := strings.TrimSpace(chi.URLParam(r, "projectId"))
+	if projectID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Project ID is required.")
+		return
+	}
+
+	payload, ok := decodeMoveProjectFolderRequest(w, r)
+	if !ok {
+		return
+	}
+
+	payload.FolderID = strings.TrimSpace(payload.FolderID)
+	payload.FolderNodeID = strings.TrimSpace(payload.FolderNodeID)
+	payload.ParentFolderID = strings.TrimSpace(payload.ParentFolderID)
+	payload.ParentNodeID = strings.TrimSpace(payload.ParentNodeID)
+	if payload.FolderID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder ID is required.")
+		return
+	}
+
+	result, err := routes.bootstrapService().MoveProjectFolder(r.Context(), bootstrapservice.MoveProjectFolderInput{
+		ProjectID:      projectID,
+		FolderID:       payload.FolderID,
+		FolderNodeID:   payload.FolderNodeID,
+		ParentFolderID: payload.ParentFolderID,
+		ParentNodeID:   payload.ParentNodeID,
+		TargetIndex:    payload.TargetIndex,
+	})
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err, "move")
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": result,
+		"meta": map[string]any{
+			"resource":  "project-folder-move",
+			"persisted": true,
+		},
+	})
+}
+
 func (routes apiRoutes) handleProjectTreeFolders(w http.ResponseWriter, r *http.Request) {
 	projectID := strings.TrimSpace(chi.URLParam(r, "projectId"))
 	if projectID == "" {
@@ -296,10 +347,55 @@ func (routes apiRoutes) handleRenameProjectTreeFolder(w http.ResponseWriter, r *
 	})
 }
 
+func (routes apiRoutes) handleMoveProjectTreeFolder(w http.ResponseWriter, r *http.Request) {
+	projectID := strings.TrimSpace(chi.URLParam(r, "projectId"))
+	if projectID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Project ID is required.")
+		return
+	}
+
+	payload, ok := decodeMoveProjectFolderRequest(w, r)
+	if !ok {
+		return
+	}
+
+	payload.FolderID = strings.TrimSpace(payload.FolderID)
+	payload.FolderNodeID = strings.TrimSpace(payload.FolderNodeID)
+	payload.ParentFolderID = strings.TrimSpace(payload.ParentFolderID)
+	payload.ParentNodeID = strings.TrimSpace(payload.ParentNodeID)
+	if payload.FolderID == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder ID is required.")
+		return
+	}
+
+	result, err := routes.bootstrapService().MoveProjectTreeFolder(r.Context(), bootstrapservice.MoveProjectFolderInput{
+		ProjectID:      projectID,
+		FolderID:       payload.FolderID,
+		FolderNodeID:   payload.FolderNodeID,
+		ParentFolderID: payload.ParentFolderID,
+		ParentNodeID:   payload.ParentNodeID,
+		TargetIndex:    payload.TargetIndex,
+	})
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err, "move")
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": result,
+		"meta": map[string]any{
+			"resource":  "project-tree-folder-move",
+			"persisted": true,
+		},
+	})
+}
+
 func (routes apiRoutes) writeProjectFolderError(w http.ResponseWriter, r *http.Request, err error, operation string) {
 	switch {
 	case errors.Is(err, bootstrapservice.ErrProjectNotFound), errors.Is(err, bootstrapservice.ErrProjectFolderNotFound):
 		WriteError(w, http.StatusNotFound, RequestIDFromContext(r.Context()), "not_found", err.Error())
+	case errors.Is(err, bootstrapservice.ErrInvalidProjectFolderMove):
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", err.Error())
 	default:
 		routes.cfg.Logger.Error(operation+" project folder", "error", err, "path", r.URL.Path)
 		message := "Failed to " + operation + " project folder."
@@ -310,6 +406,30 @@ func (routes apiRoutes) writeProjectFolderError(w http.ResponseWriter, r *http.R
 	}
 }
 
+func decodeMoveProjectFolderRequest(w http.ResponseWriter, r *http.Request) (moveProjectFolderRequest, bool) {
+	var payload moveProjectFolderRequest
+
+	decoder := json.NewDecoder(r.Body)
+	decoder.DisallowUnknownFields()
+
+	if err := decoder.Decode(&payload); err != nil {
+		if errors.Is(err, io.EOF) {
+			WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_json", "The request body is required and must be valid JSON.")
+			return payload, false
+		}
+
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_json", "The request body must be valid JSON.")
+		return payload, false
+	}
+
+	if err := decoder.Decode(&struct{}{}); !errors.Is(err, io.EOF) {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_json", "The request body must contain a single JSON object.")
+		return payload, false
+	}
+
+	return payload, true
+}
+
 func decodeDeleteProjectFolderRequest(r *http.Request) deleteProjectFolderRequest {
 	return deleteProjectFolderRequest{
 		FolderID: strings.TrimSpace(r.URL.Query().Get("folderId")),

Backend/internal/httpx/api_routes.go

@@ -37,10 +37,12 @@ func (routes apiRoutes) Register(router chi.Router) {
 			projectRouter.Get("/folders", routes.handleProjectFolders)
 			projectRouter.Post("/folders", routes.handleCreateProjectFolder)
 			projectRouter.Patch("/folders", routes.handleRenameProjectFolder)
+			projectRouter.Patch("/folders/move", routes.handleMoveProjectFolder)
 			projectRouter.Delete("/folders", routes.handleDeleteProjectFolder)
 			projectRouter.Get("/tree/folders", routes.handleProjectTreeFolders)
 			projectRouter.Post("/tree/folders", routes.handleCreateProjectTreeFolder)
 			projectRouter.Patch("/tree/folders", routes.handleRenameProjectTreeFolder)
+			projectRouter.Patch("/tree/folders/move", routes.handleMoveProjectTreeFolder)
 			projectRouter.Delete("/tree/folders", routes.handleDeleteProjectTreeFolder)
 		})
 

Frontend/src/components/shell/ProjectSelector/ProjectSelector.tsx

@@ -36,6 +36,7 @@ type ProjectSelectorProps = {
 type ProjectFolderNode = {
 	kind: "folder";
 	id: string;
+	path: string;
 	label: string;
 	meta?: string;
 	children: ProjectTreeNode[];
@@ -50,6 +51,7 @@ type ProjectTreeNode = ProjectFolderNode | ProjectLeafNode;
 
 type PersistedProjectFolderRecord = {
 	id: string;
+	path: string;
 	label: string;
 	children: PersistedProjectFolderRecord[];
 };
@@ -58,7 +60,9 @@ type ProjectFoldersResponse = {
 	data?: {
 		folders?: PersistedProjectFolderRecord[];
 		renamedFolder?: PersistedProjectFolderRecord;
+		movedFolder?: PersistedProjectFolderRecord;
 		previousFolderId?: string;
+		previousFolderPath?: string;
 	};
 	error?: string;
 	message?: string;
@@ -90,6 +94,7 @@ const buildPersistedFolderNodes = (folders: readonly PersistedProjectFolderRecor
 	folders.map((folder) => ({
 		kind: "folder",
 		id: folder.id,
+		path: folder.path,
 		label: folder.label,
 		children: buildPersistedFolderNodes(folder.children ?? []),
 	}));
@@ -574,9 +579,48 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 			}
 
 			suppressTreeClickTemporarily();
-			setProjectTreeNodes((current) =>
+
-				moveTreeNode(current, nextDragState.draggedNodeId, nextDragState.dropTarget as ProjectDragTarget, projectTreeAdapter),
+			const currentNodes = projectTreeNodes();
-			);
+			const draggedLocation = findTreeNodeLocation(currentNodes, nextDragState.draggedNodeId, projectTreeAdapter);
+			const canPersistMove = isUuidString(selectedProject().id);
+			const draggedFolderPath = draggedLocation?.node.kind === "folder" ? draggedLocation.node.path : null;
+			const previewNodes = moveTreeNode(currentNodes, nextDragState.draggedNodeId, nextDragState.dropTarget as ProjectDragTarget, projectTreeAdapter);
+			const previewLocation = findTreeNodeLocation(previewNodes, nextDragState.draggedNodeId, projectTreeAdapter);
+			const persistedParentLocation = previewLocation?.parentId
+				? findTreeNodeLocation(previewNodes, previewLocation.parentId, projectTreeAdapter)
+				: null;
+			const persistedParentFolderPath =
+				persistedParentLocation?.node.kind === "folder" ? persistedParentLocation.node.path : null;
+			const previewSiblings = previewLocation?.parentId
+				? persistedParentLocation?.node.kind === "folder"
+					? persistedParentLocation.node.children
+					: []
+				: previewNodes;
+			const targetIndex = previewLocation
+				? previewSiblings
+					.slice(0, previewLocation.index)
+					.filter((node) => node.kind === "folder").length
+				: 0;
+
+			if (
+				canPersistMove &&
+				draggedLocation?.node.kind === "folder" &&
+				draggedFolderPath &&
+				(!previewLocation?.parentId || persistedParentLocation?.node.kind === "folder")
+			) {
+				void movePersistedFolder(
+					draggedFolderPath,
+					persistedParentFolderPath,
+					draggedLocation.node.id,
+					persistedParentLocation?.node.kind === "folder" ? persistedParentLocation.node.id : null,
+					targetIndex,
+				);
+			} else {
+				setProjectTreeNodes((current) =>
+					moveTreeNode(current, nextDragState.draggedNodeId, nextDragState.dropTarget as ProjectDragTarget, projectTreeAdapter),
+				);
+			}
+
 			setDragState(null);
 		};
 
@@ -655,6 +699,11 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 		setPendingFolderRenameName(label);
 	};
 
+	const resolveFolderPath = (folderId: string): string | null => {
+		const location = findTreeNodeLocation(projectTreeNodes(), folderId, projectTreeAdapter);
+		return location && location.node.kind === "folder" ? location.node.path : null;
+	};
+
 	const submitPendingFolder = async (): Promise<void> => {
 		const name = pendingFolderName().trim();
 		const draft = pendingFolderDraft();
@@ -675,6 +724,12 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 			return;
 		}
 
+		const parentFolderPath = draft.parentId ? resolveFolderPath(draft.parentId) : null;
+		if (draft.parentId && !parentFolderPath) {
+			cancelPendingFolder();
+			return;
+		}
+
 		try {
 			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/folders`, {
 				method: "POST",
@@ -684,7 +739,7 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 				},
 				body: JSON.stringify({
 					name,
-					parentFolderId: draft.parentId,
+					parentFolderId: parentFolderPath,
 				}),
 			});
 
@@ -708,9 +763,14 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 			return;
 		}
 
+		const folderPath = resolveFolderPath(folderId);
+		if (!folderPath) {
+			return;
+		}
+
 		try {
 			const response = await fetch(
-				`${resolveAPIBase()}/projects/${projectId}/folders?folderId=${encodeURIComponent(folderId)}`,
+				`${resolveAPIBase()}/projects/${projectId}/folders?folderId=${encodeURIComponent(folderPath)}`,
 				{
 					method: "DELETE",
 					headers: {
@@ -732,6 +792,46 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 		}
 	};
 
+	const movePersistedFolder = async (
+		folderPath: string,
+		parentFolderPath: string | null,
+		folderNodeId: string,
+		parentNodeId: string | null,
+		targetIndex: number,
+	): Promise<void> => {
+		const projectId = selectedProject().id;
+		if (!folderPath || !folderNodeId || !isUuidString(projectId)) {
+			return;
+		}
+
+		try {
+			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/folders/move`, {
+				method: "PATCH",
+				headers: {
+					Accept: "application/json",
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({
+					folderId: folderPath,
+					folderNodeId,
+					parentFolderId: parentFolderPath,
+					parentNodeId,
+					targetIndex,
+				}),
+			});
+
+			const body = (await response.json()) as ProjectFoldersResponse;
+
+			if (!response.ok) {
+				throw new Error(body.message || "Failed to move project folder.");
+			}
+
+			setPersistedFolders(readPersistedFolders(body));
+		} catch (error) {
+			console.error(error);
+		}
+	};
+
 	const submitPendingFolderRename = async (): Promise<void> => {
 		const draft = pendingFolderRename();
 		const name = pendingFolderRenameName().trim();
@@ -752,6 +852,12 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 			return;
 		}
 
+		const folderPath = resolveFolderPath(draft.folderId);
+		if (!folderPath) {
+			cancelPendingFolderRename();
+			return;
+		}
+
 		try {
 			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/folders`, {
 				method: "PATCH",
@@ -760,7 +866,7 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 					"Content-Type": "application/json",
 				},
 				body: JSON.stringify({
-					folderId: draft.folderId,
+					folderId: folderPath,
 					name,
 				}),
 			});
@@ -774,14 +880,6 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 			setPersistedFolders(readPersistedFolders(body));
 			setPendingFolderRename(null);
 			setPendingFolderRenameName("");
-
-			const previousFolderId = body.data?.previousFolderId;
-			const renamedFolderId = body.data?.renamedFolder?.id;
-			if (previousFolderId && renamedFolderId && previousFolderId !== renamedFolderId) {
-				setCollapsedFolderIds((current) =>
-					current.map((id) => (id === previousFolderId ? renamedFolderId : id)),
-				);
-			}
 		} catch (error) {
 			console.error(error);
 		}

Frontend/src/components/shell/WorkspaceSidebar/WorkspaceSidebar.tsx

@@ -8,6 +8,7 @@ import { ProjectSelector } from "../ProjectSelector/ProjectSelector";
 import {
 	collectBranchNodeIds,
 	findTreeNodeDepth,
+	findTreeNodeLocation,
 	getPointerRelativeY,
 	isUuidString,
 	moveTreeNode,
@@ -51,6 +52,7 @@ type WorkspaceDragState = {
 
 type PersistedWorkspaceFolderRecord = {
 	id: string;
+	path: string;
 	label: string;
 	children?: PersistedWorkspaceFolderRecord[];
 };
@@ -59,7 +61,9 @@ type WorkspaceFoldersResponse = {
 	data?: {
 		folders?: PersistedWorkspaceFolderRecord[];
 		renamedFolder?: PersistedWorkspaceFolderRecord;
+		movedFolder?: PersistedWorkspaceFolderRecord;
 		previousFolderId?: string;
+		previousFolderPath?: string;
 	};
 	error?: string;
 	message?: string;
@@ -79,6 +83,7 @@ const buildPersistedWorkspaceFolderNodes = (
 ): WorkspaceTreeNode[] =>
 	folders.map((folder) => ({
 		id: folder.id,
+		path: folder.path,
 		label: folder.label,
 		kind: "folder",
 		icon: Folder,
@@ -527,9 +532,47 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 			}
 
 			suppressTreeClickTemporarily();
-			setWorkspaceTreeNodes((current) =>
+
-				moveTreeNode(current, nextDragState.draggedNodeId, nextDragState.dropTarget as WorkspaceDragTarget, workspaceTreeAdapter),
+			const currentNodes = workspaceTreeNodes();
-			);
+			const draggedLocation = findTreeNodeLocation(currentNodes, nextDragState.draggedNodeId, workspaceTreeAdapter);
+			const canPersistMove = isUuidString(activeProject()?.id ?? "");
+			const draggedFolderPath = draggedLocation?.node.kind === "folder" ? draggedLocation.node.path ?? null : null;
+			const previewNodes = moveTreeNode(currentNodes, nextDragState.draggedNodeId, nextDragState.dropTarget as WorkspaceDragTarget, workspaceTreeAdapter);
+			const previewLocation = findTreeNodeLocation(previewNodes, nextDragState.draggedNodeId, workspaceTreeAdapter);
+			const persistedParentLocation = previewLocation?.parentId
+				? findTreeNodeLocation(previewNodes, previewLocation.parentId, workspaceTreeAdapter)
+				: null;
+			const persistedParentFolderPath = persistedParentLocation?.node.kind === "folder" ? persistedParentLocation.node.path ?? null : null;
+			const previewSiblings = previewLocation?.parentId
+				? persistedParentLocation?.node.kind === "folder"
+					? persistedParentLocation.node.children ?? []
+					: []
+				: previewNodes;
+			const targetIndex = previewLocation
+				? previewSiblings
+					.slice(0, previewLocation.index)
+					.filter((node) => node.kind === "folder").length
+				: 0;
+
+			if (
+				canPersistMove &&
+				draggedLocation?.node.kind === "folder" &&
+				draggedFolderPath &&
+				(!previewLocation?.parentId || persistedParentLocation?.node.kind === "folder")
+			) {
+				void movePersistedFolder(
+					draggedFolderPath,
+					persistedParentFolderPath,
+					draggedLocation.node.id,
+					persistedParentLocation?.node.kind === "folder" ? persistedParentLocation.node.id : null,
+					targetIndex,
+				);
+			} else {
+				setWorkspaceTreeNodes((current) =>
+					moveTreeNode(current, nextDragState.draggedNodeId, nextDragState.dropTarget as WorkspaceDragTarget, workspaceTreeAdapter),
+				);
+			}
+
 			setDragState(null);
 		};
 
@@ -578,6 +621,11 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 		setPendingFolderRenameName(label);
 	};
 
+	const resolveFolderPath = (folderId: string): string | null => {
+		const location = findTreeNodeLocation(workspaceTreeNodes(), folderId, workspaceTreeAdapter);
+		return location?.node.kind === "folder" ? location.node.path ?? null : null;
+	};
+
 	const submitPendingFolder = async (): Promise<void> => {
 		const name = pendingFolderName().trim();
 		const draft = pendingFolderDraft();
@@ -598,6 +646,12 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 			return;
 		}
 
+		const parentFolderPath = draft.parentId ? resolveFolderPath(draft.parentId) : null;
+		if (draft.parentId && !parentFolderPath) {
+			cancelPendingFolder();
+			return;
+		}
+
 		try {
 			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/tree/folders`, {
 				method: "POST",
@@ -607,7 +661,7 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 				},
 				body: JSON.stringify({
 					name,
-					parentFolderId: draft.parentId,
+					parentFolderId: parentFolderPath,
 				}),
 			});
 
@@ -627,13 +681,17 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 
 	const deletePersistedFolder = async (folderId: string): Promise<void> => {
 		const projectId = activeProject()?.id ?? "";
+		const folderPath = resolveFolderPath(folderId);
 		if (!folderId || !projectId || !isUuidString(projectId)) {
 			return;
 		}
+		if (!folderPath) {
+			return;
+		}
 
 		try {
 			const response = await fetch(
-				`${resolveAPIBase()}/projects/${projectId}/tree/folders?folderId=${encodeURIComponent(folderId)}`,
+				`${resolveAPIBase()}/projects/${projectId}/tree/folders?folderId=${encodeURIComponent(folderPath)}`,
 				{
 					method: "DELETE",
 					headers: {
@@ -655,6 +713,46 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 		}
 	};
 
+	const movePersistedFolder = async (
+		folderPath: string,
+		parentFolderPath: string | null,
+		folderNodeId: string,
+		parentNodeId: string | null,
+		targetIndex: number,
+	): Promise<void> => {
+		const projectId = activeProject()?.id ?? "";
+		if (!folderPath || !folderNodeId || !projectId || !isUuidString(projectId)) {
+			return;
+		}
+
+		try {
+			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/tree/folders/move`, {
+				method: "PATCH",
+				headers: {
+					Accept: "application/json",
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({
+					folderId: folderPath,
+					folderNodeId,
+					parentFolderId: parentFolderPath,
+					parentNodeId,
+					targetIndex,
+				}),
+			});
+
+			const body = (await response.json()) as WorkspaceFoldersResponse;
+
+			if (!response.ok) {
+				throw new Error(body.message || "Failed to move project tree folder.");
+			}
+
+			setPersistedFolders(readPersistedWorkspaceFolders(body));
+		} catch (error) {
+			console.error(error);
+		}
+	};
+
 	const submitPendingFolderRename = async (): Promise<void> => {
 		const draft = pendingFolderRename();
 		const name = pendingFolderRenameName().trim();
@@ -675,6 +773,12 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 			return;
 		}
 
+		const folderPath = resolveFolderPath(draft.folderId);
+		if (!folderPath) {
+			cancelPendingFolderRename();
+			return;
+		}
+
 		try {
 			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/tree/folders`, {
 				method: "PATCH",
@@ -683,7 +787,7 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 					"Content-Type": "application/json",
 				},
 				body: JSON.stringify({
-					folderId: draft.folderId,
+					folderId: folderPath,
 					name,
 				}),
 			});
@@ -697,14 +801,6 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 			setPersistedFolders(readPersistedWorkspaceFolders(body));
 			setPendingFolderRename(null);
 			setPendingFolderRenameName("");
-
-			const previousFolderId = body.data?.previousFolderId;
-			const renamedFolderId = body.data?.renamedFolder?.id;
-			if (previousFolderId && renamedFolderId && previousFolderId !== renamedFolderId) {
-				setCollapsedFolderIds((current) =>
-					current.map((id) => (id === previousFolderId ? renamedFolderId : id)),
-				);
-			}
 		} catch (error) {
 			console.error(error);
 		}

Frontend/src/components/shell/data/shell.data.ts

@@ -129,6 +129,7 @@ export type WorkspaceStaticItem = SidebarItem & {
 
 export type WorkspaceFolderNode = {
 	id: string;
+	path?: string;
 	label: string;
 	kind: "folder";
 	icon: ShellIcon;

Frontend/src/components/workspace-home/WorkspaceHome/WorkspaceHome.tsx

@@ -21,6 +21,29 @@ type BootstrapSubmissionState = {
 	error: string;
 };
 
+type InstanceForm = {
+	protocol: "http" | "https";
+	access: "local" | "remote";
+	host: string;
+};
+
+type ModeForm = {
+	mode: "personal" | "organizational";
+	name: string;
+};
+
+type AdminForm = {
+	displayName: string;
+	email: string;
+	password: string;
+};
+
+type StructureForm = {
+	departmentName: string;
+	teamName: string;
+	projectName: string;
+};
+
 const bootstrapStepDefinitions: readonly BootstrapStepDefinition[] = [
 	{
 		id: "instance",
@@ -44,37 +67,37 @@ const bootstrapStepDefinitions: readonly BootstrapStepDefinition[] = [
 	},
 ];
 
-const defaultInstanceForm = {
+const defaultInstanceForm: InstanceForm = {
 	protocol: "http",
 	access: "local",
 	host: "localhost",
-} as const;
+};
 
-const defaultModeForm = {
+const defaultModeForm: ModeForm = {
 	mode: "personal",
 	name: "",
-} as const;
+};
 
-const defaultAdminForm = {
+const defaultAdminForm: AdminForm = {
 	displayName: "Admin",
 	email: "admin@example.com",
 	password: "",
-} as const;
+};
 
 const personalStructureDefaults = {
 	departmentName: "Default",
 	teamName: "Personal",
-} as const;
+};
 
 const organizationalStructureDefaults = {
 	departmentName: "Department",
 	teamName: "Team",
-} as const;
+};
 
-const defaultStructureForm = {
+const defaultStructureForm: StructureForm = {
 	...personalStructureDefaults,
 	projectName: "Project",
-} as const;
+};
 
 const initialSubmissionState = (): BootstrapSubmissionState => ({
 	status: "idle",
@@ -148,10 +171,10 @@ type WorkspaceHomeProps = {
 
 export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 	const appShellData = useAppShellData();
-	const [instanceForm, setInstanceForm] = createStore({ ...defaultInstanceForm });
+	const [instanceForm, setInstanceForm] = createStore<InstanceForm>({ ...defaultInstanceForm });
-	const [modeForm, setModeForm] = createStore({ ...defaultModeForm });
+	const [modeForm, setModeForm] = createStore<ModeForm>({ ...defaultModeForm });
-	const [adminForm, setAdminForm] = createStore({ ...defaultAdminForm });
+	const [adminForm, setAdminForm] = createStore<AdminForm>({ ...defaultAdminForm });
-	const [structureForm, setStructureForm] = createStore({ ...defaultStructureForm });
+	const [structureForm, setStructureForm] = createStore<StructureForm>({ ...defaultStructureForm });
 	const [stepState, setStepState] = createStore<Record<BootstrapStepKey, BootstrapSubmissionState>>({
 		instance: initialSubmissionState(),
 		mode: initialSubmissionState(),
@@ -363,7 +386,13 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 					<h1 class={styles.title}>{isBootstrapComplete() ? appShellData.activeServer().name : bootstrapTargetLabel()}</h1>
 					<Show when={isBootstrapStateResolved() && !isBootstrapComplete()}>
 						<div class={styles.heroActions}>
-							<button type="button" class={styles.primaryButton} onClick={(): void => setIsWizardOpen(true)}>
+						<button
+							type="button"
+							class={styles.primaryButton}
+							onClick={(): void => {
+								setIsWizardOpen(true);
+							}}
+						>
 								Open bootstrap wizard
 							</button>
 						</div>
@@ -384,7 +413,13 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 									</h2>
 								</div>
 								<Show when={canDismissWizard()}>
-									<button type="button" class={styles.wizardCloseButton} onClick={(): void => setIsWizardOpen(false)}>
+									<button
+										type="button"
+										class={styles.wizardCloseButton}
+										onClick={(): void => {
+											setIsWizardOpen(false);
+										}}
+									>
 										Close
 									</button>
 								</Show>
@@ -433,14 +468,24 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 											<>
 												<label class={styles.field}>
 													<span class={styles.fieldLabel}>Protocol</span>
-													<select value={instanceForm.protocol} onInput={(event): void => setInstanceForm("protocol", event.currentTarget.value)}>
+												<select
+													value={instanceForm.protocol}
+													onInput={(event): void =>
+														setInstanceForm("protocol", event.currentTarget.value as InstanceForm["protocol"])
+													}
+												>
 														<option value="http">http</option>
 														<option value="https">https</option>
 													</select>
 												</label>
 												<label class={styles.field}>
 													<span class={styles.fieldLabel}>Access</span>
-													<select value={instanceForm.access} onInput={(event): void => setInstanceForm("access", event.currentTarget.value)}>
+												<select
+													value={instanceForm.access}
+													onInput={(event): void =>
+														setInstanceForm("access", event.currentTarget.value as InstanceForm["access"])
+													}
+												>
 														<option value="local">local</option>
 														<option value="remote">remote</option>
 													</select>
@@ -461,7 +506,10 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 							<>
 								<label class={styles.field}>
 									<span class={styles.fieldLabel}>Mode</span>
-									<select value={modeForm.mode} onInput={(event): void => setModeForm("mode", event.currentTarget.value)}>
+								<select
+									value={modeForm.mode}
+									onInput={(event): void => setModeForm("mode", event.currentTarget.value as ModeForm["mode"])}
+								>
 										<option value="personal">personal</option>
 										<option value="organizational">organizational</option>
 									</select>
@@ -553,7 +601,9 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 												type="button"
 												class={styles.secondaryButton}
 												disabled={isFirstStep()}
-												onClick={(): void => setCurrentStepIndex((index) => Math.max(index - 1, 0))}
+												onClick={(): void => {
+													setCurrentStepIndex((index) => Math.max(index - 1, 0));
+												}}
 											>
 												Back
 											</button>