Fix: add persisted project folder deletion

.gitignore

@@ -27,3 +27,5 @@ tmp/
 bin/
 
 .cgcignore
+
+POSIX/

Backend/cmd/posix/main.go

@@ -0,0 +1,52 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+
+	"moku-backend/internal/config"
+	"moku-backend/internal/database"
+	"moku-backend/internal/posixproj"
+)
+
+func main() {
+	command := "rebuild"
+	if len(os.Args) > 1 {
+		command = os.Args[1]
+	}
+
+	switch command {
+	case "rebuild":
+		if err := rebuildProjection(context.Background()); err != nil {
+			log.Fatalf("rebuild POSIX projection: %v", err)
+		}
+	default:
+		log.Fatalf("unsupported posix command %q (supported: rebuild)", command)
+	}
+}
+
+func rebuildProjection(ctx context.Context) error {
+	cfg := config.Load()
+
+	db, err := database.NewPostgres(cfg.PostgresURL)
+	if err != nil {
+		return fmt.Errorf("connect database: %w", err)
+	}
+	defer db.Close()
+
+	summary, err := posixproj.NewProjector(db, cfg.POSIXRoot).RebuildWithSummary(ctx)
+	if err != nil {
+		return err
+	}
+
+	fmt.Printf(
+		"POSIX projection rebuilt from %s\n  total nodes: %d\n  directories: %d\n  files: %d\n",
+		cfg.POSIXRoot,
+		summary.TotalNodes,
+		summary.DirectoryCount,
+		summary.FileCount,
+	)
+	return nil
+}

Backend/db/migrations/000004_posix_nodes.sql

