first suggestion which I'd give is to use drizzle instead of Prisma, you'll get a performance boost

and for queries or mutations, I like to structure it like this.

In your context, you could maybe like create a folder for each feature and group all the queries there

Thanks for sharing! I actually used a similar structure in the past, but I found it becomes hard to manage and maintain once you start having 10–20 features. For each feature, I usually have:
- components (feature-specific components)
- hooks (data fetching with react-query)
- utils or lib (business logic or reusable code)
- server (all server-side logic)
- server/actions (mutations using server actions)
- server/queries (database queries with prisma, server-only files)
- api (fetching from API endpoints)

One problem I ran into was where to put utility functions or business logic shared across multiple features. To solve this, I created an /entities folder that contains all features with shared code. For example:
/entities/timesheets/ |-- /types # shared types |-- /lib or /utils # business logic usable by multiple features

I also had to split the /lib folder into /core and /shared:
/core contains all core app logic like authentication, prisma, Stripe, etc.
/shared contains all shared code like reusable components, hooks, utils, API handlers, etc.

So basically, I’m looking for a project structure that is optimized and scalable for larger projects.

Personally, I like to split my frontend and backend into different folders, such that lib folder contains mostly backend components like actions.

And for frontend components , I prefer to add it like @/components/{featureName}/ and all components inside.

for hooks, since hooks are usually reused across multiple pages/components, I prefer to store them like @/hooks/{hookName}.ts if less in number, or organize in sub folders.

and I don't really think hooks should be inside mutations, if hooks are reused, consider storing it inside @hooks/

Previously, I used this structure:

/features/feature-1
|-- /server
|   |-- /actions        # server actions
|   |-- /queries        # database fetches with Prisma
|-- /components         # reusable components for the feature
|-- /hooks              # hooks for queries/mutations with react-query
|-- /lib and /utils     # business logic and utilities
|-- /api                # API calls used by react-query hooks

The problem I ran into was about shared business logic or utils across multiple features, since it’s not ideal to import files directly between features. To solve this, I created an /entities folder that contains all the business logic and utils for each feature, so they can be imported wherever needed—even across different features.

How do you usually handle this? If you have numerous features (10–20), each with many files (hooks, API, components, constants, server actions, server queries, etc.) and some shared code, how do you organize it?

Thanks so much for the support you’ve been giving!

oh wait, I got a bit confused

Yes, you are right there might be circular dependency in that case.

I guess entities is a great option for shared logics

How do you usually handle this? If you have numerous features (10–20), each with many files (hooks, API, components, constants, server actions, server queries, etc.) and some shared code, how do you organize it?

For this really, What I'd do is I'd basically group features by a category or domain

for e.g. if a feature is finance related, I'd put it under the finance folder and so on, for each feature

and similarily for shared entities

I've seen certain packages also suggest the same, though its unrelated, discord.js template code for commands suggested us to group commands by features

Thanks a lot for your insights! I really appreciate it.
I’ll definitely take a closer look at the discord.js template, it sounds like a useful reference for organizing features and shared logic.

I wouldn’t suggest you to look at discordjs template much, as that’d be just an elementary level example compared to this case

I noticed that discord.js probably uses Turborepo, so the packages folder is mainly used to share files across multiple projects within the same repo.

I’ve attached an image of what I consider the “final” structure for my project. I’d love to hear your thoughts—how would you improve it?

I'd say its great enough, but I also recommend to use index.ts barrel files

which basically exports everything inside the folder/subfolders, so its easier to import

Yes, I use barrel files. I only removed them for the screenshot.

then its good to go

can u mark my message as a solution