Blog
Project Structure in Umami codebase - Part 1.1

Project Structure in Umami codebase - Part 1.1

Inspired by BulletProof React, I applied its codebase architecture concepts to the Umami codebase.

This article focuses on files and folders structure to understand the project structure and how its organized.

Prerequisite

  1. Project Structure in Umami codebase — Part 1.0

In this part 1.1, we review the following folders:

  1. src

  2. app

src folder

src folder has the following folders inside it:

Umami is a Next.js based project. You can confirm by looking at umami/next.config.ts. So, this src folder contains app folder that has the routes used in the Umami web app.

lang folder has JSON files supporting different languages. 

assets folder contains a bunch of svg files.

In the components folder, you will find the hooks and UI components.

lib folder has files named after their responsibilities, following the single responsibility principle.

permissions folder is about access control.

queries folder has prisma and sql folders, indicating it contains DB queries.

store folder is used to manage the client side state.

styles folder contains two files — global.css and variables.css

tracker folder has some tracking related files

declaration.d.ts folder has some modules declared.

index.ts exports some components from the app folder.

this src section outlined what each folder does, at a high level. We will review these folders one by one, keep reading.

app folder

app folder is the Next.js app router folder. It contains all the routes that you use on Umami.

In the Next.js app router, you have concepts like Route Groups, Dynamic Routes etc., We will see which of these Next.js rounting concepts are used in Umami’s app folder.

Route groups

You will find that below two folders are route groups defined in the app folder

  1. (collect)

  2. (main)

Learn more about Route Groups.

Dynamic Routes

You will find the below dynamic route in the app folder

  1. share/[…shareId]

Learn more about Dynamic Routes.

Then there is routes like login, logout, sso that could be grouped into (auth)?

Umami uses api folder to handle API calls. We will look at the API layer in the later articles at great detail by digging into the Umami source code.

Conclusion

We reviewed src folder contents, we saw folder like app, components, store, queries, performance, lang etc., all specific to their responsibilities, with a clear separation of concern.

In the app folder, we saw that Umami leverages Next.js route grouping and the dynamic routes. I also suggested how login, logout and sso routes can be grouped into (auth) folder.

About me:

Hey, my name is Ramu Narasinga. I study codebase architecture in large open-source projects.

Email: ramu.narasinga@gmail.com

I spent 200+ hours analyzing Supabase, shadcn/ui, LobeChat. Found the patterns that separate AI slop from production code. Stop refactoring AI slop. Start with proven patterns. Check out production-grade projects at thinkthroo.com

References:

  1. https://github.com/umami-software/umami/blob/master/next.config.ts

  2. https://github.com/umami-software/umami/tree/master/src

  3. https://umami.is/

  4. https://github.com/umami-software/umami/tree/master/src/app

  5. https://nextjs.org/docs/app/getting-started/project-structure#dynamic-routes

  6. https://nextjs.org/docs/app/getting-started/project-structure#route-groups-and-private-folders