Fix: persist project folder hierarchy

Backend/internal/bootstrap/service.go

@@ -10,6 +10,7 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+	"unicode"
 
 	"github.com/jackc/pgx/v5"
 
@@ -42,6 +43,8 @@ const (
 var (
 	ErrInstallationNotConfigured = errors.New("bootstrap installation step has not been completed")
 	ErrAdminNotConfigured        = errors.New("bootstrap admin step has not been completed")
+	ErrProjectNotFound           = errors.New("project not found")
+	ErrProjectFolderNotFound     = errors.New("project folder not found")
 )
 
 type Service struct {
@@ -177,6 +180,30 @@ type namedRecord struct {
 	Slug string `json:"slug"`
 }
 
+type ProjectHierarchyFolderRecord struct {
+	ID       string                         `json:"id"`
+	Label    string                         `json:"label"`
+	Children []ProjectHierarchyFolderRecord `json:"children"`
+}
+
+type CreateProjectFolderInput struct {
+	ProjectID      string
+	ParentFolderID string
+	Name           string
+}
+
+type CreateProjectFolderResult struct {
+	ProjectID     string                         `json:"projectId"`
+	CreatedFolder ProjectHierarchyFolderRecord   `json:"createdFolder"`
+	Folders       []ProjectHierarchyFolderRecord `json:"folders"`
+}
+
+type projectHierarchyFolderRow struct {
+	Path       string
+	ParentPath string
+	Label      string
+}
+
 func NewService(db *database.DB, posixRoot string) *Service {
 	return &Service{db: db, posixRoot: strings.TrimSpace(posixRoot)}
 }
@@ -794,6 +821,92 @@ func (service *Service) listProjects(ctx context.Context) ([]ProjectRecord, erro
 	return records, rows.Err()
 }
 
+func (service *Service) loadProjectByID(ctx context.Context, projectID string) (*ProjectRecord, error) {
+	var record ProjectRecord
+	err := service.db.Pool.QueryRow(ctx, `
+		SELECT id::text, organization_id::text, department_id::text, team_id::text, name, slug
+		FROM projects
+		WHERE id = $1::uuid
+		LIMIT 1;
+	`, projectID).Scan(&record.ID, &record.OrganizationID, &record.DepartmentID, &record.TeamID, &record.Name, &record.Slug)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, ErrProjectNotFound
+		}
+
+		return nil, err
+	}
+
+	return &record, nil
+}
+
+func (service *Service) GetProjectHierarchyFolders(ctx context.Context, projectID string) ([]ProjectHierarchyFolderRecord, error) {
+	project, err := service.loadProjectByID(ctx, projectID)
+	if err != nil {
+		return nil, err
+	}
+
+	rows, err := service.db.Pool.Query(ctx, `
+		SELECT path, COALESCE(parent_path, ''), COALESCE(resource_name, '')
+		FROM posix_nodes
+		WHERE node_kind = 'directory'::posix_node_kind
+		  AND logical_type = 'hierarchy_folder'
+		  AND project_slug = $1
+		ORDER BY depth ASC, path ASC;
+	`, project.Slug)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var folderRows []projectHierarchyFolderRow
+	for rows.Next() {
+		var row projectHierarchyFolderRow
+		if err := rows.Scan(&row.Path, &row.ParentPath, &row.Label); err != nil {
+			return nil, err
+		}
+		folderRows = append(folderRows, row)
+	}
+
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+
+	return buildProjectHierarchyFolderTree(folderRows, projectHierarchyRootPath(project.Slug)), nil
+}
+
+func (service *Service) CreateProjectFolder(ctx context.Context, input CreateProjectFolderInput) (CreateProjectFolderResult, error) {
+	project, err := service.loadProjectByID(ctx, strings.TrimSpace(input.ProjectID))
+	if err != nil {
+		return CreateProjectFolderResult{}, err
+	}
+
+	createdPath, _, err := service.createProjectHierarchyFolderOnDisk(project.Slug, strings.TrimSpace(input.ParentFolderID), input.Name)
+	if err != nil {
+		return CreateProjectFolderResult{}, err
+	}
+
+	if err := posixproj.NewProjector(service.db, service.posixRoot).Rebuild(ctx); err != nil {
+		return CreateProjectFolderResult{}, fmt.Errorf("rebuild POSIX projection: %w", err)
+	}
+
+	folders, err := service.GetProjectHierarchyFolders(ctx, project.ID)
+	if err != nil {
+		return CreateProjectFolderResult{}, err
+	}
+
+	createdFolder, ok := findProjectHierarchyFolder(folders, createdPath)
+	if !ok {
+		return CreateProjectFolderResult{}, fmt.Errorf("created project folder missing from projection")
+	}
+
+	return CreateProjectFolderResult{
+		ProjectID:     project.ID,
+		CreatedFolder: createdFolder,
+		Folders:       folders,
+	}, nil
+}
+
 func (service *Service) listWorkspaces(ctx context.Context) ([]WorkspaceRecord, error) {
 	rows, err := service.db.Pool.Query(ctx, `
 		SELECT id::text, organization_id::text, name, slug, kind::text, department_id::text, team_id::text, project_id::text
@@ -1069,6 +1182,194 @@ func (service *Service) ensureBootstrapPOSIXSkeleton(
 	return nil
 }
 
+func (service *Service) createProjectHierarchyFolderOnDisk(projectSlug, parentFolderID, name string) (string, string, error) {
+	rootPath := strings.TrimSpace(service.posixRoot)
+	if rootPath == "" {
+		return "", "", fmt.Errorf("POSIX root is not configured")
+	}
+
+	trimmedName := strings.TrimSpace(name)
+	if trimmedName == "" {
+		return "", "", fmt.Errorf("folder name is required")
+	}
+
+	projectRoot := filepath.Join(rootPath, "projects", slugDir("project", projectSlug))
+	childrenRoot := filepath.Join(projectRoot, "children")
+	parentDir := childrenRoot
+	containerProjectionPath := projectHierarchyRootPath(projectSlug)
+
+	if strings.TrimSpace(parentFolderID) != "" {
+		containerProjectionPath = filepath.ToSlash(filepath.Join(strings.TrimSpace(parentFolderID), "children"))
+		parentDir = filepath.Join(rootPath, filepath.FromSlash(containerProjectionPath))
+		info, err := os.Stat(parentDir)
+		if err != nil {
+			if os.IsNotExist(err) {
+				return "", "", ErrProjectFolderNotFound
+			}
+			return "", "", fmt.Errorf("stat parent project folder: %w", err)
+		}
+		if !info.IsDir() {
+			return "", "", ErrProjectFolderNotFound
+		}
+	}
+
+	if err := os.MkdirAll(parentDir, 0o755); err != nil {
+		return "", "", fmt.Errorf("create parent project folder path: %w", err)
+	}
+
+	baseSlug := normalizePOSIXSlug(trimmedName)
+	folderName := slugDir("folder", baseSlug)
+	folderDir := filepath.Join(parentDir, folderName)
+	folderSlug := baseSlug
+
+	for attempt := 2; ; attempt += 1 {
+		if _, err := os.Stat(folderDir); os.IsNotExist(err) {
+			break
+		} else if err != nil {
+			return "", "", fmt.Errorf("stat candidate project folder: %w", err)
+		}
+
+		folderSlug = fmt.Sprintf("%s-%d", baseSlug, attempt)
+		folderName = slugDir("folder", folderSlug)
+		folderDir = filepath.Join(parentDir, folderName)
+	}
+
+	if err := os.MkdirAll(filepath.Join(folderDir, "children"), 0o755); err != nil {
+		return "", "", fmt.Errorf("create project hierarchy folder: %w", err)
+	}
+
+	if err := writeJSONFile(filepath.Join(folderDir, "folder.json"), map[string]any{
+		"name": trimmedName,
+		"slug": folderSlug,
+		"type": "folder",
+	}); err != nil {
+		return "", "", fmt.Errorf("write project folder.json: %w", err)
+	}
+
+	if err := writeJSONFile(filepath.Join(folderDir, "acl.json"), map[string]any{
+		"version":  1,
+		"inherits": true,
+		"rules":    []any{},
+	}); err != nil {
+		return "", "", fmt.Errorf("write project acl.json: %w", err)
+	}
+
+	return filepath.ToSlash(filepath.Join(containerProjectionPath, folderName)), folderSlug, nil
+}
+
+func buildProjectHierarchyFolderTree(rows []projectHierarchyFolderRow, rootParentPath string) []ProjectHierarchyFolderRecord {
+	if len(rows) == 0 {
+		return nil
+	}
+
+	nodesByPath := make(map[string]*ProjectHierarchyFolderRecord, len(rows))
+	childrenByParent := make(map[string][]string)
+
+	for _, row := range rows {
+		label := strings.TrimSpace(row.Label)
+		if label == "" {
+			label = fallbackFolderLabel(row.Path)
+		}
+		nodesByPath[row.Path] = &ProjectHierarchyFolderRecord{
+			ID:       row.Path,
+			Label:    label,
+			Children: []ProjectHierarchyFolderRecord{},
+		}
+		childrenByParent[row.ParentPath] = append(childrenByParent[row.ParentPath], row.Path)
+	}
+
+	var build func(parentPath string) []ProjectHierarchyFolderRecord
+	build = func(parentPath string) []ProjectHierarchyFolderRecord {
+		childPaths := childrenByParent[parentPath]
+		if len(childPaths) == 0 {
+			return nil
+		}
+
+		folders := make([]ProjectHierarchyFolderRecord, 0, len(childPaths))
+		for _, childPath := range childPaths {
+			node := nodesByPath[childPath]
+			if node == nil {
+				continue
+			}
+
+			folder := ProjectHierarchyFolderRecord{
+				ID:       node.ID,
+				Label:    node.Label,
+				Children: build(filepath.ToSlash(filepath.Join(childPath, "children"))),
+			}
+			folders = append(folders, folder)
+		}
+
+		return folders
+	}
+
+	return build(rootParentPath)
+}
+
+func findProjectHierarchyFolder(folders []ProjectHierarchyFolderRecord, folderID string) (ProjectHierarchyFolderRecord, bool) {
+	for _, folder := range folders {
+		if folder.ID == folderID {
+			return folder, true
+		}
+
+		if child, ok := findProjectHierarchyFolder(folder.Children, folderID); ok {
+			return child, true
+		}
+	}
+
+	return ProjectHierarchyFolderRecord{}, false
+}
+
+func projectHierarchyRootPath(projectSlug string) string {
+	return filepath.ToSlash(filepath.Join("projects", slugDir("project", projectSlug), "children"))
+}
+
+func normalizePOSIXSlug(value string) string {
+	trimmed := strings.TrimSpace(strings.ToLower(value))
+	if trimmed == "" {
+		return "untitled"
+	}
+
+	var builder strings.Builder
+	lastDash := false
+	for _, r := range trimmed {
+		switch {
+		case unicode.IsLetter(r) || unicode.IsDigit(r):
+			builder.WriteRune(r)
+			lastDash = false
+		case r == '-' || r == '_' || unicode.IsSpace(r):
+			if !lastDash && builder.Len() > 0 {
+				builder.WriteByte('-')
+				lastDash = true
+			}
+		}
+	}
+
+	slug := strings.Trim(builder.String(), "-")
+	if slug == "" {
+		return "untitled"
+	}
+
+	return slug
+}
+
+func fallbackFolderLabel(path string) string {
+	base := filepath.Base(filepath.FromSlash(path))
+	trimmed := strings.TrimPrefix(base, "folder-")
+	parts := strings.FieldsFunc(trimmed, func(r rune) bool { return r == '-' || r == '_' })
+	for index, part := range parts {
+		if part == "" {
+			continue
+		}
+		parts[index] = strings.ToUpper(part[:1]) + part[1:]
+	}
+	label := strings.Join(parts, " ")
+	if label == "" {
+		return base
+	}
+	return label
+}
+
 func slugDir(prefix, slug string) string {
 	trimmedSlug := strings.TrimSpace(slug)
 	if trimmedSlug == "" {

Backend/internal/bootstrap/service_test.go

@@ -103,6 +103,83 @@ func TestEnsureBootstrapPOSIXSkeletonInitializesEmptyRoot(t *testing.T) {
 	}
 }
 
+func TestCreateProjectHierarchyFolderOnDiskCreatesExpectedFolderShape(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)
+	}
+
+	createdPath, createdSlug, err := service.createProjectHierarchyFolderOnDisk("primary-project", "", "Design System")
+	if err != nil {
+		t.Fatalf("createProjectHierarchyFolderOnDisk root folder: %v", err)
+	}
+	if createdPath != "projects/project-primary-project/children/folder-design-system" {
+		t.Fatalf("unexpected created path: %s", createdPath)
+	}
+	if createdSlug != "design-system" {
+		t.Fatalf("unexpected created slug: %s", createdSlug)
+	}
+
+	createdFolderPath := filepath.Join(rootPath, "projects", "project-primary-project", "children", "folder-design-system")
+	for _, path := range []string{
+		filepath.Join(createdFolderPath, "folder.json"),
+		filepath.Join(createdFolderPath, "acl.json"),
+		filepath.Join(createdFolderPath, "children"),
+	} {
+		if _, err := os.Stat(path); err != nil {
+			t.Fatalf("expected path to exist %s: %v", path, err)
+		}
+	}
+
+	folderPayload := readJSONFileForTest[map[string]any](t, filepath.Join(createdFolderPath, "folder.json"))
+	if folderPayload["name"] != "Design System" {
+		t.Fatalf("expected folder name Design System, got %#v", folderPayload["name"])
+	}
+	if folderPayload["slug"] != "design-system" {
+		t.Fatalf("expected folder slug design-system, got %#v", folderPayload["slug"])
+	}
+
+	nestedPath, nestedSlug, err := service.createProjectHierarchyFolderOnDisk("primary-project", createdPath, "Research")
+	if err != nil {
+		t.Fatalf("createProjectHierarchyFolderOnDisk nested folder: %v", err)
+	}
+	if nestedPath != "projects/project-primary-project/children/folder-design-system/children/folder-research" {
+		t.Fatalf("unexpected nested path: %s", nestedPath)
+	}
+	if nestedSlug != "research" {
+		t.Fatalf("unexpected nested slug: %s", nestedSlug)
+	}
+}
+
+func TestBuildProjectHierarchyFolderTreeBuildsNestedStructure(t *testing.T) {
+	rows := []projectHierarchyFolderRow{
+		{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"},
+		{Path: "projects/project-primary-project/children/folder-ops", ParentPath: projectHierarchyRootPath("primary-project"), Label: "Ops"},
+	}
+
+	folders := buildProjectHierarchyFolderTree(rows, projectHierarchyRootPath("primary-project"))
+	if len(folders) != 2 {
+		t.Fatalf("expected 2 top-level folders, got %d", len(folders))
+	}
+	if folders[0].Label != "Design" || folders[1].Label != "Ops" {
+		t.Fatalf("unexpected top-level folder labels: %#v", folders)
+	}
+	if len(folders[0].Children) != 1 || folders[0].Children[0].Label != "Research" {
+		t.Fatalf("unexpected nested folder structure: %#v", folders[0].Children)
+	}
+}
+
 func readJSONFileForTest[T any](t *testing.T, path string) T {
 	t.Helper()
 

Backend/internal/httpx/api_project_routes.go

@@ -0,0 +1,118 @@
+package httpx
+
+import (
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+
+	bootstrapservice "moku-backend/internal/bootstrap"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type createProjectFolderRequest struct {
+	Name           string `json:"name"`
+	ParentFolderID string `json:"parentFolderId"`
+}
+
+func (routes apiRoutes) handleProjectFolders(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
+	}
+
+	folders, err := routes.bootstrapService().GetProjectHierarchyFolders(r.Context(), projectID)
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err)
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": map[string]any{
+			"projectId": projectID,
+			"folders":   folders,
+		},
+		"meta": map[string]any{
+			"resource": "project-folders",
+		},
+	})
+}
+
+func (routes apiRoutes) handleCreateProjectFolder(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 := decodeProjectFolderRequest(w, r)
+	if !ok {
+		return
+	}
+
+	payload.Name = strings.TrimSpace(payload.Name)
+	payload.ParentFolderID = strings.TrimSpace(payload.ParentFolderID)
+	if payload.Name == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder name is required.")
+		return
+	}
+
+	result, err := routes.bootstrapService().CreateProjectFolder(r.Context(), bootstrapservice.CreateProjectFolderInput{
+		ProjectID:      projectID,
+		ParentFolderID: payload.ParentFolderID,
+		Name:           payload.Name,
+	})
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err)
+		return
+	}
+
+	WriteJSON(w, http.StatusCreated, map[string]any{
+		"data": result,
+		"meta": map[string]any{
+			"resource":  "project-folder-create",
+			"persisted": true,
+		},
+	})
+}
+
+func (routes apiRoutes) writeProjectFolderError(w http.ResponseWriter, r *http.Request, err error) {
+	switch {
+	case errors.Is(err, bootstrapservice.ErrProjectNotFound), errors.Is(err, bootstrapservice.ErrProjectFolderNotFound):
+		WriteError(w, http.StatusNotFound, RequestIDFromContext(r.Context()), "not_found", err.Error())
+	default:
+		routes.cfg.Logger.Error("persist project folder", "error", err, "path", r.URL.Path)
+		message := "Failed to persist project folder."
+		if routes.cfg.Config.IsDevelopment() {
+			message = message + " " + err.Error()
+		}
+		WriteError(w, http.StatusInternalServerError, RequestIDFromContext(r.Context()), "project_folder_persist_failed", message)
+	}
+}
+
+func decodeProjectFolderRequest(w http.ResponseWriter, r *http.Request) (createProjectFolderRequest, bool) {
+	var payload createProjectFolderRequest
+
+	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
+}

Backend/internal/httpx/api_routes.go

@@ -33,6 +33,10 @@ func (routes apiRoutes) Register(router chi.Router) {
 		apiRouter.Get("/app-shell", routes.handleAppShellState)
 		apiRouter.Get("/organizations", routes.handleOrganizations)
 		apiRouter.Get("/workspaces", routes.handleWorkspaces)
+		apiRouter.Route("/projects/{projectId}", func(projectRouter chi.Router) {
+			projectRouter.Get("/folders", routes.handleProjectFolders)
+			projectRouter.Post("/folders", routes.handleCreateProjectFolder)
+		})
 
 		if routes.cfg.Config.IsDevelopment() {
 			apiRouter.Post("/dev/bootstrap/reset", routes.handleDevelopmentBootstrapReset)

Frontend/src/components/shell/ProjectSelector/ProjectSelector.module.scss

@@ -192,13 +192,61 @@
 
 .treeSectionLabel {
   @include text-caption;
-  margin: 0 0 var(--space-2);
+  margin: 0;
   padding: 0 var(--space-3);
   color: var(--color-text-subtle);
   text-transform: uppercase;
   letter-spacing: 0.04em;
 }
 
+.treeSectionHeader {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: var(--space-2);
+	margin-bottom: var(--space-2);
+	padding-right: var(--space-1);
+}
+
+.treeControls {
+	display: inline-flex;
+	align-items: center;
+	gap: var(--space-1);
+	flex-wrap: wrap;
+	justify-content: flex-end;
+}
+
+.treeControlButton {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	width: calc(var(--control-size-md) - var(--space-1));
+	height: calc(var(--control-size-md) - var(--space-1));
+	@include text-caption;
+	padding: 0;
+	border: 1px solid color-mix(in srgb, var(--color-border) 46%, transparent);
+	border-radius: var(--radius-pill);
+	background: color-mix(in srgb, var(--color-surface) 95%, transparent);
+	color: var(--color-text-muted);
+	transition:
+		border-color 160ms var(--easing-standard),
+		background 160ms var(--easing-standard),
+		color 160ms var(--easing-standard);
+}
+
+.treeControlButton:hover,
+.treeControlButton:focus-visible {
+	border-color: color-mix(in srgb, var(--color-border-strong) 56%, transparent);
+	background: var(--color-surface-hover);
+	color: var(--color-text);
+	outline: none;
+}
+
+.treeControlButton:disabled {
+	opacity: 0.45;
+	cursor: default;
+}
+
 .treeList {
   list-style: none;
   display: grid;

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

@@ -1,9 +1,10 @@
 // Path: Frontend/src/components/shell/ProjectSelector/ProjectSelector.tsx
 
 import { For, Show, createEffect, createSignal, onCleanup, onMount, type JSX } from "solid-js";
-import { ChevronDown, ChevronRight, Folder, LayoutGrid } from "../../../lib/icons";
+import { ChevronDown, ChevronRight, Folder, LayoutGrid, ListCollapse, UnfoldVertical } from "../../../lib/icons";
 import { ProjectContextMenu } from "../ProjectContextMenu/ProjectContextMenu";
 import { useAppShellData } from "../data/app-shell.context";
+import { resolveAPIBase } from "../../../lib/api";
 import {
 	createProjectFolderTarget,
 	createProjectSurfaceTarget,
@@ -36,6 +37,20 @@ type ProjectLeafNode = {
 
 type ProjectTreeNode = ProjectFolderNode | ProjectLeafNode;
 
+type PersistedProjectFolderRecord = {
+	id: string;
+	label: string;
+	children: PersistedProjectFolderRecord[];
+};
+
+type ProjectFoldersResponse = {
+	data?: {
+		folders?: PersistedProjectFolderRecord[];
+	};
+	error?: string;
+	message?: string;
+};
+
 type PendingProjectFolderDraft = {
 	parentId: string | null;
 	depth: number;
@@ -61,17 +76,46 @@ type ProjectNodeLocation = {
 
 const LONG_PRESS_MS = 320;
 
-const createProjectFolderId = (): string => `project-folder-${Math.random().toString(36).slice(2, 10)}`;
-
 const getProjectTreeNodeId = (node: ProjectTreeNode): string =>
 	node.kind === "folder" ? node.id : node.item.id;
 
-const buildProjectTree = (items: readonly ProjectItem[]): ProjectTreeNode[] =>
-	items.map((item) => ({
-		kind: "project",
-		item,
+const buildPersistedFolderNodes = (folders: readonly PersistedProjectFolderRecord[] = []): ProjectTreeNode[] =>
+	folders.map((folder) => ({
+		kind: "folder",
+		id: folder.id,
+		label: folder.label,
+		children: buildPersistedFolderNodes(folder.children ?? []),
 	}));
 
+const buildProjectTree = (
+	items: readonly ProjectItem[],
+	folders: readonly PersistedProjectFolderRecord[] = [],
+): ProjectTreeNode[] => [
+	...items.map((item) => ({
+		kind: "project" as const,
+		item,
+	})),
+	...buildPersistedFolderNodes(folders),
+];
+
+const collectProjectFolderIds = (nodes: readonly ProjectTreeNode[]): string[] => {
+	const ids: string[] = [];
+
+	for (const node of nodes) {
+		if (node.kind !== "folder") {
+			continue;
+		}
+
+		ids.push(node.id);
+		ids.push(...collectProjectFolderIds(node.children));
+	}
+
+	return ids;
+};
+
+const readPersistedFolders = (body: ProjectFoldersResponse): PersistedProjectFolderRecord[] =>
+	Array.isArray(body.data?.folders) ? body.data.folders : [];
+
 const cloneProjectTreeNode = (node: ProjectTreeNode): ProjectTreeNode => {
 	if (node.kind === "project") {
 		return {
@@ -89,34 +133,6 @@ const cloneProjectTreeNode = (node: ProjectTreeNode): ProjectTreeNode => {
 	};
 };
 
-const insertProjectFolderNode = (
-	nodes: readonly ProjectTreeNode[],
-	parentId: string | null,
-	folder: ProjectFolderNode,
-): ProjectTreeNode[] => {
-	if (parentId === null) {
-		return [...nodes, folder];
-	}
-
-	return nodes.map((node) => {
-		if (node.kind !== "folder") {
-			return node;
-		}
-
-		if (node.id === parentId) {
-			return {
-				...node,
-				children: [...node.children, folder],
-			};
-		}
-
-		return {
-			...node,
-			children: insertProjectFolderNode(node.children, parentId, folder),
-		};
-	});
-};
-
 const findProjectNodeLocation = (
 	nodes: readonly ProjectTreeNode[],
 	nodeId: string,
@@ -336,6 +352,7 @@ const ProjectFolderBranch = (props: {
 	onSubmitPendingFolder: () => void;
 	onCancelPendingFolder: () => void;
 	dragState: ProjectDragState | null;
+	isTreeClickSuppressed: () => boolean;
 }): JSX.Element => (
 	<ul class={styles.treeList} role="list">
 		<Show when={props.nodes.length === 0 && props.pendingFolderDraft?.parentId !== props.parentId}>
@@ -368,18 +385,18 @@ const ProjectFolderBranch = (props: {
 									[styles.treeItemFolder]: true,
 									[styles.treeItemDragging]: isDraggedNode(),
 									[styles.treeItemDropBefore]: dropIntent() === "before",
-									[styles.treeItemDropAfter]: dropIntent() === "after",
-									[styles.treeItemDropInside]: dropIntent() === "inside",
-								}}
-								style={{ "--tree-depth": String(props.depth) }}
-								aria-expanded={!isCollapsed()}
-								onClick={() => {
-									if (props.dragState || suppressNextTreeClick()) {
-										return;
-									}
+								[styles.treeItemDropAfter]: dropIntent() === "after",
+								[styles.treeItemDropInside]: dropIntent() === "inside",
+							}}
+							style={{ "--tree-depth": String(props.depth) }}
+							aria-expanded={!isCollapsed()}
+							onClick={() => {
+								if (props.dragState || props.isTreeClickSuppressed()) {
+									return;
+								}
 
-									props.onToggleFolder(node.id);
-								}}
+								props.onToggleFolder(node.id);
+							}}
 								onContextMenu={(event): void => props.onOpenFolderMenu(event, node)}
 								onPointerDown={(event): void => props.onNodePointerDown(event, node.id)}
 								onPointerMove={(event): void =>
@@ -404,7 +421,7 @@ const ProjectFolderBranch = (props: {
 								</Show>
 							</button>
 
-							<Show when={!isCollapsed() && (node.children.length > 0 || props.pendingFolderDraft?.parentId === node.id)}>
+							<Show when={!isCollapsed() && ((node.children?.length ?? 0) > 0 || props.pendingFolderDraft?.parentId === node.id)}>
 								<ProjectFolderBranch
 									nodes={node.children}
 									depth={props.depth + 1}
@@ -423,6 +440,7 @@ const ProjectFolderBranch = (props: {
 									onSubmitPendingFolder={props.onSubmitPendingFolder}
 									onCancelPendingFolder={props.onCancelPendingFolder}
 									dragState={props.dragState}
+									isTreeClickSuppressed={props.isTreeClickSuppressed}
 								/>
 							</Show>
 						</li>
@@ -442,7 +460,7 @@ const ProjectFolderBranch = (props: {
 							}}
 							style={{ "--tree-depth": String(props.depth) }}
 							onClick={(): void => {
-								if (props.dragState || suppressNextTreeClick()) {
+								if (props.dragState || props.isTreeClickSuppressed()) {
 									return;
 								}
 
@@ -485,8 +503,9 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 	const [selectedProject, setSelectedProject] = createSignal(appShellData.activeProject());
 	const [drawerTop, setDrawerTop] = createSignal<number>(0);
 	const [collapsedFolderIds, setCollapsedFolderIds] = createSignal<readonly string[]>([]);
+	const [persistedFolders, setPersistedFolders] = createSignal<readonly PersistedProjectFolderRecord[]>([]);
 	const [projectTreeNodes, setProjectTreeNodes] = createSignal<ProjectTreeNode[]>(
-		buildProjectTree(appShellData.projectItems()),
+		buildProjectTree(appShellData.projectItems(), persistedFolders()),
 	);
 	const [pendingFolderDraft, setPendingFolderDraft] = createSignal<PendingProjectFolderDraft | null>(null);
 	const [pendingFolderName, setPendingFolderName] = createSignal("");
@@ -497,6 +516,8 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 	let contextMenuRef: HTMLDivElement | undefined;
 	let longPressTimer: number | undefined;
 	let suppressClickTimer: number | undefined;
+	let lastSelectedProjectId: string | null = null;
+	let latestPersistedFoldersRequest = 0;
 	const contextMenu = createProjectContextMenuController();
 
 	const clearLongPressTimer = (): void => {
@@ -527,16 +548,111 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 		);
 	};
 
+	const syncProjectTree = (): void => {
+		const nextTree = buildProjectTree(appShellData.projectItems(), persistedFolders());
+		const availableFolderIds = new Set(collectProjectFolderIds(nextTree));
+
+		setProjectTreeNodes(nextTree);
+		setCollapsedFolderIds((current) => current.filter((folderId) => availableFolderIds.has(folderId)));
+	};
+
+	const resetProjectTreeInteractionState = (): void => {
+		setCollapsedFolderIds([]);
+		setPendingFolderDraft(null);
+		setPendingFolderName("");
+		setDragState(null);
+	};
+
+	const folderIds = (): string[] => collectProjectFolderIds(projectTreeNodes());
+
+	const expandAllFolders = (): void => {
+		setCollapsedFolderIds([]);
+	};
+
+	const collapseAllFolders = (): void => {
+		setCollapsedFolderIds(folderIds());
+	};
+
+	const totalFolderCount = (): number => folderIds().length;
+
+	const areAllFoldersCollapsed = (): boolean => {
+		const folderCount = totalFolderCount();
+
+		return folderCount > 0 && collapsedFolderIds().length >= folderCount;
+	};
+
+	const toggleAllFolders = (): void => {
+		if (areAllFoldersCollapsed()) {
+			expandAllFolders();
+			return;
+		}
+
+		collapseAllFolders();
+	};
+
+	const loadPersistedFolders = async (projectId: string): Promise<void> => {
+		const requestId = latestPersistedFoldersRequest + 1;
+		latestPersistedFoldersRequest = requestId;
+
+		if (!projectId) {
+			setPersistedFolders([]);
+			return;
+		}
+
+		try {
+			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/folders`, {
+				headers: {
+					Accept: "application/json",
+				},
+			});
+			const body = (await response.json()) as ProjectFoldersResponse;
+
+			if (requestId !== latestPersistedFoldersRequest) {
+				return;
+			}
+
+			if (!response.ok) {
+				throw new Error(body.message || "Failed to load project folders.");
+			}
+
+			setPersistedFolders(readPersistedFolders(body));
+		} catch (error) {
+			if (requestId !== latestPersistedFoldersRequest) {
+				return;
+			}
+
+			console.error(error);
+			setPersistedFolders([]);
+		}
+	};
+
 	createEffect(() => {
 		setSelectedProject(appShellData.activeProject());
 	});
 
 	createEffect(() => {
-		setProjectTreeNodes(buildProjectTree(appShellData.projectItems()));
-		setCollapsedFolderIds([]);
-		setPendingFolderDraft(null);
-		setPendingFolderName("");
-		setDragState(null);
+		syncProjectTree();
+	});
+
+	createEffect(() => {
+		const projectId = selectedProject().id;
+
+		if (lastSelectedProjectId === null) {
+			lastSelectedProjectId = projectId;
+			return;
+		}
+
+		if (projectId === lastSelectedProjectId) {
+			return;
+		}
+
+		lastSelectedProjectId = projectId;
+		resetProjectTreeInteractionState();
+	});
+
+	createEffect(() => {
+		const projectId = selectedProject().id;
+		void loadPersistedFolders(projectId);
 	});
 
 	onMount(() => {
@@ -668,7 +784,7 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 		setPendingFolderDraft({ parentId, depth });
 	};
 
-	const submitPendingFolder = (): void => {
+	const submitPendingFolder = async (): Promise<void> => {
 		const name = pendingFolderName().trim();
 		const draft = pendingFolderDraft();
 
@@ -682,16 +798,31 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 			return;
 		}
 
-		setProjectTreeNodes((current) =>
-			insertProjectFolderNode(current, draft.parentId, {
-				kind: "folder",
-				id: createProjectFolderId(),
-				label: name,
-				children: [],
-			}),
-		);
-		setPendingFolderDraft(null);
-		setPendingFolderName("");
+		try {
+			const response = await fetch(`${resolveAPIBase()}/projects/${selectedProject().id}/folders`, {
+				method: "POST",
+				headers: {
+					Accept: "application/json",
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({
+					name,
+					parentFolderId: draft.parentId,
+				}),
+			});
+
+			const body = (await response.json()) as ProjectFoldersResponse;
+
+			if (!response.ok) {
+				throw new Error(body.message || "Failed to create project folder.");
+			}
+
+			setPersistedFolders(readPersistedFolders(body));
+			setPendingFolderDraft(null);
+			setPendingFolderName("");
+		} catch (error) {
+			console.error(error);
+		}
 	};
 
 	const cancelPendingFolder = (): void => {
@@ -724,6 +855,9 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 		contextMenu.openMenu(event, createProjectSurfaceTarget("Projects"));
 	};
 
+	const treeControlLabel = (): string =>
+		areAllFoldersCollapsed() ? "Expand all folders" : "Collapse all folders";
+
 	const handleNodePointerDown = (event: PointerEvent, nodeId: string): void => {
 		if (event.button !== 0 || pendingFolderDraft()) {
 			return;
@@ -752,7 +886,12 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 			return;
 		}
 
-		const bounds = event.currentTarget.getBoundingClientRect();
+		const currentTarget = event.currentTarget;
+		if (!(currentTarget instanceof HTMLElement)) {
+			return;
+		}
+
+		const bounds = currentTarget.getBoundingClientRect();
 		const relativeY = bounds.height <= 0 ? 0.5 : (event.clientY - bounds.top) / bounds.height;
 		let nextTarget: ProjectDragTarget;
 
@@ -861,9 +1000,29 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 						onContextMenu={handleSurfaceContextMenu}
 					>
 						<div class={styles.drawerBody}>
-							<Show when={!props.compact}>
-								<div class={styles.treeSectionLabel}>Projects</div>
-							</Show>
+							<div class={styles.treeSectionHeader}>
+								<Show when={!props.compact}>
+									<div class={styles.treeSectionLabel}>Projects</div>
+								</Show>
+
+								<div class={styles.treeControls}>
+									<button
+										type="button"
+										class={styles.treeControlButton}
+										onClick={toggleAllFolders}
+										aria-label={treeControlLabel()}
+										title={treeControlLabel()}
+										disabled={totalFolderCount() === 0}
+									>
+										<Show
+											when={areAllFoldersCollapsed()}
+											fallback={<ListCollapse size={16} strokeWidth={2} />}
+										>
+											<UnfoldVertical size={16} strokeWidth={2} />
+										</Show>
+									</button>
+								</div>
+							</div>
 
 							<ProjectFolderBranch
 								nodes={projectTreeNodes()}
@@ -889,6 +1048,7 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 								onSubmitPendingFolder={submitPendingFolder}
 								onCancelPendingFolder={cancelPendingFolder}
 								dragState={dragState()}
+								isTreeClickSuppressed={suppressNextTreeClick}
 							/>
 						</div>
 					</div>

Frontend/src/lib/icons/index.ts

@@ -10,6 +10,7 @@ export { default as Folder } from "lucide-solid/icons/folder";
 export { default as Home } from "lucide-solid/icons/house";
 export { default as Keyboard } from "lucide-solid/icons/keyboard";
 export { default as LayoutGrid } from "lucide-solid/icons/layout-grid";
+export { default as ListCollapse } from "lucide-solid/icons/list-collapse";
 export { default as LogOut } from "lucide-solid/icons/log-out";
 export { default as Moon } from "lucide-solid/icons/moon";
 export { default as Plus } from "lucide-solid/icons/plus";
@@ -18,5 +19,6 @@ export { default as Search } from "lucide-solid/icons/search";
 export { default as Settings } from "lucide-solid/icons/settings";
 export { default as Shield } from "lucide-solid/icons/shield";
 export { default as Sun } from "lucide-solid/icons/sun";
+export { default as UnfoldVertical } from "lucide-solid/icons/unfold-vertical";
 export { default as User } from "lucide-solid/icons/user";
 export { default as X } from "lucide-solid/icons/x";