feat: add folders (#1711)

packages/lib/server-only/document/create-document-v2.ts

@@ -233,6 +233,7 @@ export const createDocumentV2 = async ({
         documentMeta: true,
         recipients: true,
         fields: true,
+        folder: true,
       },
     });
 

packages/lib/server-only/document/create-document.ts

@@ -1,5 +1,5 @@
 import { DocumentSource, WebhookTriggerEvents } from '@prisma/client';
-import type { Team, TeamGlobalSettings } from '@prisma/client';
+import type { DocumentVisibility, Team, TeamGlobalSettings } from '@prisma/client';
 import { TeamMemberRole } from '@prisma/client';
 
 import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
@@ -29,6 +29,7 @@ export type CreateDocumentOptions = {
   normalizePdf?: boolean;
   timezone?: string;
   requestMetadata: ApiRequestMetadata;
+  folderId?: string;
 };
 
 export const createDocument = async ({
@@ -41,6 +42,7 @@ export const createDocument = async ({
   formValues,
   requestMetadata,
   timezone,
+  folderId,
 }: CreateDocumentOptions) => {
   const user = await prisma.user.findFirstOrThrow({
     where: {
@@ -89,6 +91,29 @@ export const createDocument = async ({
     userTeamRole = teamWithUserRole.members[0]?.role;
   }
 
+  let folderVisibility: DocumentVisibility | undefined;
+
+  if (folderId) {
+    const folder = await prisma.folder.findFirst({
+      where: {
+        id: folderId,
+        userId,
+        teamId,
+      },
+      select: {
+        visibility: true,
+      },
+    });
+
+    if (!folder) {
+      throw new AppError(AppErrorCode.NOT_FOUND, {
+        message: 'Folder not found',
+      });
+    }
+
+    folderVisibility = folder.visibility;
+  }
+
   if (normalizePdf) {
     const documentData = await prisma.documentData.findFirst({
       where: {
@@ -121,10 +146,13 @@ export const createDocument = async ({
         documentDataId,
         userId,
         teamId,
-        visibility: determineDocumentVisibility(
-          team?.teamGlobalSettings?.documentVisibility,
-          userTeamRole ?? TeamMemberRole.MEMBER,
-        ),
+        folderId,
+        visibility:
+          folderVisibility ??
+          determineDocumentVisibility(
+            team?.teamGlobalSettings?.documentVisibility,
+            userTeamRole ?? TeamMemberRole.MEMBER,
+          ),
         formValues,
         source: DocumentSource.DOCUMENT,
         documentMeta: {

packages/lib/server-only/document/find-documents.ts

@@ -27,6 +27,7 @@ export type FindDocumentsOptions = {
   period?: PeriodSelectorValue;
   senderIds?: number[];
   query?: string;
+  folderId?: string;
 };
 
 export const findDocuments = async ({
@@ -41,6 +42,7 @@ export const findDocuments = async ({
   period,
   senderIds,
   query = '',
+  folderId,
 }: FindDocumentsOptions) => {
   const user = await prisma.user.findFirstOrThrow({
     where: {
@@ -120,10 +122,10 @@ export const findDocuments = async ({
     },
   ];
 
-  let filters: Prisma.DocumentWhereInput | null = findDocumentsFilter(status, user);
+  let filters: Prisma.DocumentWhereInput | null = findDocumentsFilter(status, user, folderId);
 
   if (team) {
-    filters = findTeamDocumentsFilter(status, team, visibilityFilters);
+    filters = findTeamDocumentsFilter(status, team, visibilityFilters, folderId);
   }
 
   if (filters === null) {
@@ -227,6 +229,12 @@ export const findDocuments = async ({
     };
   }
 
+  if (folderId !== undefined) {
+    whereClause.folderId = folderId;
+  } else {
+    whereClause.folderId = null;
+  }
+
   const [data, count] = await Promise.all([
     prisma.document.findMany({
       where: whereClause,
@@ -273,13 +281,18 @@ export const findDocuments = async ({
   } satisfies FindResultResponse<typeof data>;
 };
 
-const findDocumentsFilter = (status: ExtendedDocumentStatus, user: User) => {
+const findDocumentsFilter = (
+  status: ExtendedDocumentStatus,
+  user: User,
+  folderId?: string | null,
+) => {
   return match<ExtendedDocumentStatus, Prisma.DocumentWhereInput>(status)
     .with(ExtendedDocumentStatus.ALL, () => ({
       OR: [
         {
           userId: user.id,
           teamId: null,
+          folderId: folderId,
         },
         {
           status: ExtendedDocumentStatus.COMPLETED,
@@ -288,6 +301,7 @@ const findDocumentsFilter = (status: ExtendedDocumentStatus, user: User) => {
               email: user.email,
             },
           },
+          folderId: folderId,
         },
         {
           status: ExtendedDocumentStatus.PENDING,
@@ -296,6 +310,7 @@ const findDocumentsFilter = (status: ExtendedDocumentStatus, user: User) => {
               email: user.email,
             },
           },
+          folderId: folderId,
         },
       ],
     }))
@@ -324,6 +339,7 @@ const findDocumentsFilter = (status: ExtendedDocumentStatus, user: User) => {
           userId: user.id,
           teamId: null,
           status: ExtendedDocumentStatus.PENDING,
+          folderId: folderId,
         },
         {
           status: ExtendedDocumentStatus.PENDING,
@@ -336,6 +352,7 @@ const findDocumentsFilter = (status: ExtendedDocumentStatus, user: User) => {
               },
             },
           },
+          folderId: folderId,
         },
       ],
     }))
@@ -345,6 +362,7 @@ const findDocumentsFilter = (status: ExtendedDocumentStatus, user: User) => {
           userId: user.id,
           teamId: null,
           status: ExtendedDocumentStatus.COMPLETED,
+          folderId: folderId,
         },
         {
           status: ExtendedDocumentStatus.COMPLETED,
@@ -353,6 +371,7 @@ const findDocumentsFilter = (status: ExtendedDocumentStatus, user: User) => {
               email: user.email,
             },
           },
+          folderId: folderId,
         },
       ],
     }))
@@ -362,6 +381,7 @@ const findDocumentsFilter = (status: ExtendedDocumentStatus, user: User) => {
           userId: user.id,
           teamId: null,
           status: ExtendedDocumentStatus.REJECTED,
+          folderId: folderId,
         },
         {
           status: ExtendedDocumentStatus.REJECTED,
@@ -371,6 +391,7 @@ const findDocumentsFilter = (status: ExtendedDocumentStatus, user: User) => {
               signingStatus: SigningStatus.REJECTED,
             },
           },
+          folderId: folderId,
         },
       ],
     }))
@@ -410,6 +431,7 @@ const findTeamDocumentsFilter = (
   status: ExtendedDocumentStatus,
   team: Team & { teamEmail: TeamEmail | null },
   visibilityFilters: Prisma.DocumentWhereInput[],
+  folderId?: string,
 ) => {
   const teamEmail = team.teamEmail?.email ?? null;
 
@@ -420,6 +442,7 @@ const findTeamDocumentsFilter = (
         OR: [
           {
             teamId: team.id,
+            folderId: folderId,
             OR: visibilityFilters,
           },
         ],
@@ -437,6 +460,7 @@ const findTeamDocumentsFilter = (
             },
           },
           OR: visibilityFilters,
+          folderId: folderId,
         });
 
         // Filter to display all documents that have been sent by the team email.
@@ -445,6 +469,7 @@ const findTeamDocumentsFilter = (
             email: teamEmail,
           },
           OR: visibilityFilters,
+          folderId: folderId,
         });
       }
 
@@ -470,6 +495,7 @@ const findTeamDocumentsFilter = (
           },
         },
         OR: visibilityFilters,
+        folderId: folderId,
       };
     })
     .with(ExtendedDocumentStatus.DRAFT, () => {
@@ -479,6 +505,7 @@ const findTeamDocumentsFilter = (
             teamId: team.id,
             status: ExtendedDocumentStatus.DRAFT,
             OR: visibilityFilters,
+            folderId: folderId,
           },
         ],
       };
@@ -490,6 +517,7 @@ const findTeamDocumentsFilter = (
             email: teamEmail,
           },
           OR: visibilityFilters,
+          folderId: folderId,
         });
       }
 
