Skip to main content

​
Overview

Terra’s folder system lets you organize forms into logical groups—by program, department, or any structure that fits your workflow. Drag and drop forms between folders for quick reorganization.
Folders are workspace-wide. All team members see the same folder structure.

​
Creating Folders

  1. Navigate to the Forms page
  2. Click the + button in the folder sidebar
  3. Enter a folder name (e.g., “Housing Connector”)
  4. Choose a color for visual identification
  5. Click Create Folder
Create folder dialog

​
Moving Forms to Folders

​
Drag and Drop

The fastest way to organize forms:
  1. Hover over a form row to reveal the drag handle (⋮⋮)
  2. Drag the form to the target folder in the sidebar
  3. Drop to complete the move
You can drag forms to “Uncategorized” to remove them from a folder.

​
Bulk Organization

For large-scale reorganization, consider:
  • Creating folders first based on your program structure
  • Filtering by “Uncategorized” to see unorganized forms
  • Dragging related forms to their folders in batches

​
Folder Views

​
All Forms

Shows every form in your workspace regardless of folder. Use this view to see your complete form inventory.

​
Uncategorized

Forms that haven’t been assigned to any folder. New forms start here by default.

​
Custom Folders

Click any folder to filter the view to only forms in that folder. The form count badge updates in real-time.

​
Managing Folders

​
Rename a Folder

  1. Hover over the folder in the sidebar
  2. Click the ⋯ menu
  3. Select Rename
  4. Update the name and/or color
  5. Click Save Changes

​
Delete a Folder

  1. Hover over the folder in the sidebar
  2. Click the ⋯ menu
  3. Select Delete
  4. Confirm deletion
Deleting a folder moves all contained forms to “Uncategorized”. Forms are never deleted when removing a folder.

​
Folder Colors

Choose from 8 colors to visually distinguish folders:
ColorHexSuggested Use
Indigo#6366F1Default / General
Blue#3B82F6Active programs
Emerald#10B981Approved / Complete
Amber#F59E0BNeeds attention
Rose#F43F5EUrgent / Priority
Purple#A855F7Special programs
Slate#64748BArchive / Inactive
Cyan#06B6D4Pilot programs

​
Best Practices

Create one folder per program (e.g., “Housing Connector”, “Emergency Rental Assistance”, “Utility Assistance”). This maps to how most government teams think about their work.
Establish naming conventions early. Consider prefixes like department codes (e.g., “HSD - Housing”, “HSD - Utilities”) for large organizations.
Create an “Archive” or “Inactive” folder for programs that are no longer accepting applications but need to be preserved for record-keeping.
Terra uses a flat folder structure (no nested folders) intentionally. This keeps navigation simple and prevents organizational complexity.

​
Technical Reference

​
Database Schema

-- Folders table
CREATE TABLE folders (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL,
  color TEXT DEFAULT '#6366F1',
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Foreign key on forms table
ALTER TABLE forms 
ADD COLUMN folder_id UUID REFERENCES folders(id) ON DELETE SET NULL;

​
Server Actions

ActionDescriptionParameters
getFolders()Fetch all folders with form counts—
createFolder(name, color)Create a new foldername: string, color?: string
updateFolder(id, updates)Update folder name/colorid: string, updates: { name?, color? }
deleteFolder(id)Delete folder (unlinks forms)id: string
moveFormToFolder(formId, folderId)Move form to folderformId: string, folderId: string | null

​
Component Architecture

app/(dashboard)/forms/
├── page.tsx          # Server component, fetches forms + folders
├── client.tsx        # DndContext provider, split view layout
└── ...

components/dashboard/
└── folder-sidebar.tsx  # Droppable folder list, CRUD dialogs

​
Drag and Drop

Terra uses @dnd-kit/core for drag-and-drop:
  • Draggable: Form rows in the table (useDraggable)
  • Droppable: Folder items in the sidebar (useDroppable)
  • Sensors: Mouse (8px activation) and Touch (200ms delay)
// Draggable form row
const { attributes, listeners, setNodeRef, isDragging } = useDraggable({
  id: form.id,
  data: { form },
});

// Droppable folder item
const { setNodeRef, isOver } = useDroppable({
  id: folderId ?? "uncategorized",
});

​
Troubleshooting

The drag handle appears on hover. Ensure you’re hovering over the form row, not just the form name link.
Folder counts update optimistically. If counts seem wrong, refresh the page to sync with the database.
Ensure you have appropriate permissions. The delete action unlinks all forms first, which requires write access to the forms table.