Project Structure and File Locations

[scheidtdav]

In order to make the entire project more accessible to anyone willing to contribute, the project needs a more obvious and straight forward structure and corresponding documentation for it.

As an example it is unclear where to put zod schemas for certain endpoints and as a result they are scattered around the project with no obvious place to put it.

Happy to use this discussion to work out a structure and documentation!

[zven]

Let's start with some observations, before coming up with solutions:

• app seems to be the main ui folder
• db + drizzle are both database related
• emails contains email templates: Is that the only location?
• Why do we have an other folder?!
• scripts contains only one script: Is that truly the only "loose" script we have?
• types: contains only one file with one interface

---

in app folder:

• components:
  • some generic ui elements on top level but also folders containing generic elements (e.g. spinner which, in turn, contains only a single file)
  • ui does also contain generic elements that are used in other components
• lib does also contain api-schemas folder (with only one API schema file that also contains functionality)
• models contains models (haha)
• routes contains all the (api) routes
• schema contains scheme files
• How is the lib folder different from the utils folder?

[zven]

I think the biggest decision is if we ant to organize our project based on features, around separation of concerns or a mix of both:

Approach	Typical top‑level folders	When it shines
Feature‑first (domain‑driven)	app/ → features/ (or modules/) → each feature contains its own components/, routes/, hooks/, utils/, styles/	Large apps with many distinct domains (e.g. dashboard, auth, admin). Keeps everything related to a feature together, making it easy to move or extract a feature.
Layered (separation‑of‑concerns)	app/ → components/, pages/ (or routes/), services/, hooks/, utils/, styles/	Smaller to medium projects that prefer a clear vertical split (UI vs. data vs. helpers). Easier for newcomers to locate “type of thing”.
Hybrid	Combine the two: top‑level feature folders for the biggest domains, and shared layers (ui/, lib/, hooks/) for cross‑cutting concerns	When a few core domains dominate but you still have a lot of reusable UI or utilities.

[scheidtdav]

Thanks for the summary!

To find a good decision, lets quickly analyze osem.
For a feature-first approach, we need to identify the features:

• landing page
• exploration
  • this could possibly be broken down even further?
• user profile
• user settings
• device creation
• device settings
• API

Dicussion question: Is this already "many" distinct domains? Are they really that disctinct? Device creation and settings e.g. share database models and possibly code. The api is not really distinct is it? It is a way of using all the features without the ui, right?

For layered approach, lets identify our layers:

• app
  • components: the stuff that builds our pages
  • routes
    • api
    • pages
  • lib: shared code that "does stuff"™️, unspecific like validLngLat()
  • services: domain-specific stuff, business logic like a measurement service
  • models/ schema: in the original sense, mostly plain types or interfaces
  • db: drizzle specific things

Discussion question: Is this "easier to locate things"? I think we are quite close to this already, so it might be the lowest hanging fruit, what do you think?

What about hybrid?
Well imho it can be applied where necessary.
Say a component provides a context and thus acts as a HOC, shouldn't that context be next to the component?
Generally I'd argue components should be single-filed and self-contained. In this case, I would create a folder for the component to also place the context there.

There is some sort of organization to be done outside of the app folder, but that might come later ;-)

When asked for my vote, I'd go with layered (hybrid layered possibly), as it seems to be the lowest hanging fruit right now and most people are comfortable with it.
Totally open for opinions though.

Opinion: Let's not use "utils" nor "helpers" please. In my experience these tend to be a junkyard for code that should be placed elsewhere and introduces easy ways of getting things to work but not on maintaining them.
You can almost always come up with a more specific name of what can be found in a file and what it can and cannot do.
Utils are more like pandoras box, accumulating code over time and worst-case being hard to remove.
They are usually either part of the business logic or you can clearly assign a "type of thing they do" and should therefore name it that way.

[zven]

A cleaned up, layered (hybrid, where meaningful) structure sounds good to me! 👍

Strong opinion: Let's clean up / eliminate "utils" and "helpers"! Sooner or later, those "utility" functions are used all over the place and suddenly contain crucial, yet somehow hidden business logic. Sometimes, different util functions depend on each other and a change in one place screws up things in unexpected places.

[zven]

Can we turn this into an issue, then?