@@ -502,6 +530,7 @@ const findTeamDocumentsFilter = (
             teamId: team.id,
             status: ExtendedDocumentStatus.PENDING,
             OR: visibilityFilters,
+            folderId: folderId,
           },
         ],
       };
@@ -521,12 +550,14 @@ const findTeamDocumentsFilter = (
                 },
               },
               OR: visibilityFilters,
+              folderId: folderId,
             },
             {
               user: {
                 email: teamEmail,
               },
               OR: visibilityFilters,
+              folderId: folderId,
             },
           ],
         });

packages/lib/server-only/document/get-document-by-id.ts

@@ -12,9 +12,15 @@ export type GetDocumentByIdOptions = {
   documentId: number;
   userId: number;
   teamId?: number;
+  folderId?: string;
 };
 
-export const getDocumentById = async ({ documentId, userId, teamId }: GetDocumentByIdOptions) => {
+export const getDocumentById = async ({
+  documentId,
+  userId,
+  teamId,
+  folderId,
+}: GetDocumentByIdOptions) => {
   const documentWhereInput = await getDocumentWhereInput({
     documentId,
     userId,
@@ -22,7 +28,10 @@ export const getDocumentById = async ({ documentId, userId, teamId }: GetDocumen
   });
 
   const document = await prisma.document.findFirst({
-    where: documentWhereInput,
+    where: {
+      ...documentWhereInput,
+      folderId,
+    },
     include: {
       documentData: true,
       documentMeta: true,

packages/lib/server-only/document/get-document-with-details-by-id.ts

@@ -7,12 +7,14 @@ export type GetDocumentWithDetailsByIdOptions = {
   documentId: number;
   userId: number;
   teamId?: number;
+  folderId?: string;
 };
 
 export const getDocumentWithDetailsById = async ({
   documentId,
   userId,
   teamId,
+  folderId,
 }: GetDocumentWithDetailsByIdOptions) => {
   const documentWhereInput = await getDocumentWhereInput({
     documentId,
@@ -21,12 +23,16 @@ export const getDocumentWithDetailsById = async ({
   });
 
   const document = await prisma.document.findFirst({
-    where: documentWhereInput,
+    where: {
+      ...documentWhereInput,
+      folderId,
+    },
     include: {
       documentData: true,
       documentMeta: true,
       recipients: true,
       fields: true,
+      folder: true,
     },
   });
 

packages/lib/server-only/document/get-stats.ts

@@ -15,9 +15,16 @@ export type GetStatsInput = {
   team?: Omit<GetTeamCountsOption, 'createdAt'>;
   period?: PeriodSelectorValue;
   search?: string;
+  folderId?: string;
 };
 
-export const getStats = async ({ user, period, search = '', ...options }: GetStatsInput) => {
+export const getStats = async ({
+  user,
+  period,
+  search = '',
+  folderId,
+  ...options
+}: GetStatsInput) => {
   let createdAt: Prisma.DocumentWhereInput['createdAt'];
 
   if (period) {
@@ -37,8 +44,9 @@ export const getStats = async ({ user, period, search = '', ...options }: GetSta
         currentUserEmail: user.email,
         userId: user.id,
         search,
+        folderId,
       })
-    : getCounts({ user, createdAt, search }));
+    : getCounts({ user, createdAt, search, folderId }));
 
   const stats: Record<ExtendedDocumentStatus, number> = {
     [ExtendedDocumentStatus.DRAFT]: 0,
@@ -84,9 +92,10 @@ type GetCountsOption = {
   user: User;
   createdAt: Prisma.DocumentWhereInput['createdAt'];
   search?: string;
+  folderId?: string | null;
 };
 
-const getCounts = async ({ user, createdAt, search }: GetCountsOption) => {
+const getCounts = async ({ user, createdAt, search, folderId }: GetCountsOption) => {
   const searchFilter: Prisma.DocumentWhereInput = {
     OR: [
       { title: { contains: search, mode: 'insensitive' } },
@@ -95,6 +104,8 @@ const getCounts = async ({ user, createdAt, search }: GetCountsOption) => {
     ],
   };
 
+  const rootPageFilter = folderId === undefined ? { folderId: null } : {};
+
   return Promise.all([
     // Owner counts.
     prisma.document.groupBy({
@@ -107,7 +118,7 @@ const getCounts = async ({ user, createdAt, search }: GetCountsOption) => {
         createdAt,
         teamId: null,
         deletedAt: null,
-        AND: [searchFilter],
+        AND: [searchFilter, rootPageFilter, folderId ? { folderId } : {}],
       },
     }),
     // Not signed counts.
@@ -126,7 +137,7 @@ const getCounts = async ({ user, createdAt, search }: GetCountsOption) => {
           },
         },
         createdAt,
-        AND: [searchFilter],
+        AND: [searchFilter, rootPageFilter, folderId ? { folderId } : {}],
       },
     }),
     // Has signed counts.
@@ -164,7 +175,7 @@ const getCounts = async ({ user, createdAt, search }: GetCountsOption) => {
             },
           },
         ],
-        AND: [searchFilter],
+        AND: [searchFilter, rootPageFilter, folderId ? { folderId } : {}],
       },
     }),
   ]);
@@ -179,10 +190,11 @@ type GetTeamCountsOption = {
   createdAt: Prisma.DocumentWhereInput['createdAt'];
   currentTeamMemberRole?: TeamMemberRole;
   search?: string;
+  folderId?: string | null;
 };
 
 const getTeamCounts = async (options: GetTeamCountsOption) => {
-  const { createdAt, teamId, teamEmail } = options;
+  const { createdAt, teamId, teamEmail, folderId } = options;
 
   const senderIds = options.senderIds ?? [];
 
@@ -206,6 +218,7 @@ const getTeamCounts = async (options: GetTeamCountsOption) => {
     createdAt,
     teamId,
     deletedAt: null,
+    folderId,
   };
 
   let notSignedCountsGroupByArgs = null;
@@ -278,6 +291,7 @@ const getTeamCounts = async (options: GetTeamCountsOption) => {
       where: {
         userId: userIdWhereClause,
         createdAt,
+        folderId,
         status: ExtendedDocumentStatus.PENDING,
         recipients: {
           some: {
@@ -298,6 +312,7 @@ const getTeamCounts = async (options: GetTeamCountsOption) => {
       where: {
         userId: userIdWhereClause,
         createdAt,
+        folderId,
         OR: [
           {
             status: ExtendedDocumentStatus.PENDING,

packages/lib/server-only/folder/create-folder.ts

@@ -0,0 +1,86 @@
+import { TeamMemberRole } from '@prisma/client';
+import type { Team, TeamGlobalSettings } from '@prisma/client';
+
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { prisma } from '@documenso/prisma';
+
+import type { TFolderType } from '../../types/folder-type';
+import { FolderType } from '../../types/folder-type';
+import { determineDocumentVisibility } from '../../utils/document-visibility';
+
+export interface CreateFolderOptions {
+  userId: number;
+  teamId?: number;
+  name: string;
+  parentId?: string | null;
+  type?: TFolderType;
+}
+
+export const createFolder = async ({
+  userId,
+  teamId,
+  name,
+  parentId,
+  type = FolderType.DOCUMENT,
+}: CreateFolderOptions) => {
+  const user = await prisma.user.findFirstOrThrow({
+    where: {
+      id: userId,
+    },
+    include: {
+      teamMembers: {
+        select: {
+          teamId: true,
+        },
+      },
+    },
+  });
+
+  if (
+    teamId !== undefined &&
+    !user.teamMembers.some((teamMember) => teamMember.teamId === teamId)
+  ) {
+    throw new AppError(AppErrorCode.NOT_FOUND, {
+      message: 'Team not found',
+    });
+  }
+
+  let team: (Team & { teamGlobalSettings: TeamGlobalSettings | null }) | null = null;
+  let userTeamRole: TeamMemberRole | undefined;
+
+  if (teamId) {
+    const teamWithUserRole = await prisma.team.findFirstOrThrow({
+      where: {
+        id: teamId,
+      },
+      include: {
+        teamGlobalSettings: true,
+        members: {
+          where: {
+            userId: userId,
+          },
+          select: {
+            role: true,
+          },
+        },
+      },
+    });
+
+    team = teamWithUserRole;
+    userTeamRole = teamWithUserRole.members[0]?.role;
+  }
+
+  return await prisma.folder.create({
+    data: {
+      name,
+      userId,
+      teamId,
+      parentId,
+      type,
+      visibility: determineDocumentVisibility(
+        team?.teamGlobalSettings?.documentVisibility,
+        userTeamRole ?? TeamMemberRole.MEMBER,
+      ),
+    },
+  });
+};

packages/lib/server-only/folder/delete-folder.ts

@@ -0,0 +1,85 @@
+import { DocumentVisibility, TeamMemberRole } from '@prisma/client';
+import { match } from 'ts-pattern';
+
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { prisma } from '@documenso/prisma';
+
+export interface DeleteFolderOptions {
+  userId: number;
+  teamId?: number;
+  folderId: string;
+}
+
+export const deleteFolder = async ({ userId, teamId, folderId }: DeleteFolderOptions) => {
+  let teamMemberRole: TeamMemberRole | null = null;
+
+  if (teamId) {
+    const team = await prisma.team.findFirst({
+      where: {
+        id: teamId,
+        members: {
+          some: {
+            userId,
+          },
+        },
+      },
+      include: {
+        members: {
+          where: {
+            userId,
+          },
+          select: {
+            role: true,
+          },
+        },
+      },
+    });
+
+    if (!team) {
+      throw new AppError(AppErrorCode.NOT_FOUND, {
+        message: 'Team not found',
+      });
+    }
+
+    teamMemberRole = team.members[0]?.role ?? null;
+  }
+
+  const folder = await prisma.folder.findFirst({
+    where: {
+      id: folderId,
+      userId,
+      teamId,
+    },
+    include: {
+      documents: true,
+      subfolders: true,
+      templates: true,
+    },
+  });
+
+  if (!folder) {
+    throw new AppError(AppErrorCode.NOT_FOUND, {
+      message: 'Folder not found',
+    });
+  }
+
+  if (teamId && teamMemberRole) {
+    const hasPermission = match(teamMemberRole)
+      .with(TeamMemberRole.ADMIN, () => true)
+      .with(TeamMemberRole.MANAGER, () => folder.visibility !== DocumentVisibility.ADMIN)
+      .with(TeamMemberRole.MEMBER, () => folder.visibility === DocumentVisibility.EVERYONE)
+      .otherwise(() => false);
+
+    if (!hasPermission) {
+      throw new AppError(AppErrorCode.UNAUTHORIZED, {
+        message: 'You do not have permission to delete this folder',
+      });
+    }
+  }
+
+  return await prisma.folder.delete({
+    where: {
+      id: folderId,
+    },
+  });
+};

packages/lib/server-only/folder/find-folders.ts

@@ -0,0 +1,152 @@
+import { TeamMemberRole } from '@prisma/client';
+import { match } from 'ts-pattern';
+
+import { prisma } from '@documenso/prisma';
+
+import { DocumentVisibility } from '../../types/document-visibility';
+import type { TFolderType } from '../../types/folder-type';
+
+export interface FindFoldersOptions {
+  userId: number;
+  teamId?: number;
+  parentId?: string | null;
+  type?: TFolderType;
+}
+
+export const findFolders = async ({ userId, teamId, parentId, type }: FindFoldersOptions) => {
+  let team = null;
+  let teamMemberRole = null;
+
+  if (teamId !== undefined) {
+    try {
+      team = await prisma.team.findFirstOrThrow({
+        where: {
+          id: teamId,
+          members: {
+            some: {
+              userId,
+            },
+          },
+        },
+        include: {
+          members: {
+            where: {
+              userId,
+            },
+            select: {
+              role: true,
+            },
+          },
+        },
+      });
+
+      teamMemberRole = team.members[0].role;
+    } catch (error) {
+      console.error('Error finding team:', error);
+      throw error;
+    }
+  }
+
+  const visibilityFilters = match(teamMemberRole)
+    .with(TeamMemberRole.ADMIN, () => ({
+      visibility: {
+        in: [
+          DocumentVisibility.EVERYONE,
+          DocumentVisibility.MANAGER_AND_ABOVE,
+          DocumentVisibility.ADMIN,
+        ],
+      },
+    }))
+    .with(TeamMemberRole.MANAGER, () => ({
+      visibility: {
+        in: [DocumentVisibility.EVERYONE, DocumentVisibility.MANAGER_AND_ABOVE],
+      },
+    }))
+    .otherwise(() => ({ visibility: DocumentVisibility.EVERYONE }));
+
+  const whereClause = {
+    AND: [
+      { parentId },
+      teamId
+        ? {
+            OR: [
+              { teamId, ...visibilityFilters },
+              { userId, teamId },
+            ],
+          }
+        : { userId, teamId: null },
+    ],
+  };
+
+  try {
+    const folders = await prisma.folder.findMany({
+      where: {
+        ...whereClause,
+        ...(type ? { type } : {}),
+      },
+      orderBy: [{ pinned: 'desc' }, { createdAt: 'desc' }],
+    });
+
+    const foldersWithDetails = await Promise.all(
+      folders.map(async (folder) => {
+        try {
+          const [subfolders, documentCount, templateCount, subfolderCount] = await Promise.all([
+            prisma.folder.findMany({
+              where: {
+                parentId: folder.id,
+                ...(teamId ? { teamId, ...visibilityFilters } : { userId, teamId: null }),
+              },
+              orderBy: {
+                createdAt: 'desc',
+              },
+            }),
+            prisma.document.count({
+              where: {
+                folderId: folder.id,
+              },
+            }),
+            prisma.template.count({
+              where: {
+                folderId: folder.id,
+              },
+            }),
+            prisma.folder.count({
+              where: {
+                parentId: folder.id,
+                ...(teamId ? { teamId, ...visibilityFilters } : { userId, teamId: null }),
+              },
+            }),
+          ]);
+
+          const subfoldersWithEmptySubfolders = subfolders.map((subfolder) => ({
+            ...subfolder,
+            subfolders: [],
+            _count: {
+              documents: 0,
+              templates: 0,
+              subfolders: 0,
+            },
+          }));
+
+          return {
+            ...folder,
+            subfolders: subfoldersWithEmptySubfolders,
+            _count: {
+              documents: documentCount,
+              templates: templateCount,
+              subfolders: subfolderCount,
+            },
+          };
+        } catch (error) {
+          console.error('Error processing folder:', folder.id, error);
+          throw error;
+        }
+      }),
+    );
+
+    return foldersWithDetails;
+  } catch (error) {
+    console.error('Error in findFolders:', error);
+    throw error;
+  }
+};

packages/lib/server-only/folder/get-folder-breadcrumbs.ts

@@ -0,0 +1,112 @@
+import { TeamMemberRole } from '@prisma/client';
+import { match } from 'ts-pattern';
+
+import { prisma } from '@documenso/prisma';
+
+import { DocumentVisibility } from '../../types/document-visibility';
+import type { TFolderType } from '../../types/folder-type';
+
+export interface GetFolderBreadcrumbsOptions {
+  userId: number;
+  teamId?: number;
+  folderId: string;
+  type?: TFolderType;
+}
+
+export const getFolderBreadcrumbs = async ({
+  userId,
+  teamId,
+  folderId,
+  type,
+}: GetFolderBreadcrumbsOptions) => {
+  let teamMemberRole = null;
+
+  if (teamId !== undefined) {
+    try {
+      const team = await prisma.team.findFirstOrThrow({
+        where: {
+          id: teamId,
+          members: {
+            some: {
+              userId,
+            },
+          },
+        },
+        include: {
+          members: {
+            where: {
+              userId,
+            },
+            select: {
+              role: true,
+            },
+          },
+        },
+      });
+
+      teamMemberRole = team.members[0].role;
+    } catch (error) {
+      console.error('Error finding team:', error);
+      return [];
+    }
+  }
+
+  const visibilityFilters = match(teamMemberRole)
+    .with(TeamMemberRole.ADMIN, () => ({
+      visibility: {
+        in: [
+          DocumentVisibility.EVERYONE,
+          DocumentVisibility.MANAGER_AND_ABOVE,
+          DocumentVisibility.ADMIN,
+        ],
+      },
+    }))
+    .with(TeamMemberRole.MANAGER, () => ({
+      visibility: {
+        in: [DocumentVisibility.EVERYONE, DocumentVisibility.MANAGER_AND_ABOVE],
+      },
+    }))
+    .otherwise(() => ({ visibility: DocumentVisibility.EVERYONE }));
+
+  const whereClause = (folderId: string) => ({
+    id: folderId,
+    ...(type ? { type } : {}),
+    ...(teamId
+      ? {
+          OR: [
+            { teamId, ...visibilityFilters },
+            { userId, teamId },
+          ],
+        }
+      : { userId, teamId: null }),
+  });
+
+  const breadcrumbs = [];
+  let currentFolderId = folderId;
+
+  const currentFolder = await prisma.folder.findFirst({
+    where: whereClause(currentFolderId),
+  });
+
+  if (!currentFolder) {
+    return [];
+  }
+
+  breadcrumbs.push(currentFolder);
+
+  while (currentFolder?.parentId) {
+    const parentFolder = await prisma.folder.findFirst({
+      where: whereClause(currentFolder.parentId),
+    });
+
+    if (!parentFolder) {
+      break;
+    }
+
+    breadcrumbs.unshift(parentFolder);
+    currentFolderId = parentFolder.id;
+    currentFolder.parentId = parentFolder.parentId;
+  }
+
+  return breadcrumbs;
+};

packages/lib/server-only/folder/get-folder-by-id.ts

@@ -0,0 +1,92 @@
+import { TeamMemberRole } from '@prisma/client';
+import { match } from 'ts-pattern';
+
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { prisma } from '@documenso/prisma';
+
+import { DocumentVisibility } from '../../types/document-visibility';
+import type { TFolderType } from '../../types/folder-type';
+
+export interface GetFolderByIdOptions {
+  userId: number;
+  teamId?: number;
+  folderId?: string;
+  type?: TFolderType;
+}
+
+export const getFolderById = async ({ userId, teamId, folderId, type }: GetFolderByIdOptions) => {
+  let teamMemberRole = null;
+
+  if (teamId !== undefined) {
+    try {
+      const team = await prisma.team.findFirstOrThrow({
+        where: {
+          id: teamId,
+          members: {
+            some: {
+              userId,
+            },
+          },
+        },
+        include: {
+          members: {
+            where: {
+              userId,
+            },
+            select: {
+              role: true,
+            },
+          },
+        },
+      });
+
+      teamMemberRole = team.members[0].role;
+    } catch (error) {
+      throw new AppError(AppErrorCode.NOT_FOUND, {
+        message: 'Team not found',
+      });
+    }
+  }
+
+  const visibilityFilters = match(teamMemberRole)
+    .with(TeamMemberRole.ADMIN, () => ({
+      visibility: {
+        in: [
+          DocumentVisibility.EVERYONE,
+          DocumentVisibility.MANAGER_AND_ABOVE,
+          DocumentVisibility.ADMIN,
+        ],
+      },
+    }))
+    .with(TeamMemberRole.MANAGER, () => ({
+      visibility: {
+        in: [DocumentVisibility.EVERYONE, DocumentVisibility.MANAGER_AND_ABOVE],
+      },
+    }))
+    .otherwise(() => ({ visibility: DocumentVisibility.EVERYONE }));
+
+  const whereClause = {
+    id: folderId,
+    ...(type ? { type } : {}),
+    ...(teamId
+      ? {
+          OR: [
+            { teamId, ...visibilityFilters },
+            { userId, teamId },
+          ],
+        }
+      : { userId, teamId: null }),
+  };
+
+  const folder = await prisma.folder.findFirst({
+    where: whereClause,
+  });
+
+  if (!folder) {
+    throw new AppError(AppErrorCode.NOT_FOUND, {
+      message: 'Folder not found',
+    });
+  }
+
+  return folder;
+};

packages/lib/server-only/folder/move-document-to-folder.ts

@@ -0,0 +1,130 @@
+import { TeamMemberRole } from '@prisma/client';
+import { match } from 'ts-pattern';
+
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { DocumentVisibility } from '@documenso/lib/types/document-visibility';
+import { FolderType } from '@documenso/lib/types/folder-type';
+import type { ApiRequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
+import { prisma } from '@documenso/prisma';
+
+export interface MoveDocumentToFolderOptions {
+  userId: number;
+  teamId?: number;
+  documentId: number;
+  folderId?: string | null;
+  requestMetadata?: ApiRequestMetadata;
+}
+
+export const moveDocumentToFolder = async ({
+  userId,
+  teamId,
+  documentId,
+  folderId,
+}: MoveDocumentToFolderOptions) => {
+  let teamMemberRole = null;
+
+  if (teamId !== undefined) {
+    try {
+      const team = await prisma.team.findFirstOrThrow({
+        where: {
+          id: teamId,
+          members: {
+            some: {
+              userId,
+            },
+          },
+        },
+        include: {
+          members: {
+            where: {
+              userId,
+            },
+            select: {
+              role: true,
+            },
+          },
+        },
+      });
+
+      teamMemberRole = team.members[0].role;
+    } catch (error) {
+      console.error('Error finding team:', error);
+      throw new AppError(AppErrorCode.NOT_FOUND, {
+        message: 'Team not found',
+      });
+    }
+  }
+
+  const visibilityFilters = match(teamMemberRole)
+    .with(TeamMemberRole.ADMIN, () => ({
+      visibility: {
+        in: [
+          DocumentVisibility.EVERYONE,
+          DocumentVisibility.MANAGER_AND_ABOVE,
+          DocumentVisibility.ADMIN,
+        ],
+      },
+    }))
+    .with(TeamMemberRole.MANAGER, () => ({
+      visibility: {
+        in: [DocumentVisibility.EVERYONE, DocumentVisibility.MANAGER_AND_ABOVE],
+      },
+    }))
+    .otherwise(() => ({ visibility: DocumentVisibility.EVERYONE }));
+
+  const documentWhereClause = {
+    id: documentId,
+    ...(teamId
+      ? {
+          OR: [
+            { teamId, ...visibilityFilters },
+            { userId, teamId },
+          ],
+        }
+      : { userId, teamId: null }),
+  };
+
+  const document = await prisma.document.findFirst({
+    where: documentWhereClause,
+  });
+
+  if (!document) {
+    throw new AppError(AppErrorCode.NOT_FOUND, {
+      message: 'Document not found',
+    });
+  }
+
+  if (folderId) {
+    const folderWhereClause = {
+      id: folderId,
+      type: FolderType.DOCUMENT,
+      ...(teamId
+        ? {
+            OR: [
+              { teamId, ...visibilityFilters },
+              { userId, teamId },
+            ],
+          }
+        : { userId, teamId: null }),
+    };
+
+    const folder = await prisma.folder.findFirst({
+      where: folderWhereClause,
+    });
+
+    if (!folder) {
+      throw new AppError(AppErrorCode.NOT_FOUND, {
+        message: 'Folder not found',
+      });
+    }
+  }
+
+  return await prisma.document.update({
+    where: {
+      id: documentId,
+    },
+    data: {
+      folderId,
+    },
+  });
+};

packages/lib/server-only/folder/move-folder.ts

@@ -0,0 +1,85 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import type { ApiRequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
+import { prisma } from '@documenso/prisma';
+
+export interface MoveFolderOptions {
+  userId: number;
+  teamId?: number;
+  folderId?: string;
+  parentId?: string | null;
+  requestMetadata?: ApiRequestMetadata;
+}
+
+export const moveFolder = async ({ userId, teamId, folderId, parentId }: MoveFolderOptions) => {
+  return await prisma.$transaction(async (tx) => {
+    const folder = await tx.folder.findFirst({
+      where: {
+        id: folderId,
+        userId,
+        teamId,
+      },
+    });
+
+    if (!folder) {
+      throw new AppError(AppErrorCode.NOT_FOUND, {
+        message: 'Folder not found',
+      });
+    }
+
+    if (parentId) {
+      const parentFolder = await tx.folder.findFirst({
+        where: {
+          id: parentId,
+          userId,
+          teamId,
+          type: folder.type,
+        },
+      });
+
+      if (!parentFolder) {
+        throw new AppError(AppErrorCode.NOT_FOUND, {
+          message: 'Parent folder not found',
+        });
+      }
+
+      if (parentId === folderId) {
+        throw new AppError(AppErrorCode.INVALID_REQUEST, {
+          message: 'Cannot move a folder into itself',
+        });
+      }
+
+      let currentParentId = parentFolder.parentId;
+      while (currentParentId) {
+        if (currentParentId === folderId) {
+          throw new AppError(AppErrorCode.INVALID_REQUEST, {
+            message: 'Cannot move a folder into its descendant',
+          });
+        }
+
+        const currentParent = await tx.folder.findUnique({
+          where: {
+            id: currentParentId,
+          },
+          select: {
+            parentId: true,
+          },
+        });
+
+        if (!currentParent) {
+          break;
+        }
+
+        currentParentId = currentParent.parentId;
+      }
+    }
+
+    return await tx.folder.update({
+      where: {
+        id: folderId,
+      },
+      data: {
+        parentId,
+      },
+    });
+  });
+};

packages/lib/server-only/folder/move-template-to-folder.ts

@@ -0,0 +1,59 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { FolderType } from '@documenso/lib/types/folder-type';
+import { prisma } from '@documenso/prisma';
+
+export interface MoveTemplateToFolderOptions {
+  userId: number;
+  teamId?: number;
+  templateId: number;
+  folderId?: string | null;
+}
+
+export const moveTemplateToFolder = async ({
+  userId,
+  teamId,
+  templateId,
+  folderId,
+}: MoveTemplateToFolderOptions) => {
+  return await prisma.$transaction(async (tx) => {
+    const template = await tx.template.findFirst({
+      where: {
+        id: templateId,
+        userId,
+        teamId,
+      },
+    });
+
+    if (!template) {
+      throw new AppError(AppErrorCode.NOT_FOUND, {
+        message: 'Template not found',
+      });
+    }
+
+    if (folderId !== null) {
+      const folder = await tx.folder.findFirst({
+        where: {
+          id: folderId,
+          userId,
+          teamId,
+          type: FolderType.TEMPLATE,
+        },
+      });
+
+      if (!folder) {
+        throw new AppError(AppErrorCode.NOT_FOUND, {
+          message: 'Folder not found',
+        });
+      }
+    }
+
+    return await tx.template.update({
+      where: {
+        id: templateId,
+      },
+      data: {
+        folderId,
+      },
+    });
+  });
+};

packages/lib/server-only/folder/pin-folder.ts

@@ -0,0 +1,37 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { prisma } from '@documenso/prisma';
+
+import type { TFolderType } from '../../types/folder-type';
+
+export interface PinFolderOptions {
+  userId: number;
+  teamId?: number;
+  folderId: string;
+  type?: TFolderType;
+}
+
+export const pinFolder = async ({ userId, teamId, folderId, type }: PinFolderOptions) => {
+  const folder = await prisma.folder.findFirst({
+    where: {
+      id: folderId,
+      userId,
+      teamId,
+      type,
+    },
+  });
+
+  if (!folder) {
+    throw new AppError(AppErrorCode.NOT_FOUND, {
+      message: 'Folder not found',
+    });
+  }
+
+  return await prisma.folder.update({
+    where: {
+      id: folderId,
+    },
+    data: {
+      pinned: true,
+    },
+  });
+};

packages/lib/server-only/folder/unpin-folder.ts

@@ -0,0 +1,37 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { prisma } from '@documenso/prisma';
+
+import type { TFolderType } from '../../types/folder-type';
+
+export interface UnpinFolderOptions {
+  userId: number;
+  teamId?: number;
+  folderId: string;
+  type?: TFolderType;
+}
+
+export const unpinFolder = async ({ userId, teamId, folderId, type }: UnpinFolderOptions) => {
+  const folder = await prisma.folder.findFirst({
+    where: {
+      id: folderId,
+      userId,
+      teamId,
+      type,
+    },
+  });
+
+  if (!folder) {
+    throw new AppError(AppErrorCode.NOT_FOUND, {
+      message: 'Folder not found',
+    });
+  }
+
+  return await prisma.folder.update({
+    where: {
+      id: folderId,
+    },
+    data: {
+      pinned: false,
+    },
+  });
+};

packages/lib/server-only/folder/update-folder.ts

@@ -0,0 +1,53 @@
+import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
+import { prisma } from '@documenso/prisma';
+import { DocumentVisibility } from '@documenso/prisma/generated/types';
+
+import type { TFolderType } from '../../types/folder-type';
+import { FolderType } from '../../types/folder-type';
+
+export interface UpdateFolderOptions {
+  userId: number;
+  teamId?: number;
+  folderId: string;
+  name: string;
+  visibility: DocumentVisibility;
+  type?: TFolderType;
+}
+
+export const updateFolder = async ({
+  userId,
+  teamId,
+  folderId,
+  name,
+  visibility,
+  type,
+}: UpdateFolderOptions) => {
+  const folder = await prisma.folder.findFirst({
+    where: {
+      id: folderId,
+      userId,
+      teamId,
+      type,
+    },
+  });
+
+  if (!folder) {
+    throw new AppError(AppErrorCode.NOT_FOUND, {
+      message: 'Folder not found',
+    });
+  }
+
+  const isTemplateFolder = folder.type === FolderType.TEMPLATE;
+  const effectiveVisibility =
+    isTemplateFolder && teamId !== null ? DocumentVisibility.EVERYONE : visibility;
+
+  return await prisma.folder.update({
+    where: {
+      id: folderId,
+    },
+    data: {
+      name,
+      visibility: effectiveVisibility,
+    },
+  });
+};

packages/lib/server-only/template/create-template.ts

@@ -20,6 +20,7 @@ export const createTemplate = async ({
   userId,
   teamId,
   templateDocumentDataId,
+  folderId,
 }: CreateTemplateOptions) => {
   let team = null;
 
@@ -43,12 +44,38 @@ export const createTemplate = async ({
     }
   }
 
+  const folder = await prisma.folder.findFirstOrThrow({
+    where: {
+      id: folderId,
+      ...(teamId
+        ? {
+            team: {
+              id: teamId,
+              members: {
+                some: {
+                  userId,
+                },
+              },
+            },
+          }
+        : {
+            userId,
+            teamId: null,
+          }),
+    },
+  });
+
+  if (!team) {
+    throw new AppError(AppErrorCode.NOT_FOUND);
+  }
+
   return await prisma.template.create({
     data: {
       title,
       userId,
       templateDocumentDataId,
       teamId,
+      folderId: folder.id,
       templateMeta: {
         create: {
           language: team?.teamGlobalSettings?.documentLanguage,

packages/lib/server-only/template/find-templates.ts

@@ -12,6 +12,7 @@ export type FindTemplatesOptions = {
   type?: Template['type'];
   page?: number;
   perPage?: number;
+  folderId?: string;
 };
 
 export const findTemplates = async ({
@@ -20,6 +21,7 @@ export const findTemplates = async ({
   type,
   page = 1,
   perPage = 10,
+  folderId,
 }: FindTemplatesOptions) => {
   const whereFilter: Prisma.TemplateWhereInput[] = [];
 
@@ -67,6 +69,12 @@ export const findTemplates = async ({
     );
   }
 
+  if (folderId) {
+    whereFilter.push({ folderId });
+  } else {
+    whereFilter.push({ folderId: null });
+  }
+
   const [data, count] = await Promise.all([
     prisma.template.findMany({
       where: {

packages/lib/server-only/template/get-template-by-id.ts

@@ -6,9 +6,15 @@ export type GetTemplateByIdOptions = {
   id: number;
   userId: number;
   teamId?: number;
+  folderId?: string | null;
 };
 
-export const getTemplateById = async ({ id, userId, teamId }: GetTemplateByIdOptions) => {
+export const getTemplateById = async ({
+  id,
+  userId,
+  teamId,
+  folderId = null,
+}: GetTemplateByIdOptions) => {
   const template = await prisma.template.findFirst({
     where: {
       id,
@@ -27,6 +33,7 @@ export const getTemplateById = async ({ id, userId, teamId }: GetTemplateByIdOpt
             userId,
             teamId: null,
           }),
+      ...(folderId ? { folderId } : {}),
     },
     include: {
       directLink: true,
@@ -41,6 +48,7 @@ export const getTemplateById = async ({ id, userId, teamId }: GetTemplateByIdOpt
           email: true,
         },
       },
+      folder: true,
     },
   });
 

packages/lib/types/document.ts

@@ -3,6 +3,7 @@ import type { z } from 'zod';
 import { DocumentDataSchema } from '@documenso/prisma/generated/zod/modelSchema/DocumentDataSchema';
 import { DocumentMetaSchema } from '@documenso/prisma/generated/zod/modelSchema/DocumentMetaSchema';
 import { DocumentSchema } from '@documenso/prisma/generated/zod/modelSchema/DocumentSchema';
+import { FolderSchema } from '@documenso/prisma/generated/zod/modelSchema/FolderSchema';
 import { TeamSchema } from '@documenso/prisma/generated/zod/modelSchema/TeamSchema';
 import { UserSchema } from '@documenso/prisma/generated/zod/modelSchema/UserSchema';
 
@@ -31,6 +32,7 @@ export const ZDocumentSchema = DocumentSchema.pick({
   deletedAt: true,
   teamId: true,
   templateId: true,
+  folderId: true,
 }).extend({
   // Todo: Maybe we want to alter this a bit since this returns a lot of data.
   documentData: DocumentDataSchema.pick({
@@ -57,6 +59,18 @@ export const ZDocumentSchema = DocumentSchema.pick({
     language: true,
     emailSettings: true,
   }).nullable(),
+  folder: FolderSchema.pick({
+    id: true,
+    name: true,
+    type: true,
+    visibility: true,
+    userId: true,
+    teamId: true,
+    pinned: true,
+    parentId: true,
+    createdAt: true,
+    updatedAt: true,
+  }).nullable(),
   recipients: ZRecipientLiteSchema.array(),
   fields: ZFieldSchema.array(),
 });
@@ -83,6 +97,7 @@ export const ZDocumentLiteSchema = DocumentSchema.pick({
   deletedAt: true,
   teamId: true,
   templateId: true,
+  folderId: true,
   useLegacyFieldInsertion: true,
 });
 
@@ -108,6 +123,7 @@ export const ZDocumentManySchema = DocumentSchema.pick({
   deletedAt: true,
   teamId: true,
   templateId: true,
+  folderId: true,
   useLegacyFieldInsertion: true,
 }).extend({
   user: UserSchema.pick({

packages/lib/types/folder-type.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+
+export const FolderType = {
+  DOCUMENT: 'DOCUMENT',
+  TEMPLATE: 'TEMPLATE',
+} as const;
+
+export const ZFolderTypeSchema = z.enum([FolderType.DOCUMENT, FolderType.TEMPLATE]);
+export type TFolderType = z.infer<typeof ZFolderTypeSchema>;

packages/lib/types/template.ts

@@ -1,6 +1,7 @@
 import type { z } from 'zod';
 
 import { DocumentDataSchema } from '@documenso/prisma/generated/zod/modelSchema/DocumentDataSchema';
+import { FolderSchema } from '@documenso/prisma/generated/zod/modelSchema/FolderSchema';
 import TeamSchema from '@documenso/prisma/generated/zod/modelSchema/TeamSchema';
 import { TemplateDirectLinkSchema } from '@documenso/prisma/generated/zod/modelSchema/TemplateDirectLinkSchema';
 import { TemplateMetaSchema } from '@documenso/prisma/generated/zod/modelSchema/TemplateMetaSchema';
@@ -29,6 +30,7 @@ export const ZTemplateSchema = TemplateSchema.pick({
   updatedAt: true,
   publicTitle: true,
   publicDescription: true,
+  folderId: true,
 }).extend({
   // Todo: Maybe we want to alter this a bit since this returns a lot of data.
   templateDocumentData: DocumentDataSchema.pick({
@@ -62,6 +64,18 @@ export const ZTemplateSchema = TemplateSchema.pick({
   }),
   recipients: ZRecipientLiteSchema.array(),
   fields: ZFieldSchema.array(),
+  folder: FolderSchema.pick({
+    id: true,
+    name: true,
+    type: true,
+    visibility: true,
+    userId: true,
+    teamId: true,
+    pinned: true,
+    parentId: true,
+    createdAt: true,
+    updatedAt: true,
+  }).nullable(),
 });
 
 export type TTemplate = z.infer<typeof ZTemplateSchema>;
@@ -83,6 +97,7 @@ export const ZTemplateLiteSchema = TemplateSchema.pick({
   updatedAt: true,
   publicTitle: true,
   publicDescription: true,
+  folderId: true,
   useLegacyFieldInsertion: true,
 });
 
@@ -103,6 +118,7 @@ export const ZTemplateManySchema = TemplateSchema.pick({
   updatedAt: true,
   publicTitle: true,
   publicDescription: true,
+  folderId: true,
   useLegacyFieldInsertion: true,
 }).extend({
   team: TeamSchema.pick({

packages/lib/utils/format-folder-count.ts

@@ -0,0 +1,5 @@
+export function formatFolderCount(count: number, singular: string, plural?: string): string {
+  const itemLabel = count === 1 ? singular : plural || `${singular}s`;
+
+  return `${count} ${itemLabel}`;
+}