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?

[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?

[scheidtdav]

I started to collect a target directory structure from our discussions:

frontend
├── .github
├── app/
│   ├── components/                 reusable UI components like buttons, alerts, etc.
│   ├── emails/                     email templates
│   ├── routes/                     pages and layouts making up the application using the components
│   |   ├── api/                    api routes
│   |   ├── device/                 /device routes
│   |   ├── ...
│   ├── lib/                        shared utility / 3rd party code that "does stuff"™️
│   ├── services/                   domain-specific stuff, business logic like a measurement service
│   ├── models/                     mostly plain types, interfaces, classes, schemas (not database)
│   ├── db/                         app-related database specifics
│   |   ├── drizzle/
│   |   |   ├── meta/
│   |   |   ├── 0000_xyz.sql
│   └── index.js.map
├── scripts
│   ├── db/                         database utility scripts (e.g. seed)
│   |   ├── migrate.ts
│   |   ├── seed.ts
│   |   ├── ...
├── tests/                          follows the structure of app/ for tests of corresponding file(s)
│   ├── components
│   ├── routes
│   |   ├── api
│   |   ├── ...
│   ├── lib
│   ├── ...
└── ...

Happy to hear your two cents @zven and @jona159 .
Are we missing something?

Some implications this would have:

• we remove mocks for now
• Dockerfile go to the root, other folder will be deleted (people expect to do docker compose up -d from the root)
• public probably needs a clean up
• types/ would be removed and corresponding files either go to models/ or will be colocated with the code using it

Looking forward to your ideas!

[zven]

Looks good to me! 🤓