@@ -0,0 +1,45 @@
+-- +goose Up
+
+CREATE TYPE posix_node_kind AS ENUM ('directory', 'file');
+
+CREATE TABLE IF NOT EXISTS posix_nodes (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  path TEXT NOT NULL UNIQUE,
+  parent_path TEXT,
+  name TEXT NOT NULL,
+  depth INTEGER NOT NULL,
+  node_kind posix_node_kind NOT NULL,
+  logical_type TEXT NOT NULL DEFAULT 'generic',
+  file_role TEXT,
+  resource_id TEXT,
+  resource_name TEXT,
+  resource_slug TEXT,
+  installation_id TEXT,
+  organization_id TEXT,
+  organization_slug TEXT,
+  department_slug TEXT,
+  team_slug TEXT,
+  project_slug TEXT,
+  personal_slug TEXT,
+  content_json JSONB,
+  size_bytes BIGINT NOT NULL DEFAULT 0,
+  checksum TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_posix_nodes_parent_path ON posix_nodes (parent_path);
+CREATE INDEX IF NOT EXISTS idx_posix_nodes_logical_type ON posix_nodes (logical_type);
+CREATE INDEX IF NOT EXISTS idx_posix_nodes_project_slug ON posix_nodes (project_slug);
+CREATE INDEX IF NOT EXISTS idx_posix_nodes_department_slug ON posix_nodes (department_slug);
+CREATE INDEX IF NOT EXISTS idx_posix_nodes_team_slug ON posix_nodes (team_slug);
+
+-- +goose Down
+
+DROP INDEX IF EXISTS idx_posix_nodes_team_slug;
+DROP INDEX IF EXISTS idx_posix_nodes_department_slug;
+DROP INDEX IF EXISTS idx_posix_nodes_project_slug;
+DROP INDEX IF EXISTS idx_posix_nodes_logical_type;
+DROP INDEX IF EXISTS idx_posix_nodes_parent_path;
+DROP TABLE IF EXISTS posix_nodes;
+DROP TYPE IF EXISTS posix_node_kind;

Backend/internal/bootstrap/service.go

@@ -4,13 +4,18 @@ package bootstrap
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
+	"os"
+	"path/filepath"
 	"strings"
+	"unicode"
 
 	"github.com/jackc/pgx/v5"
 
 	"moku-backend/internal/database"
+	"moku-backend/internal/posixproj"
 )
 
 const (
@@ -38,10 +43,13 @@ 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 {
 	db        *database.DB
+	posixRoot string
 }
 
 type SaveInstanceInput struct {
@@ -172,8 +180,43 @@ type namedRecord struct {
 	Slug string `json:"slug"`
 }
 
-func NewService(db *database.DB) *Service {
-	return &Service{db: db}
+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 DeleteProjectFolderInput struct {
+	ProjectID string
+	FolderID  string
+}
+
+type CreateProjectFolderResult struct {
+	ProjectID     string                         `json:"projectId"`
+	CreatedFolder ProjectHierarchyFolderRecord   `json:"createdFolder"`
+	Folders       []ProjectHierarchyFolderRecord `json:"folders"`
+}
+
+type DeleteProjectFolderResult struct {
+	ProjectID       string                         `json:"projectId"`
+	DeletedFolderID string                         `json:"deletedFolderId"`
+	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)}
 }
 
 func (service *Service) SaveInstance(ctx context.Context, input SaveInstanceInput) (InstallationRecord, error) {
@@ -405,6 +448,14 @@ func (service *Service) SaveStructure(ctx context.Context, input SaveStructureIn
 		return StructureRecord{}, err
 	}
 
+	if err := service.ensureBootstrapPOSIXSkeleton(installation, admin, organization, department, team, project); err != nil {
+		return StructureRecord{}, err
+	}
+
+	if err := posixproj.NewProjector(service.db, service.posixRoot).Rebuild(ctx); err != nil {
+		return StructureRecord{}, fmt.Errorf("rebuild POSIX projection: %w", err)
+	}
+
 	return StructureRecord{
 		Installation: installation,
 		Organization: organization,
@@ -781,6 +832,164 @@ 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) {
+	return service.getProjectHierarchyFoldersByRootPath(ctx, projectID, projectHierarchyRootPath)
+}
+
+func (service *Service) GetProjectTreeFolders(ctx context.Context, projectID string) ([]ProjectHierarchyFolderRecord, error) {
+	return service.getProjectHierarchyFoldersByRootPath(ctx, projectID, projectTreeRootPath)
+}
+
+func (service *Service) getProjectHierarchyFoldersByRootPath(
+	ctx context.Context,
+	projectID string,
+	rootPath func(projectSlug string) string,
+) ([]ProjectHierarchyFolderRecord, error) {
+	project, err := service.loadProjectByID(ctx, projectID)
+	if err != nil {
+		return nil, err
+	}
+
+	rootParentPath := rootPath(project.Slug)
+
+	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
+		  AND path LIKE $2
+		ORDER BY depth ASC, path ASC;
+	`, project.Slug, rootParentPath+"/%")
+	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, rootParentPath), nil
+}
+
+func (service *Service) CreateProjectFolder(ctx context.Context, input CreateProjectFolderInput) (CreateProjectFolderResult, error) {
+	return service.createProjectHierarchyFolder(ctx, input, projectHierarchyRootPath, service.createProjectHierarchyFolderOnDisk)
+}
+
+func (service *Service) CreateProjectTreeFolder(ctx context.Context, input CreateProjectFolderInput) (CreateProjectFolderResult, error) {
+	return service.createProjectHierarchyFolder(ctx, input, projectTreeRootPath, service.createProjectTreeFolderOnDisk)
+}
+
+func (service *Service) DeleteProjectFolder(ctx context.Context, input DeleteProjectFolderInput) (DeleteProjectFolderResult, error) {
+	return service.deleteProjectHierarchyFolder(ctx, input, projectHierarchyRootPath, service.deleteProjectHierarchyFolderOnDisk)
+}
+
+func (service *Service) DeleteProjectTreeFolder(ctx context.Context, input DeleteProjectFolderInput) (DeleteProjectFolderResult, error) {
+	return service.deleteProjectHierarchyFolder(ctx, input, projectTreeRootPath, service.deleteProjectTreeFolderOnDisk)
+}
+
+func (service *Service) createProjectHierarchyFolder(
+	ctx context.Context,
+	input CreateProjectFolderInput,
+	rootPath func(projectSlug string) string,
+	createOnDisk func(projectSlug, parentFolderID, name string) (string, string, error),
+) (CreateProjectFolderResult, error) {
+	project, err := service.loadProjectByID(ctx, strings.TrimSpace(input.ProjectID))
+	if err != nil {
+		return CreateProjectFolderResult{}, err
+	}
+
+	createdPath, _, err := createOnDisk(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.getProjectHierarchyFoldersByRootPath(ctx, project.ID, rootPath)
+	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) deleteProjectHierarchyFolder(
+	ctx context.Context,
+	input DeleteProjectFolderInput,
+	rootPath func(projectSlug string) string,
+	deleteOnDisk func(projectSlug, folderID string) (string, error),
+) (DeleteProjectFolderResult, error) {
+	project, err := service.loadProjectByID(ctx, strings.TrimSpace(input.ProjectID))
+	if err != nil {
+		return DeleteProjectFolderResult{}, err
+	}
+
+	deletedFolderID, err := deleteOnDisk(project.Slug, input.FolderID)
+	if err != nil {
+		return DeleteProjectFolderResult{}, err
+	}
+
+	if err := posixproj.NewProjector(service.db, service.posixRoot).Rebuild(ctx); err != nil {
+		return DeleteProjectFolderResult{}, fmt.Errorf("rebuild POSIX projection: %w", err)
+	}
+
+	folders, err := service.getProjectHierarchyFoldersByRootPath(ctx, project.ID, rootPath)
+	if err != nil {
+		return DeleteProjectFolderResult{}, err
+	}
+
+	if _, found := findProjectHierarchyFolder(folders, deletedFolderID); found {
+		return DeleteProjectFolderResult{}, fmt.Errorf("deleted project folder still present in projection")
+	}
+
+	return DeleteProjectFolderResult{
+		ProjectID:       project.ID,
+		DeletedFolderID: deletedFolderID,
+		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
@@ -901,3 +1110,430 @@ func personalHomeTitle(displayName string) string {
 
 	return fmt.Sprintf("%s's Home", trimmedDisplayName)
 }
+
+func (service *Service) ensureBootstrapPOSIXSkeleton(
+	installation InstallationRecord,
+	admin AdminSummary,
+	organization namedRecord,
+	department namedRecord,
+	team namedRecord,
+	project namedRecord,
+) error {
+	rootPath := strings.TrimSpace(service.posixRoot)
+	if rootPath == "" {
+		return nil
+	}
+
+	if err := os.MkdirAll(rootPath, 0o755); err != nil {
+		return fmt.Errorf("create POSIX root: %w", err)
+	}
+
+	if err := writeJSONFile(filepath.Join(rootPath, "settings.json"), map[string]any{
+		"installation": map[string]any{
+			"id":             installation.ID,
+			"name":           installation.Name,
+			"mode":           installation.Mode,
+			"access":         installation.Access,
+			"protocol":       installation.Protocol,
+			"host":           installation.Host,
+			"isBootstrapped": installation.IsBootstrapped,
+		},
+		"organization": map[string]any{
+			"id":   organization.ID,
+			"name": organization.Name,
+			"slug": organization.Slug,
+		},
+	}); err != nil {
+		return fmt.Errorf("write tenant settings.json: %w", err)
+	}
+
+	if err := writeJSONFile(filepath.Join(rootPath, "layout.json"), map[string]any{
+		"version": 1,
+		"type":    "tenant-layout",
+		"home": map[string]any{
+			"defaultProjectSlug": project.Slug,
+		},
+	}); err != nil {
+		return fmt.Errorf("write tenant layout.json: %w", err)
+	}
+
+	if err := os.MkdirAll(filepath.Join(rootPath, "catalog", "packs"), 0o755); err != nil {
+		return fmt.Errorf("create catalog packs root: %w", err)
+	}
+
+	if err := os.MkdirAll(filepath.Join(rootPath, "catalog", "standalone"), 0o755); err != nil {
+		return fmt.Errorf("create catalog standalone root: %w", err)
+	}
+
+	departmentPath := filepath.Join(rootPath, "departments", slugDir("department", department.Slug))
+	teamPath := filepath.Join(departmentPath, "teams", slugDir("team", team.Slug))
+	projectPath := filepath.Join(rootPath, "projects", slugDir("project", project.Slug))
+	usersPath := filepath.Join(rootPath, "users")
+
+	for _, dirPath := range []string{
+		departmentPath,
+		teamPath,
+		projectPath,
+		filepath.Join(projectPath, "children"),
+		filepath.Join(projectPath, "tree"),
+		filepath.Join(usersPath, "personals"),
+	} {
+		if err := os.MkdirAll(dirPath, 0o755); err != nil {
+			return fmt.Errorf("create POSIX directory %s: %w", dirPath, err)
+		}
+	}
+
+	if err := writeJSONFile(filepath.Join(departmentPath, "settings.json"), map[string]any{
+		"id":   department.ID,
+		"name": department.Name,
+		"slug": department.Slug,
+		"type": "department",
+	}); err != nil {
+		return fmt.Errorf("write department settings.json: %w", err)
+	}
+
+	if err := writeJSONFile(filepath.Join(departmentPath, "users.json"), map[string]any{
+		"owners": []map[string]string{{
+			"id":          admin.ID,
+			"email":       admin.Email,
+			"displayName": admin.DisplayName,
+		}},
+	}); err != nil {
+		return fmt.Errorf("write department users.json: %w", err)
+	}
+
+	if err := writeJSONFile(filepath.Join(teamPath, "settings.json"), map[string]any{
+		"id":   team.ID,
+		"name": team.Name,
+		"slug": team.Slug,
+		"type": "team",
+	}); err != nil {
+		return fmt.Errorf("write team settings.json: %w", err)
+	}
+
+	if err := writeJSONFile(filepath.Join(teamPath, "users.json"), map[string]any{
+		"owners": []map[string]string{{
+			"id":          admin.ID,
+			"email":       admin.Email,
+			"displayName": admin.DisplayName,
+		}},
+	}); err != nil {
+		return fmt.Errorf("write team users.json: %w", err)
+	}
+
+	if err := writeJSONFile(filepath.Join(projectPath, "settings.json"), map[string]any{
+		"id":   project.ID,
+		"name": project.Name,
+		"slug": project.Slug,
+		"type": "project",
+	}); err != nil {
+		return fmt.Errorf("write project settings.json: %w", err)
+	}
+
+	if err := writeJSONFile(filepath.Join(projectPath, "home.json"), map[string]any{
+		"type":    "project-home",
+		"project": project.Slug,
+		"widgets": []any{},
+	}); err != nil {
+		return fmt.Errorf("write project home.json: %w", err)
+	}
+
+	if err := writeJSONFile(filepath.Join(projectPath, "acl.json"), map[string]any{
+		"version":  1,
+		"inherits": true,
+		"rules":    []any{},
+	}); err != nil {
+		return fmt.Errorf("write project acl.json: %w", err)
+	}
+
+	if err := writeJSONFile(filepath.Join(usersPath, "settings.json"), map[string]any{
+		"primaryAdminId": admin.ID,
+	}); err != nil {
+		return fmt.Errorf("write users settings.json: %w", err)
+	}
+
+	if err := writeJSONFile(filepath.Join(usersPath, "data.json"), map[string]any{
+		"users": []map[string]string{{
+			"id":          admin.ID,
+			"email":       admin.Email,
+			"displayName": admin.DisplayName,
+		}},
+	}); err != nil {
+		return fmt.Errorf("write users data.json: %w", err)
+	}
+
+	return nil
+}
+
+func (service *Service) createProjectHierarchyFolderOnDisk(projectSlug, parentFolderID, name string) (string, string, error) {
+	return service.createProjectFolderOnDisk(projectSlug, parentFolderID, name, projectHierarchyRootPath)
+}
+
+func (service *Service) createProjectTreeFolderOnDisk(projectSlug, parentFolderID, name string) (string, string, error) {
+	return service.createProjectFolderOnDisk(projectSlug, parentFolderID, name, projectTreeRootPath)
+}
+
+func (service *Service) deleteProjectHierarchyFolderOnDisk(projectSlug, folderID string) (string, error) {
+	return service.deleteProjectFolderOnDisk(projectSlug, folderID, projectHierarchyRootPath)
+}
+
+func (service *Service) deleteProjectTreeFolderOnDisk(projectSlug, folderID string) (string, error) {
+	return service.deleteProjectFolderOnDisk(projectSlug, folderID, projectTreeRootPath)
+}
+
+func (service *Service) createProjectFolderOnDisk(
+	projectSlug, parentFolderID, name string,
+	rootPathBuilder func(projectSlug string) string,
+) (string, string, error) {
+	posixRoot := strings.TrimSpace(service.posixRoot)
+	if posixRoot == "" {
+		return "", "", fmt.Errorf("POSIX root is not configured")
+	}
+
+	trimmedName := strings.TrimSpace(name)
+	if trimmedName == "" {
+		return "", "", fmt.Errorf("folder name is required")
+	}
+
+	containerProjectionPath := rootPathBuilder(projectSlug)
+	parentDir := filepath.Join(posixRoot, filepath.FromSlash(containerProjectionPath))
+
+	if strings.TrimSpace(parentFolderID) != "" {
+		containerProjectionPath = filepath.ToSlash(filepath.Join(strings.TrimSpace(parentFolderID), "children"))
+		parentDir = filepath.Join(posixRoot, 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 (service *Service) deleteProjectFolderOnDisk(
+	projectSlug, folderID string,
+	rootPathBuilder func(projectSlug string) string,
+) (string, error) {
+	posixRoot := strings.TrimSpace(service.posixRoot)
+	if posixRoot == "" {
+		return "", fmt.Errorf("POSIX root is not configured")
+	}
+
+	trimmedFolderID := strings.TrimSpace(folderID)
+	if trimmedFolderID == "" {
+		return "", ErrProjectFolderNotFound
+	}
+
+	rootProjectionPath := rootPathBuilder(projectSlug)
+	folderProjectionPath := strings.TrimPrefix(filepath.ToSlash(filepath.Clean("/"+trimmedFolderID)), "/")
+	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
+	}
+
+	if err := os.RemoveAll(folderDir); err != nil {
+		return "", fmt.Errorf("delete project folder: %w", err)
+	}
+
+	return folderProjectionPath, 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 projectTreeRootPath(projectSlug string) string {
+	return filepath.ToSlash(filepath.Join("projects", slugDir("project", projectSlug), "tree"))
+}
+
+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 == "" {
+		return prefix
+	}
+
+	return fmt.Sprintf("%s-%s", prefix, trimmedSlug)
+}
+
+func writeJSONFile(path string, payload any) error {
+	parentDir := filepath.Dir(path)
+	if err := os.MkdirAll(parentDir, 0o755); err != nil {
+		return err
+	}
+
+	data, err := json.MarshalIndent(payload, "", "  ")
+	if err != nil {
+		return err
+	}
+
+	data = append(data, '\n')
+
+	return os.WriteFile(path, data, 0o644)
+}

Backend/internal/bootstrap/service_test.go

@@ -0,0 +1,247 @@
+package bootstrap
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestEnsureBootstrapPOSIXSkeletonInitializesEmptyRoot(t *testing.T) {
+	rootPath := filepath.Join(t.TempDir(), "POSIX")
+	t.Setenv("POSIX_ROOT", rootPath)
+
+	if _, err := os.Stat(rootPath); !os.IsNotExist(err) {
+		t.Fatalf("expected isolated POSIX root to start absent, got err=%v", err)
+	}
+
+	service := NewService(nil, os.Getenv("POSIX_ROOT"))
+
+	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)
+	}
+
+	requiredPaths := []string{
+		filepath.Join(rootPath, "settings.json"),
+		filepath.Join(rootPath, "layout.json"),
+		filepath.Join(rootPath, "catalog", "packs"),
+		filepath.Join(rootPath, "catalog", "standalone"),
+		filepath.Join(rootPath, "departments", "department-primary-department", "settings.json"),
+		filepath.Join(rootPath, "departments", "department-primary-department", "users.json"),
+		filepath.Join(rootPath, "departments", "department-primary-department", "teams", "team-primary-team", "settings.json"),
+		filepath.Join(rootPath, "departments", "department-primary-department", "teams", "team-primary-team", "users.json"),
+		filepath.Join(rootPath, "projects", "project-primary-project", "settings.json"),
+		filepath.Join(rootPath, "projects", "project-primary-project", "home.json"),
+		filepath.Join(rootPath, "projects", "project-primary-project", "acl.json"),
+		filepath.Join(rootPath, "projects", "project-primary-project", "children"),
+		filepath.Join(rootPath, "projects", "project-primary-project", "tree"),
+		filepath.Join(rootPath, "users", "settings.json"),
+		filepath.Join(rootPath, "users", "data.json"),
+		filepath.Join(rootPath, "users", "personals"),
+	}
+
+	for _, path := range requiredPaths {
+		if _, err := os.Stat(path); err != nil {
+			t.Fatalf("expected path to exist %s: %v", path, err)
+		}
+	}
+
+	settingsPayload := readJSONFileForTest[map[string]any](t, filepath.Join(rootPath, "settings.json"))
+	installationPayload, ok := settingsPayload["installation"].(map[string]any)
+	if !ok {
+		t.Fatalf("settings.json missing installation object: %#v", settingsPayload)
+	}
+	if installationPayload["name"] != "MangoPig" {
+		t.Fatalf("expected installation name MangoPig, got %#v", installationPayload["name"])
+	}
+	if installationPayload["isBootstrapped"] != true {
+		t.Fatalf("expected installation to be bootstrapped, got %#v", installationPayload["isBootstrapped"])
+	}
+
+	layoutPayload := readJSONFileForTest[map[string]any](t, filepath.Join(rootPath, "layout.json"))
+	homePayload, ok := layoutPayload["home"].(map[string]any)
+	if !ok {
+		t.Fatalf("layout.json missing home object: %#v", layoutPayload)
+	}
+	if homePayload["defaultProjectSlug"] != "primary-project" {
+		t.Fatalf("expected default project slug primary-project, got %#v", homePayload["defaultProjectSlug"])
+	}
+
+	projectSettings := readJSONFileForTest[map[string]any](t, filepath.Join(rootPath, "projects", "project-primary-project", "settings.json"))
+	if projectSettings["type"] != "project" {
+		t.Fatalf("expected project settings type project, got %#v", projectSettings["type"])
+	}
+
+	projectACL := readJSONFileForTest[map[string]any](t, filepath.Join(rootPath, "projects", "project-primary-project", "acl.json"))
+	if projectACL["inherits"] != true {
+		t.Fatalf("expected project acl to inherit by default, got %#v", projectACL["inherits"])
+	}
+
+	usersSettings := readJSONFileForTest[map[string]any](t, filepath.Join(rootPath, "users", "settings.json"))
+	if usersSettings["primaryAdminId"] != "admin-1" {
+		t.Fatalf("expected primary admin id admin-1, got %#v", usersSettings["primaryAdminId"])
+	}
+}
+
+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 TestCreateProjectTreeFolderOnDiskCreatesExpectedFolderShape(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.createProjectTreeFolderOnDisk("primary-project", "", "Docs")
+	if err != nil {
+		t.Fatalf("createProjectTreeFolderOnDisk root folder: %v", err)
+	}
+	if createdPath != "projects/project-primary-project/tree/folder-docs" {
+		t.Fatalf("unexpected created path: %s", createdPath)
+	}
+	if createdSlug != "docs" {
+		t.Fatalf("unexpected created slug: %s", createdSlug)
+	}
+
+	createdFolderPath := filepath.Join(rootPath, "projects", "project-primary-project", "tree", "folder-docs")
+	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)
+		}
+	}
+
+	nestedPath, nestedSlug, err := service.createProjectTreeFolderOnDisk("primary-project", createdPath, "Research")
+	if err != nil {
+		t.Fatalf("createProjectTreeFolderOnDisk nested folder: %v", err)
+	}
+	if nestedPath != "projects/project-primary-project/tree/folder-docs/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()
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read %s: %v", path, err)
+	}
+
+	var payload T
+	if err := json.Unmarshal(data, &payload); err != nil {
+		t.Fatalf("unmarshal %s: %v", path, err)
+	}
+
+	return payload
+}

Backend/internal/config/config.go

@@ -17,6 +17,7 @@ type Config struct {
 	APIPort         string
 	PostgresURL     string
 	ValkeyURL       string
+	POSIXRoot       string
 	ShutdownTimeout time.Duration
 }
 
@@ -29,6 +30,7 @@ func Load() *Config {
 		APIPort:         getEnv("BACKEND_API_PORT", "8081"),
 		PostgresURL:     getEnv("DATABASE_URL", "postgres://moku:moku_dev_password@localhost:5432/moku?sslmode=disable"),
 		ValkeyURL:       getEnv("VALKEY_URL", "redis://localhost:6379/0"),
+		POSIXRoot:       getEnv("POSIX_ROOT", "../POSIX"),
 		ShutdownTimeout: getDurationEnv("BACKEND_SHUTDOWN_TIMEOUT", 10*time.Second),
 	}
 }

Backend/internal/httpx/api_bootstrap_routes.go

@@ -341,7 +341,7 @@ func (routes apiRoutes) handleBootstrapStructureStep(w http.ResponseWriter, r *h
 }
 
 func (routes apiRoutes) bootstrapService() *bootstrapservice.Service {
-	return bootstrapservice.NewService(routes.cfg.Database)
+	return bootstrapservice.NewService(routes.cfg.Database, routes.cfg.Config.POSIXRoot)
 }
 
 func (routes apiRoutes) writeBootstrapStepResponse(w http.ResponseWriter, status int, step string, payload any) {

Backend/internal/httpx/api_project_routes.go

@@ -0,0 +1,252 @@
+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"`
+}
+
+type deleteProjectFolderRequest struct {
+	FolderID string `json:"folderId"`
+}
+
+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, "load")
+		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, "persist")
+		return
+	}
+
+	WriteJSON(w, http.StatusCreated, map[string]any{
+		"data": result,
+		"meta": map[string]any{
+			"resource":  "project-folder-create",
+			"persisted": true,
+		},
+	})
+}
+
+func (routes apiRoutes) handleDeleteProjectFolder(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 := decodeDeleteProjectFolderRequest(r)
+	if strings.TrimSpace(payload.FolderID) == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder ID is required.")
+		return
+	}
+
+	result, err := routes.bootstrapService().DeleteProjectFolder(r.Context(), bootstrapservice.DeleteProjectFolderInput{
+		ProjectID: projectID,
+		FolderID:  payload.FolderID,
+	})
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err, "delete")
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": result,
+		"meta": map[string]any{
+			"resource":  "project-folder-delete",
+			"persisted": true,
+		},
+	})
+}
+
+func (routes apiRoutes) handleProjectTreeFolders(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().GetProjectTreeFolders(r.Context(), projectID)
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err, "load")
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": map[string]any{
+			"projectId": projectID,
+			"folders":   folders,
+		},
+		"meta": map[string]any{
+			"resource": "project-tree-folders",
+		},
+	})
+}
+
+func (routes apiRoutes) handleCreateProjectTreeFolder(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().CreateProjectTreeFolder(r.Context(), bootstrapservice.CreateProjectFolderInput{
+		ProjectID:      projectID,
+		ParentFolderID: payload.ParentFolderID,
+		Name:           payload.Name,
+	})
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err, "persist")
+		return
+	}
+
+	WriteJSON(w, http.StatusCreated, map[string]any{
+		"data": result,
+		"meta": map[string]any{
+			"resource":  "project-tree-folder-create",
+			"persisted": true,
+		},
+	})
+}
+
+func (routes apiRoutes) handleDeleteProjectTreeFolder(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 := decodeDeleteProjectFolderRequest(r)
+	if strings.TrimSpace(payload.FolderID) == "" {
+		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder ID is required.")
+		return
+	}
+
+	result, err := routes.bootstrapService().DeleteProjectTreeFolder(r.Context(), bootstrapservice.DeleteProjectFolderInput{
+		ProjectID: projectID,
+		FolderID:  payload.FolderID,
+	})
+	if err != nil {
+		routes.writeProjectFolderError(w, r, err, "delete")
+		return
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"data": result,
+		"meta": map[string]any{
+			"resource":  "project-tree-folder-delete",
+			"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())
+	default:
+		routes.cfg.Logger.Error(operation+" project folder", "error", err, "path", r.URL.Path)
+		message := "Failed to " + operation + " project folder."
+		if routes.cfg.Config.IsDevelopment() {
+			message = message + " " + err.Error()
+		}
+		WriteError(w, http.StatusInternalServerError, RequestIDFromContext(r.Context()), "project_folder_"+operation+"_failed", message)
+	}
+}
+
+func decodeDeleteProjectFolderRequest(r *http.Request) deleteProjectFolderRequest {
+	return deleteProjectFolderRequest{
+		FolderID: strings.TrimSpace(r.URL.Query().Get("folderId")),
+	}
+}
+
+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,14 @@ 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)
+			projectRouter.Delete("/folders", routes.handleDeleteProjectFolder)
+			projectRouter.Get("/tree/folders", routes.handleProjectTreeFolders)
+			projectRouter.Post("/tree/folders", routes.handleCreateProjectTreeFolder)
+			projectRouter.Delete("/tree/folders", routes.handleDeleteProjectTreeFolder)
+		})
 
 		if routes.cfg.Config.IsDevelopment() {
 			apiRouter.Post("/dev/bootstrap/reset", routes.handleDevelopmentBootstrapReset)

Backend/internal/posixproj/projector.go

@@ -0,0 +1,553 @@
+package posixproj
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"moku-backend/internal/database"
+)
+
+const rootProjectionPath = "/"
+
+type Projector struct {
+	db   *database.DB
+	root string
+}
+
+type RebuildSummary struct {
+	TotalNodes      int
+	DirectoryCount  int
+	FileCount       int
+}
+
+type NodeKind string
+
+const (
+	NodeKindDirectory NodeKind = "directory"
+	NodeKindFile      NodeKind = "file"
+)
+
+type Scope struct {
+	InstallationID  string
+	OrganizationID  string
+	OrganizationSlug string
+	DepartmentSlug  string
+	TeamSlug        string
+	ProjectSlug     string
+	PersonalSlug    string
+}
+
+type Node struct {
+	Path            string
+	ParentPath      *string
+	Name            string
+	Depth           int
+	NodeKind        NodeKind
+	LogicalType     string
+	FileRole        string
+	ResourceID      string
+	ResourceName    string
+	ResourceSlug    string
+	InstallationID  string
+	OrganizationID  string
+	OrganizationSlug string
+	DepartmentSlug  string
+	TeamSlug        string
+	ProjectSlug     string
+	PersonalSlug    string
+	ContentJSON     []byte
+	SizeBytes       int64
+	Checksum        string
+}
+
+func NewProjector(db *database.DB, root string) *Projector {
+	return &Projector{db: db, root: strings.TrimSpace(root)}
+}
+
+func (projector *Projector) Rebuild(ctx context.Context) error {
+	_, err := projector.RebuildWithSummary(ctx)
+	return err
+}
+
+func (projector *Projector) RebuildWithSummary(ctx context.Context) (RebuildSummary, error) {
+	if projector == nil || projector.db == nil || projector.db.Pool == nil {
+		return RebuildSummary{}, nil
+	}
+
+	nodes, err := ScanRoot(projector.root)
+	if err != nil {
+		return RebuildSummary{}, err
+	}
+
+	summary := summarizeNodes(nodes)
+
+	tx, err := projector.db.Pool.Begin(ctx)
+	if err != nil {
+		return RebuildSummary{}, err
+	}
+	defer func() {
+		_ = tx.Rollback(ctx)
+	}()
+
+	if _, err := tx.Exec(ctx, `DELETE FROM posix_nodes;`); err != nil {
+		return RebuildSummary{}, fmt.Errorf("clear posix_nodes: %w", err)
+	}
+
+	for _, node := range nodes {
+		if _, err := tx.Exec(ctx, `
+			INSERT INTO posix_nodes (
+				path,
+				parent_path,
+				name,
+				depth,
+				node_kind,
+				logical_type,
+				file_role,
+				resource_id,
+				resource_name,
+				resource_slug,
+				installation_id,
+				organization_id,
+				organization_slug,
+				department_slug,
+				team_slug,
+				project_slug,
+				personal_slug,
+				content_json,
+				size_bytes,
+				checksum
+			) VALUES (
+				$1, $2, $3, $4, $5::posix_node_kind, $6, $7, $8, $9, $10,
+				$11, $12, $13, $14, $15, $16, $17, $18::jsonb, $19, $20
+			);
+		`,
+			node.Path,
+			node.ParentPath,
+			node.Name,
+			node.Depth,
+			string(node.NodeKind),
+			node.LogicalType,
+			node.FileRole,
+			node.ResourceID,
+			node.ResourceName,
+			node.ResourceSlug,
+			node.InstallationID,
+			node.OrganizationID,
+			node.OrganizationSlug,
+			node.DepartmentSlug,
+			node.TeamSlug,
+			node.ProjectSlug,
+			node.PersonalSlug,
+				node.ContentJSON,
+				node.SizeBytes,
+				node.Checksum,
+		); err != nil {
+			return RebuildSummary{}, fmt.Errorf("insert posix node %s: %w", node.Path, err)
+		}
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return RebuildSummary{}, err
+	}
+
+	return summary, nil
+}
+
+func ScanRoot(root string) ([]Node, error) {
+	rootPath := strings.TrimSpace(root)
+	if rootPath == "" {
+		return nil, nil
+	}
+
+	info, err := os.Stat(rootPath)
+	if err != nil {
+		return nil, fmt.Errorf("stat POSIX root: %w", err)
+	}
+	if !info.IsDir() {
+		return nil, fmt.Errorf("POSIX root is not a directory: %s", rootPath)
+	}
+
+	rootScope, err := loadRootScope(rootPath)
+	if err != nil {
+		return nil, err
+	}
+
+	nodes := []Node{{
+		Path:             rootProjectionPath,
+		ParentPath:       nil,
+		Name:             filepath.Base(rootPath),
+		Depth:            0,
+		NodeKind:         NodeKindDirectory,
+		LogicalType:      "tenant_root",
+		InstallationID:   rootScope.InstallationID,
+		OrganizationID:   rootScope.OrganizationID,
+		OrganizationSlug: rootScope.OrganizationSlug,
+	}}
+
+	err = filepath.WalkDir(rootPath, func(path string, entry fs.DirEntry, walkErr error) error {
+		if walkErr != nil {
+			return walkErr
+		}
+		if path == rootPath {
+			return nil
+		}
+
+		relPath, err := filepath.Rel(rootPath, path)
+		if err != nil {
+			return err
+		}
+		relPath = filepath.ToSlash(relPath)
+		if relPath == "." {
+			return nil
+		}
+
+		node, err := buildNode(rootPath, relPath, entry, rootScope)
+		if err != nil {
+			return err
+		}
+
+		nodes = append(nodes, node)
+		return nil
+	})
+	if err != nil {
+		return nil, fmt.Errorf("scan POSIX root: %w", err)
+	}
+
+	return nodes, nil
+}
+
+func loadRootScope(rootPath string) (Scope, error) {
+	settingsPath := filepath.Join(rootPath, "settings.json")
+	content, err := os.ReadFile(settingsPath)
+	if err != nil {
+		if errorsIsNotExist(err) {
+			return Scope{}, nil
+		}
+		return Scope{}, fmt.Errorf("read root settings.json: %w", err)
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal(content, &payload); err != nil {
+		return Scope{}, fmt.Errorf("decode root settings.json: %w", err)
+	}
+
+	installation, _ := payload["installation"].(map[string]any)
+	organization, _ := payload["organization"].(map[string]any)
+
+	return Scope{
+		InstallationID:  stringValue(installation["id"]),
+		OrganizationID:  stringValue(organization["id"]),
+		OrganizationSlug: stringValue(organization["slug"]),
+	}, nil
+}
+
+func buildNode(rootPath, relPath string, entry fs.DirEntry, rootScope Scope) (Node, error) {
+	scope := deriveScope(relPath, rootScope)
+	parentPath := projectionParentPath(relPath)
+	logicalType, fileRole := classifyPath(relPath, entry.IsDir())
+
+	node := Node{
+		Path:             relPath,
+		ParentPath:       parentPath,
+		Name:             entry.Name(),
+		Depth:            strings.Count(relPath, "/") + 1,
+		NodeKind:         NodeKindDirectory,
+		LogicalType:      logicalType,
+		FileRole:         fileRole,
+		InstallationID:   scope.InstallationID,
+		OrganizationID:   scope.OrganizationID,
+		OrganizationSlug: scope.OrganizationSlug,
+		DepartmentSlug:   scope.DepartmentSlug,
+		TeamSlug:         scope.TeamSlug,
+		ProjectSlug:      scope.ProjectSlug,
+		PersonalSlug:     scope.PersonalSlug,
+	}
+
+	if entry.IsDir() {
+		return node, nil
+	}
+
+	absPath := filepath.Join(rootPath, filepath.FromSlash(relPath))
+	content, err := os.ReadFile(absPath)
+	if err != nil {
+		return Node{}, fmt.Errorf("read POSIX file %s: %w", relPath, err)
+	}
+
+	hash := sha256.Sum256(content)
+	node.NodeKind = NodeKindFile
+	node.SizeBytes = int64(len(content))
+	node.Checksum = hex.EncodeToString(hash[:])
+
+	if strings.EqualFold(filepath.Ext(entry.Name()), ".json") {
+		var payload map[string]any
+		if err := json.Unmarshal(content, &payload); err == nil {
+			jsonContent, err := json.Marshal(payload)
+			if err != nil {
+				return Node{}, fmt.Errorf("remarshal POSIX file %s: %w", relPath, err)
+			}
+			node.ContentJSON = jsonContent
+			node.ResourceID = stringValue(payload["id"])
+			node.ResourceName = stringValue(payload["name"])
+			node.ResourceSlug = stringValue(payload["slug"])
+			if node.ResourceID == "" && fileRole == "settings" && logicalType == "tenant" {
+				installation, _ := payload["installation"].(map[string]any)
+				organization, _ := payload["organization"].(map[string]any)
+				node.ResourceID = stringValue(installation["id"])
+				node.ResourceName = stringValue(installation["name"])
+				node.InstallationID = stringValue(installation["id"])
+				node.OrganizationID = stringValue(organization["id"])
+				node.OrganizationSlug = firstNonEmpty(node.OrganizationSlug, stringValue(organization["slug"]))
+			}
+			if node.ResourceID == "" && fileRole == "users" {
+				node.ResourceName = firstNonEmpty(node.ResourceName, parentEntityName(logicalType, scope))
+			}
+		}
+	}
+
+	if node.ResourceSlug == "" {
+		node.ResourceSlug = inferredResourceSlug(logicalType, scope)
+	}
+
+	return node, nil
+}
+
+func deriveScope(relPath string, rootScope Scope) Scope {
+	scope := rootScope
+	parts := strings.Split(relPath, "/")
+	for _, part := range parts {
+		switch {
+		case strings.HasPrefix(part, "department-"):
+			scope.DepartmentSlug = strings.TrimPrefix(part, "department-")
+		case strings.HasPrefix(part, "team-"):
+			scope.TeamSlug = strings.TrimPrefix(part, "team-")
+		case strings.HasPrefix(part, "project-"):
+			scope.ProjectSlug = strings.TrimPrefix(part, "project-")
+		case strings.HasPrefix(part, "personal-"):
+			scope.PersonalSlug = strings.TrimPrefix(part, "personal-")
+		}
+	}
+	return scope
+}
+
+func classifyPath(relPath string, isDir bool) (logicalType, fileRole string) {
+	parts := strings.Split(relPath, "/")
+	name := parts[len(parts)-1]
+	if !isDir {
+		fileRole = strings.TrimSuffix(name, filepath.Ext(name))
+	}
+
+	hasChildrenAncestor := pathContainsSegment(parts, "children")
+	hasTreeAncestor := pathContainsSegment(parts, "tree")
+	parentName := ""
+	if len(parts) >= 2 {
+		parentName = parts[len(parts)-2]
+	}
+
+	switch {
+	case relPath == "settings.json":
+		return "tenant", "settings"
+	case relPath == "layout.json":
+		return "tenant", "layout"
+	case len(parts) >= 1 && parts[0] == "catalog":
+		if isDir {
+			if len(parts) == 1 {
+				return "catalog", ""
+			}
+			if len(parts) >= 2 && parts[1] == "packs" {
+				if len(parts) == 2 {
+					return "catalog_packs", ""
+				}
+				if len(parts) == 3 {
+					return "catalog_pack", ""
+				}
+				if len(parts) >= 4 && parts[3] == "entries" {
+					return "catalog_pack_entries", ""
+				}
+				return "catalog_entry", ""
+			}
+			if len(parts) >= 2 && parts[1] == "standalone" {
+				if len(parts) == 2 {
+					return "catalog_standalone", ""
+				}
+				return "catalog_entry", ""
+			}
+		}
+		return "catalog", fileRole
+	case len(parts) >= 2 && parts[0] == "departments" && strings.HasPrefix(parts[1], "department-"):
+		if isDir {
+			if len(parts) == 2 {
+				return "department", ""
+			}
+			if len(parts) == 3 && parts[2] == "teams" {
+				return "department_teams", ""
+			}
+			if len(parts) >= 4 && strings.HasPrefix(parts[3], "team-") {
+				return "team", ""
+			}
+		}
+		if len(parts) >= 4 && strings.HasPrefix(parts[3], "team-") {
+			return "team", fileRole
+		}
+		return "department", fileRole
+	case len(parts) >= 2 && parts[0] == "projects" && strings.HasPrefix(parts[1], "project-"):
+		if isDir {
+			if strings.HasPrefix(name, "project-") {
+				return "project", ""
+			}
+			if name == "children" {
+				return "project_children", ""
+			}
+			if name == "tree" {
+				return "project_tree", ""
+			}
+			if hasChildrenAncestor && strings.HasPrefix(name, "folder-") {
+				return "hierarchy_folder", ""
+			}
+			if hasTreeAncestor && strings.HasPrefix(name, "folder-") {
+				return "hierarchy_folder", ""
+			}
+			if hasTreeAncestor && strings.HasPrefix(name, "item-") {
+				return "item", ""
+			}
+		}
+		if hasChildrenAncestor && strings.HasPrefix(parentName, "folder-") {
+			return "hierarchy_folder", fileRole
+		}
+		if hasTreeAncestor {
+			if strings.HasPrefix(parentName, "item-") {
+				return "item", fileRole
+			}
+			if strings.HasPrefix(parentName, "folder-") {
+				return "hierarchy_folder", fileRole
+			}
+		}
+		return "project", fileRole
+	case len(parts) >= 1 && parts[0] == "users":
+		if isDir {
+			if len(parts) == 1 {
+				return "users", ""
+			}
+			if len(parts) == 2 && parts[1] == "personals" {
+				return "personals", ""
+			}
+			if len(parts) >= 3 && parts[1] == "personals" && strings.HasPrefix(parts[2], "personal-") {
+				return "personal", ""
+			}
+			if strings.Contains(relPath, "/tree/") || strings.HasSuffix(relPath, "/tree") {
+				if strings.HasPrefix(name, "folder-") {
+					return "folder", ""
+				}
+				if strings.HasPrefix(name, "item-") {
+					return "item", ""
+				}
+			}
+		}
+		if len(parts) >= 3 && parts[1] == "personals" && strings.HasPrefix(parts[2], "personal-") {
+			if strings.Contains(relPath, "/tree/") {
+				if strings.HasPrefix(parts[len(parts)-2], "item-") {
+					return "item", fileRole
+				}
+				if strings.HasPrefix(parts[len(parts)-2], "folder-") {
+					return "folder", fileRole
+				}
+			}
+			return "personal", fileRole
+		}
+		return "users", fileRole
+	default:
+		if isDir {
+			return "directory", ""
+		}
+		return "file", fileRole
+	}
+}
+
+func pathContainsSegment(parts []string, target string) bool {
+	for _, part := range parts {
+		if part == target {
+			return true
+		}
+	}
+	return false
+}
+
+func projectionParentPath(relPath string) *string {
+	if relPath == "" || relPath == rootProjectionPath {
+		return nil
+	}
+	parent := filepath.ToSlash(filepath.Dir(relPath))
+	if parent == "." || parent == "" {
+		root := rootProjectionPath
+		return &root
+	}
+	return &parent
+}
+
+func inferredResourceSlug(logicalType string, scope Scope) string {
+	switch logicalType {
+	case "department":
+		return scope.DepartmentSlug
+	case "team":
+		return scope.TeamSlug
+	case "project":
+		return scope.ProjectSlug
+	case "personal":
+		return scope.PersonalSlug
+	default:
+		return ""
+	}
+}
+
+func parentEntityName(logicalType string, scope Scope) string {
+	switch logicalType {
+	case "department":
+		return scope.DepartmentSlug
+	case "team":
+		return scope.TeamSlug
+	case "project":
+		return scope.ProjectSlug
+	case "personal":
+		return scope.PersonalSlug
+	default:
+		return ""
+	}
+}
+
+func stringValue(value any) string {
+	stringValue, _ := value.(string)
+	return strings.TrimSpace(stringValue)
+}
+
+func firstNonEmpty(values ...string) string {
+	for _, value := range values {
+		trimmed := strings.TrimSpace(value)
+		if trimmed != "" {
+			return trimmed
+		}
+	}
+	return ""
+}
+
+func summarizeNodes(nodes []Node) RebuildSummary {
+	summary := RebuildSummary{TotalNodes: len(nodes)}
+	for _, node := range nodes {
+		switch node.NodeKind {
+		case NodeKindDirectory:
+			summary.DirectoryCount++
+		case NodeKindFile:
+			summary.FileCount++
+		}
+	}
+	return summary
+}
+
+func errorsIsNotExist(err error) bool {
+	return err != nil && os.IsNotExist(err)
+}

Backend/internal/posixproj/projector_test.go

@@ -0,0 +1,232 @@
+package posixproj
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestScanRootBuildsProjectedNodesFromBootstrapShape(t *testing.T) {
+	root := filepath.Join(t.TempDir(), "POSIX")
+
+	mustMkdirAll(t, filepath.Join(root, "catalog", "packs"))
+	mustMkdirAll(t, filepath.Join(root, "catalog", "standalone"))
+	mustMkdirAll(t, filepath.Join(root, "departments", "department-primary-department", "teams", "team-primary-team"))
+	mustMkdirAll(t, filepath.Join(root, "projects", "project-primary-project", "children", "folder-design", "children", "project-web", "children"))
+	mustMkdirAll(t, filepath.Join(root, "projects", "project-primary-project", "children", "folder-design", "children", "project-web", "tree"))
+	mustMkdirAll(t, filepath.Join(root, "projects", "project-primary-project", "tree"))
+	mustMkdirAll(t, filepath.Join(root, "projects", "project-primary-project", "tree", "folder-docs", "children"))
+	mustMkdirAll(t, filepath.Join(root, "projects", "project-primary-project", "tree", "folder-docs", "item-roadmap"))
+	mustMkdirAll(t, filepath.Join(root, "users", "personals"))
+
+	mustWriteJSON(t, filepath.Join(root, "settings.json"), map[string]any{
+		"installation": map[string]any{
+			"id":             "installation-1",
+			"name":           "MangoPig",
+			"isBootstrapped": true,
+		},
+		"organization": map[string]any{
+			"id":   "org-1",
+			"name": "Primary Organization",
+			"slug": "primary-organization",
+		},
+	})
+	mustWriteJSON(t, filepath.Join(root, "layout.json"), map[string]any{
+		"type": "tenant-layout",
+		"home": map[string]any{"defaultProjectSlug": "primary-project"},
+	})
+	mustWriteJSON(t, filepath.Join(root, "departments", "department-primary-department", "settings.json"), map[string]any{
+		"id":   "dept-1",
+		"name": "Primary Department",
+		"slug": "primary-department",
+		"type": "department",
+	})
+	mustWriteJSON(t, filepath.Join(root, "departments", "department-primary-department", "users.json"), map[string]any{
+		"users": []map[string]any{{"id": "admin-1"}},
+	})
+	mustWriteJSON(t, filepath.Join(root, "departments", "department-primary-department", "teams", "team-primary-team", "settings.json"), map[string]any{
+		"id":   "team-1",
+		"name": "Primary Team",
+		"slug": "primary-team",
+		"type": "team",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "settings.json"), map[string]any{
+		"id":   "project-1",
+		"name": "Primary Project",
+		"slug": "primary-project",
+		"type": "project",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "home.json"), map[string]any{
+		"type":    "project-home",
+		"project": "primary-project",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "acl.json"), map[string]any{
+		"inherits": true,
+		"rules":    []any{},
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "children", "folder-design", "folder.json"), map[string]any{
+		"name": "Design",
+		"slug": "design",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "children", "folder-design", "acl.json"), map[string]any{
+		"inherits": true,
+		"rules":    []any{},
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "children", "folder-design", "children", "project-web", "settings.json"), map[string]any{
+		"id":   "project-2",
+		"name": "Web Project",
+		"slug": "web",
+		"type": "project",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "children", "folder-design", "children", "project-web", "home.json"), map[string]any{
+		"type":    "project-home",
+		"project": "web",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "children", "folder-design", "children", "project-web", "acl.json"), map[string]any{
+		"inherits": true,
+		"rules":    []any{},
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "tree", "folder-docs", "folder.json"), map[string]any{
+		"name": "Docs",
+		"slug": "docs",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "tree", "folder-docs", "item-roadmap", "item.json"), map[string]any{
+		"id":   "item-1",
+		"name": "Roadmap",
+		"slug": "roadmap",
+		"type": "board",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "tree", "folder-docs", "item-roadmap", "schema.json"), map[string]any{
+		"type": "object",
+	})
+	mustWriteJSON(t, filepath.Join(root, "projects", "project-primary-project", "tree", "folder-docs", "item-roadmap", "data.json"), map[string]any{
+		"title": "Roadmap",
+	})
+	mustWriteJSON(t, filepath.Join(root, "users", "settings.json"), map[string]any{
+		"primaryAdminId": "admin-1",
+	})
+	mustWriteJSON(t, filepath.Join(root, "users", "data.json"), map[string]any{
+		"users": []map[string]any{{"id": "admin-1", "email": "ronald@example.com"}},
+	})
+
+	nodes, err := ScanRoot(root)
+	if err != nil {
+		t.Fatalf("ScanRoot() error = %v", err)
+	}
+
+	index := make(map[string]Node, len(nodes))
+	for _, node := range nodes {
+		index[node.Path] = node
+	}
+
+	rootNode, ok := index[rootProjectionPath]
+	if !ok {
+		t.Fatalf("expected synthetic root node")
+	}
+	if rootNode.LogicalType != "tenant_root" {
+		t.Fatalf("expected root logical type tenant_root, got %q", rootNode.LogicalType)
+	}
+	if rootNode.OrganizationSlug != "primary-organization" {
+		t.Fatalf("expected root organization slug primary-organization, got %q", rootNode.OrganizationSlug)
+	}
+
+	tenantSettings := index["settings.json"]
+	if tenantSettings.LogicalType != "tenant" || tenantSettings.FileRole != "settings" {
+		t.Fatalf("unexpected tenant settings classification: %#v", tenantSettings)
+	}
+	if tenantSettings.InstallationID != "installation-1" {
+		t.Fatalf("expected installation id installation-1, got %q", tenantSettings.InstallationID)
+	}
+
+	deptSettings := index["departments/department-primary-department/settings.json"]
+	if deptSettings.DepartmentSlug != "primary-department" {
+		t.Fatalf("expected department slug primary-department, got %q", deptSettings.DepartmentSlug)
+	}
+	if deptSettings.ResourceID != "dept-1" {
+		t.Fatalf("expected department resource id dept-1, got %q", deptSettings.ResourceID)
+	}
+
+	teamSettings := index["departments/department-primary-department/teams/team-primary-team/settings.json"]
+	if teamSettings.TeamSlug != "primary-team" {
+		t.Fatalf("expected team slug primary-team, got %q", teamSettings.TeamSlug)
+	}
+
+	projectSettings := index["projects/project-primary-project/settings.json"]
+	if projectSettings.ProjectSlug != "primary-project" {
+		t.Fatalf("expected project slug primary-project, got %q", projectSettings.ProjectSlug)
+	}
+	if projectSettings.ResourceName != "Primary Project" {
+		t.Fatalf("expected project resource name Primary Project, got %q", projectSettings.ResourceName)
+	}
+
+	projectTree := index["projects/project-primary-project/tree"]
+	if projectTree.LogicalType != "project_tree" || projectTree.NodeKind != NodeKindDirectory {
+		t.Fatalf("unexpected project tree node: %#v", projectTree)
+	}
+
+	projectChildren := index["projects/project-primary-project/children"]
+	if projectChildren.LogicalType != "project_children" || projectChildren.NodeKind != NodeKindDirectory {
+		t.Fatalf("unexpected project children node: %#v", projectChildren)
+	}
+
+	hierarchyFolder := index["projects/project-primary-project/children/folder-design"]
+	if hierarchyFolder.LogicalType != "hierarchy_folder" || hierarchyFolder.ProjectSlug != "primary-project" {
+		t.Fatalf("unexpected hierarchy folder node: %#v", hierarchyFolder)
+	}
+
+	hierarchyFolderACL := index["projects/project-primary-project/children/folder-design/acl.json"]
+	if hierarchyFolderACL.LogicalType != "hierarchy_folder" || hierarchyFolderACL.FileRole != "acl" {
+		t.Fatalf("unexpected hierarchy folder acl classification: %#v", hierarchyFolderACL)
+	}
+
+	childProjectSettings := index["projects/project-primary-project/children/folder-design/children/project-web/settings.json"]
+	if childProjectSettings.LogicalType != "project" || childProjectSettings.ProjectSlug != "web" {
+		t.Fatalf("unexpected child project classification: %#v", childProjectSettings)
+	}
+
+	treeFolder := index["projects/project-primary-project/tree/folder-docs"]
+	if treeFolder.LogicalType != "hierarchy_folder" || treeFolder.ProjectSlug != "primary-project" {
+		t.Fatalf("unexpected tree folder node: %#v", treeFolder)
+	}
+
+	treeFolderACL := index["projects/project-primary-project/tree/folder-docs/folder.json"]
+	if treeFolderACL.LogicalType != "hierarchy_folder" || treeFolderACL.FileRole != "folder" {
+		t.Fatalf("unexpected tree folder file classification: %#v", treeFolderACL)
+	}
+
+	treeItem := index["projects/project-primary-project/tree/folder-docs/item-roadmap/item.json"]
+	if treeItem.LogicalType != "item" || treeItem.FileRole != "item" {
+		t.Fatalf("unexpected tree item classification: %#v", treeItem)
+	}
+	if treeItem.ResourceSlug != "roadmap" {
+		t.Fatalf("expected tree item resource slug roadmap, got %#v", treeItem.ResourceSlug)
+	}
+
+	usersData := index["users/data.json"]
+	if usersData.LogicalType != "users" || usersData.FileRole != "data" {
+		t.Fatalf("unexpected users data classification: %#v", usersData)
+	}
+	if usersData.Checksum == "" || usersData.SizeBytes == 0 {
+		t.Fatalf("expected users/data.json checksum and size to be populated: %#v", usersData)
+	}
+}
+
+func mustMkdirAll(t *testing.T, path string) {
+	t.Helper()
+	if err := os.MkdirAll(path, 0o755); err != nil {
+		t.Fatalf("MkdirAll(%q) error = %v", path, err)
+	}
+}
+
+func mustWriteJSON(t *testing.T, path string, payload any) {
+	t.Helper()
+	bytes, err := json.MarshalIndent(payload, "", "  ")
+	if err != nil {
+		t.Fatalf("MarshalIndent(%q) error = %v", path, err)
+	}
+	bytes = append(bytes, '\n')
+	if err := os.WriteFile(path, bytes, 0o644); err != nil {
+		t.Fatalf("WriteFile(%q) error = %v", path, err)
+	}
+}

Commands/Local/Dev/backend.just

@@ -9,18 +9,22 @@ migrate-up:
 migrate-down:
 	cd '{{backend_dir}}' && go run ./cmd/migrate down
 
-# Reset all embedded database migrations and reapply from scratch.
+# Reset all embedded database migrations.
 migrate-reset:
 	cd '{{backend_dir}}' && go run ./cmd/migrate reset
 
+# Reset embedded database migrations and apply them again from scratch.
+migrate-rebuild:
+	cd '{{backend_dir}}' && go run ./cmd/migrate reset && go run ./cmd/migrate up
+
 # Show the embedded database migration status.
 migrate-status:
 	cd '{{backend_dir}}' && go run ./cmd/migrate status
 
+# Rebuild the POSIX-to-DB projection from the current POSIX root.
+posix-rebuild:
+	cd '{{backend_dir}}' && go run ./cmd/posix rebuild
+
 # Format backend Go source files.
 fmt:
 	cd '{{backend_dir}}' && gofmt -w ./cmd ./db ./internal
-
-# Run backend test suite.
-test:
-	cd '{{backend_dir}}' && go test ./...

Commands/Test/backend.just

@@ -0,0 +1,11 @@
+project_root := justfile_directory()
+backend_dir := project_root + "/Backend"
+
+# Run the full backend test suite.
+[default]
+all:
+	cd '{{backend_dir}}' && go test ./...
+
+# Run the isolated POSIX bootstrap smoke test.
+posix-bootstrap:
+	cd '{{backend_dir}}' && go test ./internal/bootstrap -run TestEnsureBootstrapPOSIXSkeletonInitializesEmptyRoot -count=1 -v

Commands/Test/mod.just

@@ -0,0 +1 @@
+mod backend

Docker/docker-compose.local.dev.yaml

@@ -6,6 +6,7 @@ x-backend-service: &backend-service
   environment:
     DATABASE_URL: postgres://moku:moku_dev_password@postgres:5432/moku?sslmode=disable
     VALKEY_URL: redis://valkey:6379/0
+    POSIX_ROOT: /posix
   depends_on:
     postgres:
       condition: service_healthy
@@ -13,6 +14,7 @@ x-backend-service: &backend-service
       condition: service_healthy
   volumes:
     - ../Backend:/app
+    - ../POSIX:/posix
     - moku_work_backend_go_pkg:/go/pkg/mod
     - moku_work_backend_go_build:/root/.cache/go-build
 

Docker/docker-compose.local.prod.yaml

@@ -5,11 +5,14 @@ x-backend-service: &backend-service
   environment:
     DATABASE_URL: postgres://moku:moku_dev_password@postgres:5432/moku?sslmode=disable
     VALKEY_URL: redis://valkey:6379/0
+    POSIX_ROOT: /posix
   depends_on:
     postgres:
       condition: service_healthy
     valkey:
       condition: service_healthy
+  volumes:
+    - ../POSIX:/posix
 
 services:
   postgres:

Documentation/POSIX-Structure.md

@@ -0,0 +1,75 @@
+# POSIX Structure
+
+[Filetree Link](https://tree.nathanfriend.com/?s=(%27optiUs!(%27fancy!Yue~fullPath!fbq~YailingSlash!Yue~rootDot!fbq)~R(%27R%27PJ%20or%20OrganizatiU%20%7Bqrver%7DM*46layout6cNlog7packs7*pack37A2*enYies75W5A_standbUe7WA6HwH30LZ2teamw5teamGL5Z6FwF30LKTC058T5C7XFG5LXKXTXC7XI7I05QG5BN2*8QG5BN6Z04_dN_pJw*pJGlayout2L*KI70%27)~vEiU!%271%27)*%20%200M52_*3-%3Cslug%3E4qttings5**69M*7%2F08VG*V259.jsUA5manifestBQ25*schema25*dCchildrenEersFprojectG305HdepartmentI*YeeJEUbKhome2L*42M%5CnNataQitemRsource!Tacl2UonVfolderW*app37X55YtrZusE_90balqsews0%01wqb_ZYXWVUTRQNMLKJIHGFECBA987654320*)
+
+``` markdown
+Personal or Organization (server)/
+├── settings.json
+├── layout.json
+├── catalog/
+│   ├── packs/
+│   │   └── pack-<slug>/
+│   │       ├── manifest.json
+│   │       └── entries/
+│   │           └── app-<slug>/
+│   │               └── manifest.json
+│   └── standalone/
+│       └── app-<slug>/
+│           └── manifest.json
+├── departments/
+│   └── department-<slug>/
+│       ├── settings.json
+│       ├── users.json
+│       └── teams/
+│           └── team-<slug>/
+│               ├── settings.json
+│               └── users.json
+├── projects/
+│   └── project-<slug>/
+│       ├── settings.json
+│       ├── home.json
+│       ├── acl.json
+│       ├── children/
+│       │   └── folder-<slug>/
+│       │       ├── folder.json
+│       │       ├── acl.json
+│       │       └── children/
+│       │           └── project-<slug>/
+│       │               ├── settings.json
+│       │               ├── home.json
+│       │               ├── acl.json
+│       │               ├── children/
+│       │               └── tree/
+│       └── tree/
+│           ├── item-<slug>/
+│           │   ├── item.json
+│           │   ├── schema.json
+│           │   └── data.json
+│           └── folder-<slug>/
+│               ├── folder.json
+│               └── item-<slug>/
+│                   ├── item.json
+│                   ├── schema.json
+│                   └── data.json
+└── users/
+    ├── settings.json
+    ├── data.json
+    └── personals/
+        └── personal-<slug>/
+            ├── layout.json
+            ├── settings.json
+            ├── home.json
+            └── tree/
+```
+
+## File Responsibilities
+
+- `settings.json` — Metadata and presentation config for the thing, such as display name, icon, description, and simple settings.
+- `layout.json` — Layout configuration for the current server or personal space.
+- `home.json` — Home surface configuration, such as widgets, sections, and how they are arranged.
+- `folder.json` — Metadata for a folder node in a tree.
+- `item.json` — Instance metadata for a created item, including what it is and how it should behave.
+- `schema.json` — The structure expected by that item's data.
+- `data.json` — The actual content or state data for that item.
+- `manifest.json` — Catalog definition metadata, including versioning, description, and capabilities for reusable apps or entries.
+- `users.json` — User membership or assignment data for departments and teams.

Documentation/TODO.md

@@ -4,87 +4,149 @@
 
 ### Version 0.1.0
 
-**Goal:** Barebone frontend with a real backend core.
+**Goal:** Finish the base application shell, auth, and platform foundations.
 
-#### Architecture
+#### Architecture and Delivery
 
-- [ ] Project-Structure
-- [ ] Stack-Decisions
-- [ ] Proxy
-  - [ ] Local-Prod-NGINX-Proxy
-  - [ ] Static-Frontend-Serving
-- [ ] First-Request-Web-Loader
-  - [ ] Bootstrap-Document
-  - [ ] Route-Intent-Handoff
-  - [ ] Tiny-First-Paint-Budget
-- [ ] Dev-and-Prod-Builds
+- [x] Project-Structure
+- [x] Stack-Decisions
+- [x] Proxy
+  - [x] Local-Dev-Vite-Proxy
+  - [x] Local-Prod-NGINX-Proxy
+- [x] First-Request-Web-Loader
+  - [x] Bootstrap-Document
+  - [x] Route-Intent-Handoff
+  - [x] Tiny-First-Paint-Budget
+- [x] Dev-and-Prod-Builds
   - [x] Local-Dev-Just-Commands
   - [x] Local-Dev-Docker-Compose
-  - [ ] Local-Prod-Just-Commands
-  - [ ] Local-Prod-Docker-Compose
-  - [ ] Frontend-Production-Dockerfile
-  - [ ] Frontend-docker-bake
+  - [x] Local-Prod-Just-Commands
+  - [x] Local-Prod-Docker-Compose
+  - [x] Frontend-Production-Dockerfile
+  - [x] Frontend-docker-bake
 
-#### Backend
+#### Backend — Done Foundations
+
+- [x] Bootstrap-Persistence
+  - [x] Installation-Step
+  - [x] Mode-Step
+  - [x] Admin-Step
+  - [x] Structure-Step
+  - [x] Bootstrap-State-Authority
+  - [x] Development-Bootstrap-Reset
+- [x] Base-Schema
+  - [x] Installations
+  - [x] Users
+  - [x] User-Homes
+  - [x] Organizations
+  - [x] Departments
+  - [x] Teams
+  - [x] Projects
+  - [x] Workspaces
+  - [x] Membership-Tables
+- [x] App-Shell-Read-API
+  - [x] App-Shell-State-Endpoint
+  - [x] Bootstrap-Read-Endpoints
+  - [x] Shell-Tree-Hydration
+- [x] Web-Route-Scaffolds
+  - [x] Session-Endpoint-Scaffold
+  - [x] Bootstrap-Endpoint-Scaffold
+  - [x] Current-User-Endpoint-Scaffold
+
+#### Backend — Remaining for 0.1.0
 
 - [ ] Auth
   - [ ] Session-Flow
   - [ ] Login-Logout-Foundation
   - [ ] Authentication
-- [ ] User
-  - [ ] Base-Model
+- [ ] Current-User-Implementation
+- [ ] POSIX-Lite-File-Persistence-Foundation
+  - [ ] Mounted-Storage-Root-Config
+  - [ ] Project-Folder-Creation-On-Backend
+  - [ ] moku.project.json
+  - [ ] Item-Folder-Creation
+  - [ ] item.json
+  - [ ] schema.json
+  - [ ] data.json
+  - [ ] DB-To-Files-Write-Flow
+- [ ] User-and-Workspace-Domain-Readiness
   - [ ] Base-Workspace
-    - [ ] Folders-and-Subfolders
   - [ ] Boards
   - [ ] Dashboard
-- [ ] Organization
-  - [ ] Base-Model
-  - [ ] Access-Rules-and-Membership
-- [ ] Workspace
-  - [ ] Folders-and-Subfolders
 - [ ] API
+  - [ ] Real-Organizations-Read-Endpoint
+  - [ ] Real-Workspaces-Read-Endpoint
+  - [ ] Tree-Mutation-Endpoints
+  - [ ] Project-Creation-Endpoint
 
-#### Frontend
+#### Frontend — Done Foundations
 
 - [x] Foundation
 - [x] Typography
 - [x] Icons
-- [ ] App Shell
+- [x] App-Shell
+  - [x] Left-Rail
+  - [x] Top-Bar
+  - [x] Server-Dock
+  - [x] Department-Selector
+  - [x] Theme-Toggle
+  - [x] Notifications-Menu
+  - [x] Profile-Menu
+- [x] Responsive-Shell
+  - [x] Collapsible-Shell
+  - [x] Mobile-Bottom-Nav
+  - [x] Mobile-Workspace-Browser
+  - [x] Mobile-Workspace-Views
+- [x] Context-Menus
+  - [x] Workspace-Context-Menu
+  - [x] Project-Context-Menu
+- [x] Bootstrap-Workspace-Home
+  - [x] Bootstrap-Wizard
+  - [x] Bootstrap-Step-Submission
+  - [x] App-Shell-Reload-After-Bootstrap
+- [x] Project-Menu
+  - [x] Folders-and-Subfolders
+  - [x] Rooted-From-Department
+  - [x] Long-Press-Drag-and-Drop
+- [x] Workspace-Tree
+  - [x] Folders-and-Subfolders
+  - [x] Long-Press-Drag-and-Drop
+- [x] App-Shell-Hydration
+
+#### Frontend — Remaining for 0.1.0
+
 - [ ] Primitives
   - [ ] Button
   - [ ] IconButton
   - [ ] Input
   - [ ] Surface
-- [ ] Nav-Bar
 - [ ] Workspace-Switching
-- [ ] Workspace-Home
+- [ ] Real-Workspace-Home
+- [ ] Real-Workspace-Tree-Hydration
+- [ ] Create-Project-Flow
+- [ ] Persist-Tree-Mutations
+- [ ] Connect-Tree-Interactions-To-Backend-Data
 
 ### Version 0.2.0
 
-**Goal:** First real work surface.
-
-- [ ] Table
-- [ ] CVA
-- [ ] Storyboard
-- [ ] Theme-System
-  - [ ] Theme-Registry
-  - [ ] Built-In-Theme-Presets
-  - [ ] Active-Theme-Persistence
-  - [ ] Theme-Switcher
-  - [ ] Theme-JSON-Upload
-  - [ ] Theme-JSON-Import-Validation
-  - [ ] Community-Theme-Readiness
+**Goal:** Build the plugin app system on top of the base platform. And core app plugins like calendar, board, docs and text channels
 
 ### Version 0.3.0
 
-**Goal:** Documents and system hardening.
-
-- [ ] Document
-- [ ] Accessibility-Rules
-- [ ] Motion-Foundation
+**Goal:** Communications and Collaboration (Email System, Reminder System, and Live Collaboration on Documents)
 
 ### Version 0.4.0
 
-- [ ] Gantt-Board
-- [ ] Calendar
-- [ ] Timeline
+**Goal:** Introduce the POSIX-based file system drive direction with OnlyOffice + S3 blob storage + Per File Versioning
+
+### Version 0.5.0
+
+**Goal:** File Sharing and Per File Permissions
+
+### Version 0.6.0
+
+**Goal:** Git as a core plugin
+
+### Version 0.7.0
+
+**Goal:** Full Automation System (Extensive)

Env/.env.example

@@ -10,6 +10,7 @@ BACKEND_SHUTDOWN_TIMEOUT=10s
 
 DATABASE_URL=postgres://moku:moku_dev_password@localhost:5432/moku?sslmode=disable
 VALKEY_URL=redis://localhost:6379/0
+POSIX_ROOT=../POSIX
 
 VITE_API_BASE_URL=/v1
 

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

@@ -1,3 +1,5 @@
+@use "../shared/tree-nav" as treeNav;
+
 .root {
   display: grid;
   --project-drawer-gap: var(--space-3);
@@ -191,142 +193,126 @@
 }
 
 .treeSectionLabel {
-  @include text-caption;
-  margin: 0 0 var(--space-2);
+	@include treeNav.section-label;
+  margin: 0;
   padding: 0 var(--space-3);
-  color: var(--color-text-subtle);
-  text-transform: uppercase;
-  letter-spacing: 0.04em;
 }
 
-.treeList {
-  list-style: none;
-  display: grid;
-  gap: var(--space-1);
-  padding: 0;
-}
-
-.treeEmptySlot {
-	min-height: calc(var(--control-size-lg) - var(--space-2));
-	padding-left: calc(var(--space-3) + (var(--tree-depth, 0) * var(--space-4)));
-	border-radius: var(--radius-lg);
-	border: 1px dashed color-mix(in srgb, var(--color-border) 38%, transparent);
-	opacity: 0.35;
-}
-
-.treeInputRow {
-	width: 100%;
-	min-width: 0;
-	display: grid;
-	grid-template-columns: auto minmax(0, 1fr);
+.treeSectionHeader {
+	display: flex;
 	align-items: center;
+	justify-content: space-between;
 	gap: var(--space-2);
-	min-height: calc(var(--control-size-lg) - var(--space-2));
-	padding: var(--space-2) var(--space-3);
-	padding-left: calc(var(--space-3) + (var(--tree-depth, 0) * var(--space-4)));
-	border: 1px solid color-mix(in srgb, var(--color-border) 42%, transparent);
-	border-radius: var(--radius-lg);
-	background: color-mix(in srgb, var(--color-surface) 94%, transparent);
+	margin-bottom: var(--space-2);
+	padding-right: var(--space-1);
 }
 
-.treeInput {
-	width: 100%;
-	min-width: 0;
-	border: 0;
-	background: transparent;
+.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);
-	font: inherit;
 	outline: none;
 }
 
-.treeInput::placeholder {
-	color: var(--color-text-muted);
+.treeControlButton:disabled {
+	opacity: 0.45;
+	cursor: default;
+}
+
+.treeList {
+	@include treeNav.tree-list;
+}
+
+.treeEmptySlot {
+	@include treeNav.empty-slot;
+}
+
+.treeInputRow {
+	@include treeNav.input-row;
+}
+
+.treeInput {
+	@include treeNav.input;
 }
 
 .treeItem {
-  width: 100%;
-  min-width: 0;
-  display: grid;
-  grid-template-columns: auto auto minmax(0, 1fr) auto;
-  align-items: center;
-  gap: var(--space-2);
-  min-height: calc(var(--control-size-lg) - var(--space-2));
-  padding: var(--space-2) var(--space-3);
-  padding-left: calc(var(--space-3) + (var(--tree-depth, 0) * var(--space-4)));
-  border: 1px solid transparent;
-  border-radius: var(--radius-lg);
-  background: transparent;
-  color: var(--color-text-muted);
-  transition:
-    background 160ms var(--easing-standard),
-    color 160ms var(--easing-standard),
-    border-color 160ms var(--easing-standard),
-    box-shadow 160ms var(--easing-standard),
-    transform 180ms var(--easing-standard);
-  text-align: left;
+	@include treeNav.item;
 }
 
 .treeItem:hover,
 .treeItem:focus-visible {
-  background: color-mix(in srgb, var(--color-surface-hover) 80%, var(--color-accent-soft) 20%);
-  color: var(--color-text);
-  box-shadow: inset 0 1px 0 color-mix(in srgb, white 4%, transparent);
+	@include treeNav.item-hover;
 }
 
 .treeItemFolder {
-  color: var(--color-text);
+	@include treeNav.item-folder;
 }
 
 .treeItemDragging {
-	opacity: 0.45;
-	transform: scale(0.985);
-	box-shadow: none;
+	@include treeNav.item-dragging;
 }
 
 .treeItemDropBefore {
-	box-shadow: inset 0 2px 0 color-mix(in srgb, var(--color-accent-strong) 78%, transparent);
+	@include treeNav.item-drop-before;
 }
 
 .treeItemDropAfter {
-	box-shadow: inset 0 -2px 0 color-mix(in srgb, var(--color-accent-strong) 78%, transparent);
+	@include treeNav.item-drop-after;
 }
 
 .treeItemDropInside {
-	border-color: color-mix(in srgb, var(--color-accent-strong) 55%, transparent);
-	background: color-mix(in srgb, var(--color-accent-soft) 36%, var(--color-surface));
-	color: var(--color-text);
-	box-shadow: inset 0 1px 0 color-mix(in srgb, white 4%, transparent);
+	@include treeNav.item-drop-inside;
 }
 
 .folderChevron {
-  color: var(--color-text-muted);
-  transition: transform 160ms var(--easing-standard);
+	@include treeNav.folder-chevron;
 }
 
 .folderChevronOpen {
-  transform: rotate(90deg);
+	@include treeNav.folder-chevron-open;
 }
 
 .treeItemActive {
-  border-color: var(--color-border);
-  background: var(--color-surface);
-  color: var(--color-text);
-  box-shadow: inset 0 1px 0 color-mix(in srgb, white 4%, transparent);
+	@include treeNav.item-active;
 }
 
 .icon {
-  color: inherit;
-  opacity: 0.85;
+	@include treeNav.icon;
 }
 
 .label {
-  @include text-label;
-  min-width: 0;
+	@include treeNav.label;
 }
 
 .itemMeta {
-  @include text-caption;
-  color: var(--color-text-muted);
+	@include treeNav.item-meta;
 }
 
 @media (max-width: 720px) {

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

@@ -1,9 +1,21 @@
 // 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 {
+	collectBranchNodeIds,
+	findTreeNodeDepth,
+	findTreeNodeLocation,
+	getPointerRelativeY,
+	isUuidString,
+	moveTreeNode,
+	resolveTreeDropTarget,
+	type NavTreeAdapter,
+	type NavTreeDropTarget,
+} from "../shared/navTreeDnd";
 import {
 	createProjectFolderTarget,
 	createProjectSurfaceTarget,
@@ -36,244 +48,70 @@ 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;
 };
 
-type ProjectDragTarget = {
-	parentId: string | null;
-	index: number;
-	intent: "before" | "after" | "inside";
-	targetNodeId?: string;
-};
+type ProjectDragTarget = NavTreeDropTarget;
 
 type ProjectDragState = {
 	draggedNodeId: string;
 	dropTarget: ProjectDragTarget | null;
 };
 
-type ProjectNodeLocation = {
-	parentId: string | null;
-	index: number;
-	node: ProjectTreeNode;
-};
-
 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 cloneProjectTreeNode = (node: ProjectTreeNode): ProjectTreeNode => {
-	if (node.kind === "project") {
-		return {
-			kind: "project",
-			item: { ...node.item },
-		};
-	}
+const buildProjectTree = (
+	items: readonly ProjectItem[],
+	folders: readonly PersistedProjectFolderRecord[] = [],
+): ProjectTreeNode[] => [
+	...items.map((item) => ({
+		kind: "project" as const,
+		item,
+	})),
+	...buildPersistedFolderNodes(folders),
+];
 
-	return {
-		kind: "folder",
-		id: node.id,
-		label: node.label,
-		meta: node.meta,
-		children: node.children.map(cloneProjectTreeNode),
-	};
-};
+const readPersistedFolders = (body: ProjectFoldersResponse): PersistedProjectFolderRecord[] =>
+	Array.isArray(body.data?.folders) ? body.data.folders : [];
 
-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 {
+const projectTreeAdapter: NavTreeAdapter<ProjectTreeNode> = {
+	getNodeId: getProjectTreeNodeId,
+	isBranchNode: (node) => node.kind === "folder",
+	getChildren: (node) => (node.kind === "folder" ? node.children : []),
+	withChildren: (node, children) =>
+		node.kind === "folder"
+			? {
 				...node,
-				children: [...node.children, folder],
-			};
+				children: [...children],
 			}
-
-		return {
-			...node,
-			children: insertProjectFolderNode(node.children, parentId, folder),
-		};
-	});
-};
-
-const findProjectNodeLocation = (
-	nodes: readonly ProjectTreeNode[],
-	nodeId: string,
-	parentId: string | null = null,
-): ProjectNodeLocation | null => {
-	for (let index = 0; index < nodes.length; index += 1) {
-		const node = nodes[index];
-
-		if (getProjectTreeNodeId(node) === nodeId) {
-			return { parentId, index, node };
-		}
-
-		if (node.kind === "folder") {
-			const nestedLocation = findProjectNodeLocation(node.children, nodeId, node.id);
-
-			if (nestedLocation) {
-				return nestedLocation;
-			}
-		}
-	}
-
-	return null;
-};
-
-const findProjectNodeDepth = (nodes: readonly ProjectTreeNode[], nodeId: string, depth = 0): number | null => {
-	for (const node of nodes) {
-		if (getProjectTreeNodeId(node) === nodeId) {
-			return depth;
-		}
-
-		if (node.kind === "folder") {
-			const nestedDepth = findProjectNodeDepth(node.children, nodeId, depth + 1);
-
-			if (nestedDepth !== null) {
-				return nestedDepth;
-			}
-		}
-	}
-
-	return null;
-};
-
-const projectTreeContainsNode = (nodes: readonly ProjectTreeNode[], nodeId: string): boolean => {
-	for (const node of nodes) {
-		if (getProjectTreeNodeId(node) === nodeId) {
-			return true;
-		}
-
-		if (node.kind === "folder" && projectTreeContainsNode(node.children, nodeId)) {
-			return true;
-		}
-	}
-
-	return false;
-};
-
-const removeProjectTreeNode = (
-	nodes: readonly ProjectTreeNode[],
-	nodeId: string,
-): { nodes: ProjectTreeNode[]; removed: ProjectTreeNode | null } => {
-	const nextNodes: ProjectTreeNode[] = [];
-	let removed: ProjectTreeNode | null = null;
-
-	for (const node of nodes) {
-		if (getProjectTreeNodeId(node) === nodeId) {
-			removed = node;
-			continue;
-		}
-
-		if (node.kind === "folder") {
-			const result = removeProjectTreeNode(node.children, nodeId);
-
-			if (result.removed) {
-				removed = result.removed;
-				nextNodes.push({
-					...node,
-					children: result.nodes,
-				});
-				continue;
-			}
-		}
-
-		nextNodes.push(node);
-	}
-
-	return { nodes: nextNodes, removed };
-};
-
-const insertProjectTreeNode = (
-	nodes: readonly ProjectTreeNode[],
-	parentId: string | null,
-	index: number,
-	nodeToInsert: ProjectTreeNode,
-): ProjectTreeNode[] => {
-	if (parentId === null) {
-		const nextNodes = [...nodes];
-		nextNodes.splice(Math.max(0, Math.min(index, nextNodes.length)), 0, nodeToInsert);
-		return nextNodes;
-	}
-
-	return nodes.map((node) => {
-		if (node.kind !== "folder") {
-			return node;
-		}
-
-		if (node.id === parentId) {
-			const nextChildren = [...node.children];
-			nextChildren.splice(Math.max(0, Math.min(index, nextChildren.length)), 0, nodeToInsert);
-			return {
-				...node,
-				children: nextChildren,
-			};
-		}
-
-		return {
-			...node,
-			children: insertProjectTreeNode(node.children, parentId, index, nodeToInsert),
-		};
-	});
-};
-
-const moveProjectTreeNode = (
-	nodes: readonly ProjectTreeNode[],
-	draggedNodeId: string,
-	dropTarget: ProjectDragTarget,
-): ProjectTreeNode[] => {
-	const location = findProjectNodeLocation(nodes, draggedNodeId);
-
-	if (!location) {
-		return [...nodes];
-	}
-
-	if (
-		location.node.kind === "folder" &&
-		dropTarget.parentId !== null &&
-		(projectTreeContainsNode(location.node.children, dropTarget.parentId) || dropTarget.parentId === location.node.id)
-	) {
-		return [...nodes];
-	}
-
-	let normalizedIndex = dropTarget.index;
-
-	if (dropTarget.parentId === location.parentId && dropTarget.index > location.index) {
-		normalizedIndex -= 1;
-	}
-
-	if (dropTarget.parentId === location.parentId && normalizedIndex === location.index) {
-		return [...nodes];
-	}
-
-	const removalResult = removeProjectTreeNode(nodes, draggedNodeId);
-
-	if (!removalResult.removed) {
-		return [...nodes];
-	}
-
-	return insertProjectTreeNode(removalResult.nodes, dropTarget.parentId, normalizedIndex, removalResult.removed);
+			: node,
 };
 
 const ProjectFolderDraftRow = (props: {
@@ -336,6 +174,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}>
@@ -374,7 +213,7 @@ const ProjectFolderBranch = (props: {
 								style={{ "--tree-depth": String(props.depth) }}
 								aria-expanded={!isCollapsed()}
 								onClick={() => {
-									if (props.dragState || suppressNextTreeClick()) {
+									if (props.dragState || props.isTreeClickSuppressed()) {
 										return;
 									}
 
@@ -404,7 +243,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 +262,7 @@ const ProjectFolderBranch = (props: {
 									onSubmitPendingFolder={props.onSubmitPendingFolder}
 									onCancelPendingFolder={props.onCancelPendingFolder}
 									dragState={props.dragState}
+									isTreeClickSuppressed={props.isTreeClickSuppressed}
 								/>
 							</Show>
 						</li>
@@ -442,7 +282,7 @@ const ProjectFolderBranch = (props: {
 							}}
 							style={{ "--tree-depth": String(props.depth) }}
 							onClick={(): void => {
-								if (props.dragState || suppressNextTreeClick()) {
+								if (props.dragState || props.isTreeClickSuppressed()) {
 									return;
 								}
 
@@ -485,8 +325,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 +338,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 +370,116 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 		);
 	};
 
+	const syncProjectTree = (): void => {
+		const nextTree = buildProjectTree(appShellData.projectItems(), persistedFolders());
+		const availableFolderIds = new Set(collectBranchNodeIds(nextTree, projectTreeAdapter));
+
+		setProjectTreeNodes(nextTree);
+		setCollapsedFolderIds((current) => current.filter((folderId) => availableFolderIds.has(folderId)));
+	};
+
+	const resetProjectTreeInteractionState = (): void => {
+		setCollapsedFolderIds([]);
+		setPendingFolderDraft(null);
+		setPendingFolderName("");
+		setDragState(null);
+	};
+
+	const folderIds = (): string[] => collectBranchNodeIds(projectTreeNodes(), projectTreeAdapter);
+
+	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;
+		}
+
+		if (!isUuidString(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(() => {
@@ -597,7 +540,7 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 
 			suppressTreeClickTemporarily();
 			setProjectTreeNodes((current) =>
-				moveProjectTreeNode(current, nextDragState.draggedNodeId, nextDragState.dropTarget as ProjectDragTarget),
+				moveTreeNode(current, nextDragState.draggedNodeId, nextDragState.dropTarget as ProjectDragTarget, projectTreeAdapter),
 			);
 			setDragState(null);
 		};
@@ -649,7 +592,7 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 	};
 
 	const selectProject = (projectId: string): void => {
-		const location = findProjectNodeLocation(projectTreeNodes(), projectId);
+		const location = findTreeNodeLocation(projectTreeNodes(), projectId, projectTreeAdapter);
 
 		if (!location || location.node.kind !== "project") {
 			return;
@@ -668,9 +611,10 @@ 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();
+		const projectId = selectedProject().id;
 
 		if (!draft) {
 			return;
@@ -682,16 +626,66 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 			return;
 		}
 
-		setProjectTreeNodes((current) =>
-			insertProjectFolderNode(current, draft.parentId, {
-				kind: "folder",
-				id: createProjectFolderId(),
-				label: name,
-				children: [],
+		if (!isUuidString(projectId)) {
+			cancelPendingFolder();
+			return;
+		}
+
+		try {
+			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/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 deletePersistedFolder = async (folderId: string): Promise<void> => {
+		const projectId = selectedProject().id;
+		if (!folderId || !isUuidString(projectId)) {
+			return;
+		}
+
+		try {
+			const response = await fetch(
+				`${resolveAPIBase()}/projects/${projectId}/folders?folderId=${encodeURIComponent(folderId)}`,
+				{
+					method: "DELETE",
+					headers: {
+						Accept: "application/json",
+					},
+				},
+			);
+
+			const body = (await response.json()) as ProjectFoldersResponse;
+
+			if (!response.ok) {
+				throw new Error(body.message || "Failed to delete project folder.");
+			}
+
+			setPersistedFolders(readPersistedFolders(body));
+			setCollapsedFolderIds((current) => current.filter((id) => id !== folderId));
+		} catch (error) {
+			console.error(error);
+		}
 	};
 
 	const cancelPendingFolder = (): void => {
@@ -700,23 +694,30 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 	};
 
 	const handleContextActionSelect = (action: { id: string; label: string }, target: ProjectMenuTarget): void => {
-		if (action.id !== "new-folder") {
-			return;
-		}
-
+		switch (action.id) {
+			case "new-folder":
 				switch (target.kind) {
 					case "surface":
 						beginFolderDraft(null, 0);
 						return;
 					case "folder":
-				beginFolderDraft(target.id, (findProjectNodeDepth(projectTreeNodes(), target.id) ?? 0) + 1);
+						beginFolderDraft(target.id, (findTreeNodeDepth(projectTreeNodes(), target.id, projectTreeAdapter) ?? 0) + 1);
 						return;
 					case "project": {
-				const parentId = findProjectNodeLocation(projectTreeNodes(), target.id)?.parentId ?? null;
-				beginFolderDraft(parentId, parentId ? (findProjectNodeDepth(projectTreeNodes(), parentId) ?? 0) + 1 : 0);
+						const parentId = findTreeNodeLocation(projectTreeNodes(), target.id, projectTreeAdapter)?.parentId ?? null;
+						beginFolderDraft(parentId, parentId ? (findTreeNodeDepth(projectTreeNodes(), parentId, projectTreeAdapter) ?? 0) + 1 : 0);
 						return;
 					}
 				}
+				return;
+			case "delete-folder":
+				if (target.kind === "folder") {
+					void deletePersistedFolder(target.id);
+				}
+				return;
+			default:
+				return;
+		}
 	};
 
 	const handleSurfaceContextMenu = (event: MouseEvent): void => {
@@ -724,6 +725,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,45 +756,20 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 			return;
 		}
 
-		const bounds = event.currentTarget.getBoundingClientRect();
-		const relativeY = bounds.height <= 0 ? 0.5 : (event.clientY - bounds.top) / bounds.height;
-		let nextTarget: ProjectDragTarget;
-
-		if (node.kind === "folder") {
-			if (relativeY < 0.28) {
-				nextTarget = {
-					parentId,
-					index,
-					intent: "before",
-					targetNodeId: node.id,
-				};
-			} else if (relativeY > 0.72) {
-				nextTarget = {
-					parentId,
-					index: index + 1,
-					intent: "after",
-					targetNodeId: node.id,
-				};
-			} else {
-				nextTarget = {
-					parentId: node.id,
-					index: node.children.length,
-					intent: "inside",
-					targetNodeId: node.id,
-				};
-			}
-		} else {
-			nextTarget = {
-				parentId,
-				index: relativeY < 0.5 ? index : index + 1,
-				intent: relativeY < 0.5 ? "before" : "after",
-				targetNodeId: node.item.id,
-			};
+		const relativeY = getPointerRelativeY(event);
+		if (relativeY === null) {
+			return;
 		}
 
 		setDragState({
 			...nextDragState,
-			dropTarget: nextTarget,
+			dropTarget: resolveTreeDropTarget({
+				parentId,
+				index,
+				node,
+				relativeY,
+				adapter: projectTreeAdapter,
+			}),
 		});
 	};
 
@@ -861,10 +840,30 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 						onContextMenu={handleSurfaceContextMenu}
 					>
 						<div class={styles.drawerBody}>
+							<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()}
 								depth={0}
@@ -889,6 +888,7 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 								onSubmitPendingFolder={submitPendingFolder}
 								onCancelPendingFolder={cancelPendingFolder}
 								dragState={dragState()}
+								isTreeClickSuppressed={suppressNextTreeClick}
 							/>
 						</div>
 					</div>

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

@@ -1,3 +1,5 @@
+@use "../shared/tree-nav" as treeNav;
+
 .sidebar {
   --sidebar-nav-item-min-height: var(--control-size-lg);
   position: relative;
@@ -117,56 +119,25 @@
 }
 
 .treeSectionLabel {
-  @include text-caption;
+	@include treeNav.section-label;
   margin: var(--space-3) 0 var(--space-2);
   padding: 0 var(--space-3);
-  color: var(--color-text-subtle);
-  text-transform: uppercase;
-  letter-spacing: 0.04em;
 }
 
 .treeList {
-  list-style: none;
-  display: grid;
-  gap: var(--space-1);
-  padding: 0;
+	@include treeNav.tree-list;
 }
 
 .treeEmptySlot {
-	min-height: calc(var(--control-size-lg) - var(--space-2));
-	padding-left: calc(var(--space-3) + (var(--tree-depth, 0) * var(--space-4)));
-	border-radius: var(--radius-lg);
-	border: 1px dashed color-mix(in srgb, var(--color-border) 38%, transparent);
-	opacity: 0.35;
+	@include treeNav.empty-slot;
 }
 
 .treeInputRow {
-	width: 100%;
-	min-width: 0;
-	display: grid;
-	grid-template-columns: auto minmax(0, 1fr);
-	align-items: center;
-	gap: var(--space-2);
-	min-height: calc(var(--control-size-lg) - var(--space-2));
-	padding: var(--space-2) var(--space-3);
-	padding-left: calc(var(--space-3) + (var(--tree-depth, 0) * var(--space-4)));
-	border: 1px solid color-mix(in srgb, var(--color-border) 42%, transparent);
-	border-radius: var(--radius-lg);
-	background: color-mix(in srgb, var(--color-surface) 94%, transparent);
+	@include treeNav.input-row;
 }
 
 .treeInput {
-	width: 100%;
-	min-width: 0;
-	border: 0;
-	background: transparent;
-	color: var(--color-text);
-	font: inherit;
-	outline: none;
-}
-
-.treeInput::placeholder {
-	color: var(--color-text-muted);
+	@include treeNav.input;
 }
 
 .navItem {
@@ -184,74 +155,44 @@
 }
 
 .treeItem {
-  width: 100%;
-  min-width: 0;
-  display: grid;
-  grid-template-columns: auto auto minmax(0, 1fr) auto;
-  align-items: center;
-  gap: var(--space-2);
-  min-height: calc(var(--control-size-lg) - var(--space-2));
-  padding: var(--space-2) var(--space-3);
-  padding-left: calc(var(--space-3) + (var(--tree-depth, 0) * var(--space-4)));
-  border: 1px solid transparent;
-  border-radius: var(--radius-lg);
-  background: transparent;
-  color: var(--color-text-muted);
-  text-align: left;
-  transition:
-    background 160ms var(--easing-standard),
-    color 160ms var(--easing-standard),
-    border-color 160ms var(--easing-standard),
-    box-shadow 160ms var(--easing-standard),
-    transform 180ms var(--easing-standard);
+	@include treeNav.item;
 }
 
 .treeItem:hover,
 .treeItem:focus-visible {
-  background: color-mix(in srgb, var(--color-surface-hover) 80%, var(--color-accent-soft) 20%);
-  color: var(--color-text);
-  box-shadow: inset 0 1px 0 color-mix(in srgb, white 4%, transparent);
+	@include treeNav.item-hover;
 }
 
 .treeItemFolder {
-  color: var(--color-text);
+	@include treeNav.item-folder;
 }
 
 .treeItemDragging {
-	opacity: 0.45;
-	transform: scale(0.985);
-	box-shadow: none;
+	@include treeNav.item-dragging;
 }
 
 .treeItemDropBefore {
-	box-shadow: inset 0 2px 0 color-mix(in srgb, var(--color-accent-strong) 78%, transparent);
+	@include treeNav.item-drop-before;
 }
 
 .treeItemDropAfter {
-	box-shadow: inset 0 -2px 0 color-mix(in srgb, var(--color-accent-strong) 78%, transparent);
+	@include treeNav.item-drop-after;
 }
 
 .treeItemDropInside {
-	border-color: color-mix(in srgb, var(--color-accent-strong) 55%, transparent);
-	background: color-mix(in srgb, var(--color-accent-soft) 36%, var(--color-surface));
-	color: var(--color-text);
-	box-shadow: inset 0 1px 0 color-mix(in srgb, white 4%, transparent);
+	@include treeNav.item-drop-inside;
 }
 
 .folderChevron {
-  color: var(--color-text-muted);
-  transition: transform 160ms var(--easing-standard);
+	@include treeNav.folder-chevron;
 }
 
 .folderChevronOpen {
-  transform: rotate(90deg);
+	@include treeNav.folder-chevron-open;
 }
 
 .treeItemActive {
-  border-color: var(--color-border);
-  background: var(--color-surface);
-  color: var(--color-text);
-  box-shadow: inset 0 1px 0 color-mix(in srgb, white 4%, transparent);
+	@include treeNav.item-active;
 }
 
 .navItemActive {
@@ -262,18 +203,15 @@
 }
 
 .icon {
-  color: inherit;
-  opacity: 0.85;
+	@include treeNav.icon;
 }
 
 .label {
-  @include text-label;
-  min-width: 0;
+	@include treeNav.label;
 }
 
 .itemMeta {
-  @include text-caption;
-  color: var(--color-text-muted);
+	@include treeNav.item-meta;
 }
 
 .sidebarCollapsed {

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

@@ -1,9 +1,20 @@
 // Path: Frontend/src/components/shell/WorkspaceSidebar/WorkspaceSidebar.tsx
 
 import { For, Show, createEffect, createSignal, onCleanup, onMount, type JSX } from "solid-js";
-import { ChevronLeft, ChevronRight, Folder } from "../../../lib/icons";
+import { resolveAPIBase } from "../../../lib/api";
+import { ChevronLeft, ChevronRight, Folder, ListCollapse, UnfoldVertical } from "../../../lib/icons";
 import { useAppShellData } from "../data/app-shell.context";
 import { ProjectSelector } from "../ProjectSelector/ProjectSelector";
+import {
+	collectBranchNodeIds,
+	findTreeNodeDepth,
+	getPointerRelativeY,
+	isUuidString,
+	moveTreeNode,
+	resolveTreeDropTarget,
+	type NavTreeAdapter,
+	type NavTreeDropTarget,
+} from "../shared/navTreeDnd";
 import {
 	createWorkspaceStaticTarget,
 	createWorkspaceSurfaceTarget,
@@ -31,217 +42,56 @@ type PendingWorkspaceFolderDraft = {
 	depth: number;
 };
 
-type WorkspaceDragTarget = {
-	parentId: string | null;
-	index: number;
-	intent: "before" | "after" | "inside";
-	targetNodeId?: string;
-};
+type WorkspaceDragTarget = NavTreeDropTarget;
 
 type WorkspaceDragState = {
 	draggedNodeId: string;
 	dropTarget: WorkspaceDragTarget | null;
 };
 
-type WorkspaceNodeLocation = {
-	parentId: string | null;
-	index: number;
-	node: WorkspaceTreeNode;
+type PersistedWorkspaceFolderRecord = {
+	id: string;
+	label: string;
+	children?: PersistedWorkspaceFolderRecord[];
+};
+
+type WorkspaceFoldersResponse = {
+	data?: {
+		folders?: PersistedWorkspaceFolderRecord[];
+	};
+	error?: string;
+	message?: string;
 };
 
 const LONG_PRESS_MS = 320;
 
-const createWorkspaceFolderId = (): string => `folder-${Math.random().toString(36).slice(2, 10)}`;
-
 const getWorkspaceTreeNodeId = (node: WorkspaceTreeNode): string => node.id;
 
-const insertWorkspaceFolderNode = (
-	nodes: readonly WorkspaceTreeNode[],
-	parentId: string | null,
-	folder: WorkspaceTreeNode,
-): readonly WorkspaceTreeNode[] => {
-	if (parentId === null) {
-		return [...nodes, folder];
-	}
+const buildPersistedWorkspaceFolderNodes = (
+	folders: readonly PersistedWorkspaceFolderRecord[],
+): WorkspaceTreeNode[] =>
+	folders.map((folder) => ({
+		id: folder.id,
+		label: folder.label,
+		kind: "folder",
+		icon: Folder,
+		children: buildPersistedWorkspaceFolderNodes(folder.children ?? []),
+	}));
 
-	return nodes.map((node) => {
-		if (node.kind !== "folder") {
-			return node;
-		}
+const readPersistedWorkspaceFolders = (body: WorkspaceFoldersResponse): PersistedWorkspaceFolderRecord[] =>
+	Array.isArray(body.data?.folders) ? body.data.folders : [];
 
-		if (node.id === parentId) {
-			return {
+const workspaceTreeAdapter: NavTreeAdapter<WorkspaceTreeNode> = {
+	getNodeId: getWorkspaceTreeNodeId,
+	isBranchNode: (node) => node.kind === "folder",
+	getChildren: (node) => (node.kind === "folder" ? (node.children ?? []) : []),
+	withChildren: (node, children) =>
+		node.kind === "folder"
+			? {
 				...node,
-				children: [...(node.children ?? []), folder],
-			};
+				children: [...children],
 			}
-
-		return {
-			...node,
-			children: node.children ? insertWorkspaceFolderNode(node.children, parentId, folder) : node.children,
-		};
-	});
-};
-
-const findWorkspaceFolderDepth = (nodes: readonly WorkspaceTreeNode[], folderId: string, depth = 0): number | null => {
-	for (const node of nodes) {
-		if (node.kind !== "folder") {
-			continue;
-		}
-
-		if (node.id === folderId) {
-			return depth;
-		}
-
-		const nestedDepth = node.children ? findWorkspaceFolderDepth(node.children, folderId, depth + 1) : null;
-		if (nestedDepth !== null) {
-			return nestedDepth;
-		}
-	}
-
-	return null;
-};
-
-const findWorkspaceNodeLocation = (
-	nodes: readonly WorkspaceTreeNode[],
-	nodeId: string,
-	parentId: string | null = null,
-): WorkspaceNodeLocation | null => {
-	for (let index = 0; index < nodes.length; index += 1) {
-		const node = nodes[index];
-
-		if (node.id === nodeId) {
-			return { parentId, index, node };
-		}
-
-		if (node.kind === "folder" && node.children) {
-			const nestedLocation = findWorkspaceNodeLocation(node.children, nodeId, node.id);
-
-			if (nestedLocation) {
-				return nestedLocation;
-			}
-		}
-	}
-
-	return null;
-};
-
-const workspaceTreeContainsNode = (nodes: readonly WorkspaceTreeNode[], nodeId: string): boolean => {
-	for (const node of nodes) {
-		if (node.id === nodeId) {
-			return true;
-		}
-
-		if (node.kind === "folder" && node.children && workspaceTreeContainsNode(node.children, nodeId)) {
-			return true;
-		}
-	}
-
-	return false;
-};
-
-const removeWorkspaceTreeNode = (
-	nodes: readonly WorkspaceTreeNode[],
-	nodeId: string,
-): { nodes: WorkspaceTreeNode[]; removed: WorkspaceTreeNode | null } => {
-	const nextNodes: WorkspaceTreeNode[] = [];
-	let removed: WorkspaceTreeNode | null = null;
-
-	for (const node of nodes) {
-		if (node.id === nodeId) {
-			removed = node;
-			continue;
-		}
-
-		if (node.kind === "folder" && node.children) {
-			const result = removeWorkspaceTreeNode(node.children, nodeId);
-
-			if (result.removed) {
-				removed = result.removed;
-				nextNodes.push({
-					...node,
-					children: result.nodes,
-				});
-				continue;
-			}
-		}
-
-		nextNodes.push(node);
-	}
-
-	return { nodes: nextNodes, removed };
-};
-
-const insertWorkspaceTreeNode = (
-	nodes: readonly WorkspaceTreeNode[],
-	parentId: string | null,
-	index: number,
-	nodeToInsert: WorkspaceTreeNode,
-): WorkspaceTreeNode[] => {
-	if (parentId === null) {
-		const nextNodes = [...nodes];
-		nextNodes.splice(Math.max(0, Math.min(index, nextNodes.length)), 0, nodeToInsert);
-		return nextNodes;
-	}
-
-	return nodes.map((node) => {
-		if (node.kind !== "folder") {
-			return node;
-		}
-
-		if (node.id === parentId) {
-			const nextChildren = [...(node.children ?? [])];
-			nextChildren.splice(Math.max(0, Math.min(index, nextChildren.length)), 0, nodeToInsert);
-			return {
-				...node,
-				children: nextChildren,
-			};
-		}
-
-		return {
-			...node,
-			children: node.children ? insertWorkspaceTreeNode(node.children, parentId, index, nodeToInsert) : node.children,
-		};
-	});
-};
-
-const moveWorkspaceTreeNode = (
-	nodes: readonly WorkspaceTreeNode[],
-	draggedNodeId: string,
-	dropTarget: WorkspaceDragTarget,
-): WorkspaceTreeNode[] => {
-	const location = findWorkspaceNodeLocation(nodes, draggedNodeId);
-
-	if (!location) {
-		return [...nodes];
-	}
-
-	if (
-		location.node.kind === "folder" &&
-		dropTarget.parentId !== null &&
-		((location.node.children && workspaceTreeContainsNode(location.node.children, dropTarget.parentId)) ||
-			dropTarget.parentId === location.node.id)
-	) {
-		return [...nodes];
-	}
-
-	let normalizedIndex = dropTarget.index;
-
-	if (dropTarget.parentId === location.parentId && dropTarget.index > location.index) {
-		normalizedIndex -= 1;
-	}
-
-	if (dropTarget.parentId === location.parentId && normalizedIndex === location.index) {
-		return [...nodes];
-	}
-
-	const removalResult = removeWorkspaceTreeNode(nodes, draggedNodeId);
-
-	if (!removalResult.removed) {
-		return [...nodes];
-	}
-
-	return insertWorkspaceTreeNode(removalResult.nodes, dropTarget.parentId, normalizedIndex, removalResult.removed);
+			: node,
 };
 
 const FolderDraftRow = (props: {
@@ -292,10 +142,6 @@ const WorkspaceHomeEntry = (props: {
 	item: WorkspaceStaticItem;
 	onOpenContextMenu: (event: MouseEvent, target: WorkspaceContextMenuTarget) => void;
 	onOpenContextMenuFromKeyboard: (element: HTMLElement, target: WorkspaceContextMenuTarget) => void;
-	onNodePointerDown: (event: PointerEvent, nodeId: string) => void;
-	onNodePointerMove: (event: PointerEvent, parentId: string | null, index: number, node: WorkspaceTreeNode) => void;
-	dragState: WorkspaceDragState | null;
-	isTreeClickSuppressed: () => boolean;
 }): JSX.Element => {
 	const Icon = props.item.icon;
 	const target = createWorkspaceStaticTarget(props.item);
@@ -350,6 +196,10 @@ const WorkspaceTreeBranch = (props: {
 	onCancelPendingFolder: () => void;
 	onOpenContextMenu: (event: MouseEvent, target: WorkspaceContextMenuTarget) => void;
 	onOpenContextMenuFromKeyboard: (element: HTMLElement, target: WorkspaceContextMenuTarget) => void;
+	onNodePointerDown: (event: PointerEvent, nodeId: string) => void;
+	onNodePointerMove: (event: PointerEvent, parentId: string | null, index: number, node: WorkspaceTreeNode) => void;
+	dragState: WorkspaceDragState | null;
+	isTreeClickSuppressed: () => boolean;
 }): JSX.Element => {
 	const depth = () => props.depth ?? 0;
 	const parentId = () => props.parentId ?? null;
@@ -485,24 +335,105 @@ const WorkspaceTreeBranch = (props: {
 
 export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 	const appShellData = useAppShellData();
+	const activeProject = () => appShellData.activeProject();
 	const [isProjectDrawerOpen, setIsProjectDrawerOpen] = createSignal(false);
 	const [workspaceTreeNodes, setWorkspaceTreeNodes] = createSignal<readonly WorkspaceTreeNode[]>(appShellData.workspaceTree());
+	const [persistedFolders, setPersistedFolders] = createSignal<readonly PersistedWorkspaceFolderRecord[]>([]);
 	const [collapsedFolderIds, setCollapsedFolderIds] = createSignal<readonly string[]>([]);
 	const [pendingFolderDraft, setPendingFolderDraft] = createSignal<PendingWorkspaceFolderDraft | null>(null);
 	const [pendingFolderName, setPendingFolderName] = createSignal("");
 	const [dragState, setDragState] = createSignal<WorkspaceDragState | null>(null);
 	const [suppressNextTreeClick, setSuppressNextTreeClick] = createSignal(false);
+	let lastSelectedProjectId: string | null = null;
+	let latestPersistedFoldersRequest = 0;
 	const contextMenu = createWorkspaceContextMenuController();
 	let longPressTimer: number | undefined;
 	let suppressClickTimer: number | undefined;
 	const railToggleLabel = (): string => (props.railCollapsed ? "Expand server rail" : "Collapse server rail");
 	const sidebarContextMenuTarget = createWorkspaceSurfaceTarget(appShellData.activeProject());
 	const isFolderCollapsed = (folderId: string): boolean => collapsedFolderIds().includes(folderId);
+	const folderIds = (): string[] => collectBranchNodeIds(workspaceTreeNodes(), workspaceTreeAdapter);
+	const totalFolderCount = (): number => folderIds().length;
+	const areAllFoldersCollapsed = (): boolean => {
+		const count = totalFolderCount();
+		return count > 0 && collapsedFolderIds().length >= count;
+	};
+	const workspaceFolderToggleLabel = (): string =>
+		areAllFoldersCollapsed() ? "Expand all folders" : "Collapse all folders";
 	const toggleFolder = (folderId: string): void => {
 		setCollapsedFolderIds((current) =>
 			current.includes(folderId) ? current.filter((id) => id !== folderId) : [...current, folderId],
 		);
 	};
+	const expandAllFolders = (): void => {
+		setCollapsedFolderIds([]);
+	};
+	const collapseAllFolders = (): void => {
+		setCollapsedFolderIds(folderIds());
+	};
+	const toggleAllFolders = (): void => {
+		if (areAllFoldersCollapsed()) {
+			expandAllFolders();
+			return;
+		}
+
+		collapseAllFolders();
+	};
+	const resetWorkspaceTreeInteractionState = (): void => {
+		setCollapsedFolderIds([]);
+		setPendingFolderDraft(null);
+		setPendingFolderName("");
+		setDragState(null);
+	};
+	const syncWorkspaceTree = (): void => {
+		const nextTree = activeProject()?.id
+			? buildPersistedWorkspaceFolderNodes(persistedFolders())
+			: appShellData.workspaceTree();
+		const availableFolderIds = new Set(collectBranchNodeIds(nextTree, workspaceTreeAdapter));
+
+		setWorkspaceTreeNodes(nextTree);
+		setCollapsedFolderIds((current) => current.filter((id) => availableFolderIds.has(id)));
+	};
+	const loadPersistedFolders = async (projectId: string): Promise<void> => {
+		const requestId = latestPersistedFoldersRequest + 1;
+		latestPersistedFoldersRequest = requestId;
+
+		if (!projectId) {
+			setPersistedFolders([]);
+			return;
+		}
+
+		if (!isUuidString(projectId)) {
+			setPersistedFolders([]);
+			return;
+		}
+
+		try {
+			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/tree/folders`, {
+				headers: {
+					Accept: "application/json",
+				},
+			});
+			const body = (await response.json()) as WorkspaceFoldersResponse;
+
+			if (requestId !== latestPersistedFoldersRequest) {
+				return;
+			}
+
+			if (!response.ok) {
+				throw new Error(body.message || "Failed to load project tree folders.");
+			}
+
+			setPersistedFolders(readPersistedWorkspaceFolders(body));
+		} catch (error) {
+			if (requestId !== latestPersistedFoldersRequest) {
+				return;
+			}
+
+			console.error(error);
+			setPersistedFolders([]);
+		}
+	};
 	const clearLongPressTimer = (): void => {
 		if (longPressTimer !== undefined) {
 			window.clearTimeout(longPressTimer);
@@ -523,11 +454,27 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 	};
 
 	createEffect(() => {
-		setWorkspaceTreeNodes(appShellData.workspaceTree());
-		setCollapsedFolderIds([]);
-		setPendingFolderDraft(null);
-		setPendingFolderName("");
-		setDragState(null);
+		syncWorkspaceTree();
+	});
+
+	createEffect(() => {
+		const projectId = activeProject()?.id ?? null;
+
+		if (lastSelectedProjectId === null) {
+			lastSelectedProjectId = projectId;
+			return;
+		}
+
+		if (projectId === lastSelectedProjectId) {
+			return;
+		}
+
+		lastSelectedProjectId = projectId;
+		resetWorkspaceTreeInteractionState();
+	});
+
+	createEffect(() => {
+		void loadPersistedFolders(activeProject()?.id ?? "");
 	});
 
 	onMount(() => {
@@ -546,7 +493,7 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 
 			suppressTreeClickTemporarily();
 			setWorkspaceTreeNodes((current) =>
-				moveWorkspaceTreeNode(current, nextDragState.draggedNodeId, nextDragState.dropTarget as WorkspaceDragTarget),
+				moveTreeNode(current, nextDragState.draggedNodeId, nextDragState.dropTarget as WorkspaceDragTarget, workspaceTreeAdapter),
 			);
 			setDragState(null);
 		};
@@ -587,9 +534,10 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 		setPendingFolderDraft({ parentId, depth });
 	};
 
-	const submitPendingFolder = (): void => {
+	const submitPendingFolder = async (): Promise<void> => {
 		const name = pendingFolderName().trim();
 		const draft = pendingFolderDraft();
+		const projectId = activeProject()?.id ?? "";
 
 		if (!draft) {
 			return;
@@ -601,17 +549,66 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 			return;
 		}
 
-		setWorkspaceTreeNodes((current) =>
-			insertWorkspaceFolderNode(current, draft.parentId, {
-				id: createWorkspaceFolderId(),
-				label: name,
-				kind: "folder",
-				icon: Folder,
-				children: [],
+		if (!projectId || !isUuidString(projectId)) {
+			cancelPendingFolder();
+			return;
+		}
+
+		try {
+			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/tree/folders`, {
+				method: "POST",
+				headers: {
+					Accept: "application/json",
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({
+					name,
+					parentFolderId: draft.parentId,
 				}),
-		);
+			});
+
+			const body = (await response.json()) as WorkspaceFoldersResponse;
+
+			if (!response.ok) {
+				throw new Error(body.message || "Failed to create project tree folder.");
+			}
+
+			setPersistedFolders(readPersistedWorkspaceFolders(body));
 			setPendingFolderDraft(null);
 			setPendingFolderName("");
+		} catch (error) {
+			console.error(error);
+		}
+	};
+
+	const deletePersistedFolder = async (folderId: string): Promise<void> => {
+		const projectId = activeProject()?.id ?? "";
+		if (!folderId || !projectId || !isUuidString(projectId)) {
+			return;
+		}
+
+		try {
+			const response = await fetch(
+				`${resolveAPIBase()}/projects/${projectId}/tree/folders?folderId=${encodeURIComponent(folderId)}`,
+				{
+					method: "DELETE",
+					headers: {
+						Accept: "application/json",
+					},
+				},
+			);
+
+			const body = (await response.json()) as WorkspaceFoldersResponse;
+
+			if (!response.ok) {
+				throw new Error(body.message || "Failed to delete project tree folder.");
+			}
+
+			setPersistedFolders(readPersistedWorkspaceFolders(body));
+			setCollapsedFolderIds((current) => current.filter((id) => id !== folderId));
+		} catch (error) {
+			console.error(error);
+		}
 	};
 
 	const cancelPendingFolder = (): void => {
@@ -619,6 +616,17 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 		setPendingFolderName("");
 	};
 
+	const handleHeaderActionClick = (actionId: string): void => {
+		switch (actionId) {
+			case "toggle-workspace-folders":
+				toggleAllFolders();
+				return;
+			case "search-workspace":
+			default:
+				return;
+		}
+	};
+
 	const handleNodePointerDown = (event: PointerEvent, nodeId: string): void => {
 		if (event.button !== 0 || pendingFolderDraft()) {
 			return;
@@ -643,52 +651,47 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 			return;
 		}
 
-		const bounds = event.currentTarget.getBoundingClientRect();
-		const relativeY = bounds.height <= 0 ? 0.5 : (event.clientY - bounds.top) / bounds.height;
-		let nextTarget: WorkspaceDragTarget;
-
-		if (node.kind === "folder") {
-			if (relativeY < 0.28) {
-				nextTarget = { parentId, index, intent: "before", targetNodeId: node.id };
-			} else if (relativeY > 0.72) {
-				nextTarget = { parentId, index: index + 1, intent: "after", targetNodeId: node.id };
-			} else {
-				nextTarget = {
-					parentId: node.id,
-					index: (node.children ?? []).length,
-					intent: "inside",
-					targetNodeId: node.id,
-				};
-			}
-		} else {
-			nextTarget = {
-				parentId,
-				index: relativeY < 0.5 ? index : index + 1,
-				intent: relativeY < 0.5 ? "before" : "after",
-				targetNodeId: node.id,
-			};
-		}
-
-		setDragState({ ...nextDragState, dropTarget: nextTarget });
-	};
-
-	const handleContextActionSelect = (action: WorkspaceContextMenuAction, target: WorkspaceContextMenuTarget): void => {
-		if (action.id !== "new-folder") {
+		const relativeY = getPointerRelativeY(event);
+		if (relativeY === null) {
 			return;
 		}
 
+		setDragState({
+			...nextDragState,
+			dropTarget: resolveTreeDropTarget({
+				parentId,
+				index,
+				node,
+				relativeY,
+				adapter: workspaceTreeAdapter,
+			}),
+		});
+	};
+
+	const handleContextActionSelect = (action: WorkspaceContextMenuAction, target: WorkspaceContextMenuTarget): void => {
+		switch (action.id) {
+			case "new-folder":
 				switch (target.kind) {
 					case "workspace":
 					case "home":
 						beginFolderDraft(null, 0);
 						return;
 					case "folder":
-				beginFolderDraft(target.id, (findWorkspaceFolderDepth(workspaceTreeNodes(), target.id) ?? 0) + 1);
+						beginFolderDraft(target.id, (findTreeNodeDepth(workspaceTreeNodes(), target.id, workspaceTreeAdapter) ?? 0) + 1);
 						return;
 					case "settings":
 					case "item":
 						return;
 				}
+				return;
+			case "delete-folder":
+				if (target.kind === "folder") {
+					void deletePersistedFolder(target.id);
+				}
+				return;
+			default:
+				return;
+		}
 	};
 
 	return (
@@ -731,10 +734,28 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 
 					<For each={workspaceSidebarHeaderActions}>
 						{(action): JSX.Element => {
-								const Icon = action.icon;
+							const label =
+								action.id === "toggle-workspace-folders"
+										? workspaceFolderToggleLabel()
+										: action.label;
+							const Icon =
+								action.id === "toggle-workspace-folders"
+										? areAllFoldersCollapsed()
+											? UnfoldVertical
+											: ListCollapse
+										: action.icon;
 
 							return (
-									<button type="button" class={styles.headerActionButton} aria-label={action.label} title={action.label} data-slot="workspace-sidebar-header-action" data-action-id={action.id}>
+								<button
+									type="button"
+									class={styles.headerActionButton}
+									aria-label={label}
+									title={label}
+									data-slot="workspace-sidebar-header-action"
+									data-action-id={action.id}
+									disabled={action.id === "toggle-workspace-folders" && totalFolderCount() === 0}
+									onClick={(): void => handleHeaderActionClick(action.id)}
+									>
 										<Icon size={16} strokeWidth={2} />
 									</button>
 								);

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

@@ -9,6 +9,7 @@ import {
 	Home,
 	Keyboard,
 	LayoutGrid,
+	ListCollapse,
 	LogOut,
 	Repeat,
 	Search,
@@ -476,6 +477,7 @@ export const workspaceTree: readonly WorkspaceTreeNode[] = [
 
 export const workspaceSidebarHeaderActions: readonly SidebarHeaderAction[] = [
 	{ id: "search-workspace", label: "Search workspace", icon: Search },
+	{ id: "toggle-workspace-folders", label: "Collapse all folders", icon: ListCollapse },
 ] as const;
 
 export const mobileBottomNavItems: readonly MobileBottomNavItem[] = [
@@ -595,6 +597,11 @@ const getProjectCreateActions = (): readonly ProjectContextMenuAction[] =>
 		{ id: "new-folder", label: "New folder" },
 	] as const;
 
+const getProjectFolderDangerActions = (): readonly ProjectContextMenuAction[] =>
+	[
+		{ id: "delete-folder", label: "Delete", shortcut: { modifiers: ["meta"], key: "delete" }, tone: "danger" },
+	] as const;
+
 export const createProjectSurfaceTarget = (label = "Projects"): ProjectMenuTarget => ({
 	id: "project-surface",
 	label,
@@ -641,6 +648,10 @@ export const getProjectContextMenuSections = (target: ProjectMenuTarget): readon
 					id: "create",
 					items: createActions,
 				},
+				{
+					id: "organize",
+					items: getProjectFolderDangerActions(),
+				},
 			] as const;
 		case "project":
 			return [

Frontend/src/components/shell/shared/_tree-nav.scss

@@ -0,0 +1,188 @@
+@use "../../../styles/tools/mixins" as *;
+
+@mixin section-label {
+	@include text-caption;
+	color: var(--color-text-subtle);
+	text-transform: uppercase;
+	letter-spacing: 0.04em;
+}
+
+@mixin tree-list {
+	list-style: none;
+	display: grid;
+	gap: var(--space-1);
+	padding: 0;
+}
+
+@mixin empty-slot {
+	min-height: calc(var(--control-size-lg) - var(--space-2));
+	padding-left: calc(var(--space-3) + (var(--tree-depth, 0) * var(--space-4)));
+	border-radius: var(--radius-lg);
+	border: 1px dashed color-mix(in srgb, var(--color-border) 38%, transparent);
+	opacity: 0.35;
+}
+
+@mixin input-row {
+	width: 100%;
+	min-width: 0;
+	display: grid;
+	grid-template-columns: auto minmax(0, 1fr);
+	align-items: center;
+	gap: var(--space-2);
+	min-height: calc(var(--control-size-lg) - var(--space-2));
+	padding: var(--space-2) var(--space-3);
+	padding-left: calc(var(--space-3) + (var(--tree-depth, 0) * var(--space-4)));
+	border: 1px solid color-mix(in srgb, var(--color-border) 42%, transparent);
+	border-radius: var(--radius-lg);
+	background: color-mix(in srgb, var(--color-surface) 94%, transparent);
+}
+
+@mixin input {
+	width: 100%;
+	min-width: 0;
+	border: 0;
+	background: transparent;
+	color: var(--color-text);
+	font: inherit;
+	outline: none;
+
+	&::placeholder {
+		color: var(--color-text-muted);
+	}
+}
+
+@mixin item {
+	width: 100%;
+	min-width: 0;
+	display: grid;
+	position: relative;
+	isolation: isolate;
+	grid-template-columns: auto auto minmax(0, 1fr) auto;
+	align-items: center;
+	gap: var(--space-2);
+	min-height: calc(var(--control-size-lg) - var(--space-2));
+	padding: var(--space-2) var(--space-3);
+	padding-left: calc(var(--space-3) + (var(--tree-depth, 0) * var(--space-4)));
+	border: 0;
+	border-radius: 0;
+	background: transparent;
+	color: var(--color-text-muted);
+	text-align: left;
+	transition:
+		color 160ms var(--easing-standard),
+		box-shadow 160ms var(--easing-standard),
+		transform 180ms var(--easing-standard);
+
+	&::after {
+		content: "";
+		position: absolute;
+		inset: 0;
+		border: 1px solid transparent;
+		border-radius: var(--radius-lg);
+		background: transparent;
+		transition:
+			background 160ms var(--easing-standard),
+			border-color 160ms var(--easing-standard),
+			box-shadow 160ms var(--easing-standard);
+		pointer-events: none;
+		z-index: 0;
+	}
+
+	> * {
+		position: relative;
+		z-index: 1;
+	}
+}
+
+@mixin item-hover {
+	color: var(--color-text);
+
+	&::after {
+		background: color-mix(in srgb, var(--color-surface-hover) 80%, var(--color-accent-soft) 20%);
+		box-shadow: inset 0 1px 0 color-mix(in srgb, white 4%, transparent);
+	}
+}
+
+@mixin item-folder {
+	color: var(--color-text);
+}
+
+@mixin item-dragging {
+	opacity: 0.45;
+	transform: scale(0.985);
+	box-shadow: none;
+}
+
+@mixin item-drop-before {
+	&::before {
+		content: "";
+		position: absolute;
+		left: calc(var(--space-3) + (var(--tree-depth, 0) * var(--space-4)));
+		right: var(--space-3);
+		top: calc((var(--space-1) * -0.5) - 1px);
+		height: 2px;
+		border-radius: 999px;
+		background: color-mix(in srgb, var(--color-accent-strong) 78%, transparent);
+		pointer-events: none;
+		z-index: 2;
+	}
+}
+
+@mixin item-drop-after {
+	&::before {
+		content: "";
+		position: absolute;
+		left: calc(var(--space-3) + (var(--tree-depth, 0) * var(--space-4)));
+		right: var(--space-3);
+		bottom: calc((var(--space-1) * -0.5) - 1px);
+		height: 2px;
+		border-radius: 999px;
+		background: color-mix(in srgb, var(--color-accent-strong) 78%, transparent);
+		pointer-events: none;
+		z-index: 2;
+	}
+}
+
+@mixin item-drop-inside {
+	color: var(--color-text);
+
+	&::after {
+		border-color: color-mix(in srgb, var(--color-accent-strong) 55%, transparent);
+		background: color-mix(in srgb, var(--color-accent-soft) 36%, var(--color-surface));
+		box-shadow: inset 0 1px 0 color-mix(in srgb, white 4%, transparent);
+	}
+}
+
+@mixin folder-chevron {
+	color: var(--color-text-muted);
+	transition: transform 160ms var(--easing-standard);
+}
+
+@mixin folder-chevron-open {
+	transform: rotate(90deg);
+}
+
+@mixin item-active {
+	color: var(--color-text);
+
+	&::after {
+		border-color: var(--color-border);
+		background: var(--color-surface);
+		box-shadow: inset 0 1px 0 color-mix(in srgb, white 4%, transparent);
+	}
+}
+
+@mixin icon {
+	color: inherit;
+	opacity: 0.85;
+}
+
+@mixin label {
+	@include text-label;
+	min-width: 0;
+}
+
+@mixin item-meta {
+	@include text-caption;
+	color: var(--color-text-muted);
+}

Frontend/src/components/shell/shared/navTreeDnd.ts

@@ -0,0 +1,278 @@
+export type NavTreeDropIntent = "before" | "after" | "inside";
+
+export type NavTreeDropTarget = {
+	parentId: string | null;
+	index: number;
+	intent: NavTreeDropIntent;
+	targetNodeId?: string;
+};
+
+export type NavTreeDragState = {
+	draggedNodeId: string;
+	dropTarget: NavTreeDropTarget | null;
+};
+
+export type NavTreeLocation<TNode> = {
+	parentId: string | null;
+	index: number;
+	node: TNode;
+};
+
+export type NavTreeAdapter<TNode> = {
+	getNodeId: (node: TNode) => string;
+	isBranchNode: (node: TNode) => boolean;
+	getChildren: (node: TNode) => readonly TNode[];
+	withChildren: (node: TNode, children: readonly TNode[]) => TNode;
+};
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export const isUuidString = (value: string | null | undefined): boolean => {
+	if (typeof value !== "string") {
+		return false;
+	}
+
+	return UUID_PATTERN.test(value.trim());
+};
+
+export const collectBranchNodeIds = <TNode>(
+	nodes: readonly TNode[],
+	adapter: NavTreeAdapter<TNode>,
+): string[] => {
+	const ids: string[] = [];
+
+	for (const node of nodes) {
+		if (!adapter.isBranchNode(node)) {
+			continue;
+		}
+
+		ids.push(adapter.getNodeId(node));
+		ids.push(...collectBranchNodeIds(adapter.getChildren(node), adapter));
+	}
+
+	return ids;
+};
+
+export const findTreeNodeLocation = <TNode>(
+	nodes: readonly TNode[],
+	nodeId: string,
+	adapter: NavTreeAdapter<TNode>,
+	parentId: string | null = null,
+): NavTreeLocation<TNode> | null => {
+	for (let index = 0; index < nodes.length; index += 1) {
+		const node = nodes[index];
+
+		if (adapter.getNodeId(node) === nodeId) {
+			return { parentId, index, node };
+		}
+
+		if (!adapter.isBranchNode(node)) {
+			continue;
+		}
+
+		const nestedLocation = findTreeNodeLocation(adapter.getChildren(node), nodeId, adapter, adapter.getNodeId(node));
+		if (nestedLocation) {
+			return nestedLocation;
+		}
+	}
+
+	return null;
+};
+
+export const findTreeNodeDepth = <TNode>(
+	nodes: readonly TNode[],
+	nodeId: string,
+	adapter: NavTreeAdapter<TNode>,
+	depth = 0,
+): number | null => {
+	for (const node of nodes) {
+		if (adapter.getNodeId(node) === nodeId) {
+			return depth;
+		}
+
+		if (!adapter.isBranchNode(node)) {
+			continue;
+		}
+
+		const nestedDepth = findTreeNodeDepth(adapter.getChildren(node), nodeId, adapter, depth + 1);
+		if (nestedDepth !== null) {
+			return nestedDepth;
+		}
+	}
+
+	return null;
+};
+
+export const treeContainsNode = <TNode>(
+	nodes: readonly TNode[],
+	nodeId: string,
+	adapter: NavTreeAdapter<TNode>,
+): boolean => {
+	for (const node of nodes) {
+		if (adapter.getNodeId(node) === nodeId) {
+			return true;
+		}
+
+		if (adapter.isBranchNode(node) && treeContainsNode(adapter.getChildren(node), nodeId, adapter)) {
+			return true;
+		}
+	}
+
+	return false;
+};
+
+export const removeTreeNode = <TNode>(
+	nodes: readonly TNode[],
+	nodeId: string,
+	adapter: NavTreeAdapter<TNode>,
+): { nodes: TNode[]; removed: TNode | null } => {
+	const nextNodes: TNode[] = [];
+	let removed: TNode | null = null;
+
+	for (const node of nodes) {
+		if (adapter.getNodeId(node) === nodeId) {
+			removed = node;
+			continue;
+		}
+
+		if (adapter.isBranchNode(node)) {
+			const result = removeTreeNode(adapter.getChildren(node), nodeId, adapter);
+
+			if (result.removed) {
+				removed = result.removed;
+				nextNodes.push(adapter.withChildren(node, result.nodes));
+				continue;
+			}
+		}
+
+		nextNodes.push(node);
+	}
+
+	return { nodes: nextNodes, removed };
+};
+
+export const insertTreeNode = <TNode>(
+	nodes: readonly TNode[],
+	parentId: string | null,
+	index: number,
+	nodeToInsert: TNode,
+	adapter: NavTreeAdapter<TNode>,
+): TNode[] => {
+	if (parentId === null) {
+		const nextNodes = [...nodes];
+		nextNodes.splice(Math.max(0, Math.min(index, nextNodes.length)), 0, nodeToInsert);
+		return nextNodes;
+	}
+
+	return nodes.map((node) => {
+		if (!adapter.isBranchNode(node)) {
+			return node;
+		}
+
+		if (adapter.getNodeId(node) === parentId) {
+			const nextChildren = [...adapter.getChildren(node)];
+			nextChildren.splice(Math.max(0, Math.min(index, nextChildren.length)), 0, nodeToInsert);
+			return adapter.withChildren(node, nextChildren);
+		}
+
+		return adapter.withChildren(node, insertTreeNode(adapter.getChildren(node), parentId, index, nodeToInsert, adapter));
+	});
+};
+
+export const moveTreeNode = <TNode>(
+	nodes: readonly TNode[],
+	draggedNodeId: string,
+	dropTarget: NavTreeDropTarget,
+	adapter: NavTreeAdapter<TNode>,
+): TNode[] => {
+	const location = findTreeNodeLocation(nodes, draggedNodeId, adapter);
+
+	if (!location) {
+		return [...nodes];
+	}
+
+	if (
+		adapter.isBranchNode(location.node) &&
+		dropTarget.parentId !== null &&
+		(treeContainsNode(adapter.getChildren(location.node), dropTarget.parentId, adapter) ||
+			dropTarget.parentId === adapter.getNodeId(location.node))
+	) {
+		return [...nodes];
+	}
+
+	let normalizedIndex = dropTarget.index;
+	if (dropTarget.parentId === location.parentId && dropTarget.index > location.index) {
+		normalizedIndex -= 1;
+	}
+
+	if (dropTarget.parentId === location.parentId && normalizedIndex === location.index) {
+		return [...nodes];
+	}
+
+	const removalResult = removeTreeNode(nodes, draggedNodeId, adapter);
+	if (!removalResult.removed) {
+		return [...nodes];
+	}
+
+	return insertTreeNode(removalResult.nodes, dropTarget.parentId, normalizedIndex, removalResult.removed, adapter);
+};
+
+export const getPointerRelativeY = (event: PointerEvent): number | null => {
+	const currentTarget = event.currentTarget;
+	if (!(currentTarget instanceof HTMLElement)) {
+		return null;
+	}
+
+	const bounds = currentTarget.getBoundingClientRect();
+	return bounds.height <= 0 ? 0.5 : (event.clientY - bounds.top) / bounds.height;
+};
+
+export const resolveTreeDropTarget = <TNode>(params: {
+	parentId: string | null;
+	index: number;
+	node: TNode;
+	relativeY: number;
+	adapter: NavTreeAdapter<TNode>;
+	beforeThreshold?: number;
+	beforeThresholdFirstSibling?: number;
+	afterThreshold?: number;
+}): NavTreeDropTarget => {
+	const {
+		parentId,
+		index,
+		node,
+		relativeY,
+		adapter,
+		beforeThreshold = 0.28,
+		beforeThresholdFirstSibling = 0.42,
+		afterThreshold = 0.72,
+	} = params;
+
+	const targetNodeId = adapter.getNodeId(node);
+
+	if (adapter.isBranchNode(node)) {
+		const nextBeforeThreshold = index === 0 ? beforeThresholdFirstSibling : beforeThreshold;
+
+		if (relativeY < nextBeforeThreshold) {
+			return { parentId, index, intent: "before", targetNodeId };
+		}
+
+		if (relativeY > afterThreshold) {
+			return { parentId, index: index + 1, intent: "after", targetNodeId };
+		}
+
+		return {
+			parentId: targetNodeId,
+			index: adapter.getChildren(node).length,
+			intent: "inside",
+			targetNodeId,
+		};
+	}
+
+	return {
+		parentId,
+		index: relativeY < 0.5 ? index : index + 1,
+		intent: relativeY < 0.5 ? "before" : "after",
+		targetNodeId,
+	};
+};

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";

Justfile

@@ -1,6 +1,7 @@
 set shell := ["bash", "-cu"]
 
 mod local "Commands/Local"
+mod test "Commands/Test"
 
 [default]
 help: