Resource/context folder structure instead of structure based on file type

[paulcsmith]

Right now we have a structure that many frameworks have. This structure is based heavily on the type of file:

- src
  - actions
  - forms
  - queries

This can sometimes make it hard to find related files (query objects, service objects, etc.). It also makes it hard to tell at a glance what the application does and how things relate to one another (see "Other Advantages" below).

I've seen some applications handle this with "contexts" or "applications" that encapsulate different domains.

I've had a few issues with this approach though:

1. It is sometimes hard to tell what the context should be. For example should "users" be in an "accounts" context? What if a model is shared between multiple contexts. For example, a product might be part of a "store" context and an order "context". It is often not clear when you start what the contexts should be so I see a lot of "God contexts" that house a ton of different logic. I've also seen a lot of duplicated logic because it isn't clear where to look or where to put things.
2. It is hard to share code like models because there isn't a shared/common area for code

Proposed solution

I experimented with a few approaches and I think this would resolve the above issues.

1. Default convention is folder structure matches resource: Admin::Users::Index goes in src/admin/users/index.cr. Api::Users::Show goes in src/api/users/show.cr, etc.
2. Forms, queries and models go in src/common by default because they are often shared across boundaries. You can have more specific forms or queries in folder if you want.
3. Only if you want to: you can extract to something else (like src/store in the example below), but default (class name -> folder structure) is the way to start so you don't have to overthink things too early

  - src
    - common (or maybe "shared")
      - css
        - app.css
      - js
        - app.js
      - actions
        - browser_action.cr
        - api_action.cr
      - forms # forms go here by *default*
      - queries # queries go here by *default*
        - user_query.cr
      - models # models go here by *default*
        - user.cr
      - views (shared pages/layouts/components go here)
        - main_layout.cr
        - field_component.cr
    - users (by default, use the class name to group things. Easier to get started w/o overthinking things)
      - index.cr
      - show.cr 
      - user_form.cr
      - index_page.cr
      - show_page.cr
      - row_component.cr (put extracted HTML components here)
    - api
      - users
        - index.cr
        - index_serializer.cr
    - store (if you want, group everything in another folder like thid)
      - orders
        - index.cr
        - index_page.cr
        - etc
      - products
        - index.cr
        - etc

So default convention is:

1. Put actions, pages, components in a apps/features/contexts folder
2. The apps/features/context/whatver it is called folder is named after the resource by default. Makes it easy to get started without premature extraction
3. Put shared stuff like models, forms and queries in common

Other advantages:

I recently had an issue with a project where we were trying to figure out what was going on after records were imported. This took a day of digging to find all the workers and related code that was scattered across multiple folders. Here's what I would have loved to have done afterward:

- src
   - importing
     - api_client_for_third_party_service.cr
     - sync_agents
     - sync_images
     - other_stuf...

This makes it a lot easier to find related code without tracing method calls between your apps and stitching it all together in your head or writing a markdown doc of everything you've found

What do you think?

Thoughts/concerns about this approach? Any ideas for naming things?

[BlakeWilliams]

I really like this idea! I like how it's similar to a lot of the React applications I've worked on where the files are placed based on hierarchy.

That being said, what are your thoughts on this kind of file structure with less emphasis on the common/shared folder being special and instead just being a default folder to place shared code?

- app/
  - common/
  - users/
    - models
      - profile.cr
    - edit.cr

[paulcsmith]

@BlakeWilliams Thanks for the feedback! Could you explain a bit more what you mean by common/shared not being special? I didn't think it was but maybe I'm misunderstanding

[BlakeWilliams]

Sure! I think it's my assumption/misunderstanding here.

I assumed that since common and apps were different directories that they'd be treated differently. I think with how my brain works, I'd want common to be another "features"/"context" directory that's purely conventional so you could rename it, have a separate/more specific shared folder in some cases, etc.

Does that help clarify my thought process on it?

[paulcsmith]

Oh yes, I see what you mean. I agree with that. My only concern here is that that may require using require differently. The advantage of having common separate from apps is the the apps can be required a lot like this:

require "src/common/**" # Load common/shared stuff first
require "src/apps/**" # Load everything else after

That way any new folder you add to apps is required automatically.

Alternatively, if you had a folder structure like this:

- src
  - common
  - users
  - store

You'd have to manually require the feature folders. Maybe that is worth it though?

require "src/common/**" # Load common/shared stuff first
require "src/users/**" 
require "src/store/**" 

Thoughts?

[paulcsmith]

Or maybe it could be required like this...

require "something_that_needs_to_be_loaded_first.cr"
require "src/common/**"
require "src/**" # Load everything else after

Maybe that would be nice. The structure would look like this

- src
  - common
    - forms, actions, etc.
  - users
  - store
  - something_that_needs_to_be_loaded_first.cr

[jwoertink]

I've seen some frameworks that do weird structures like this as well, and I'm not a fan. Looking at a folder structure for an app shouldn't be where you look to see what the app does. It would be like looking under neath a car to see how fast it goes. This breaks convention because every app is going to function a bit different. Right now our largest Lucky app doesn't have users, or authentication, and our models have been abstracted in to a separate shard allowing us to use the same models across different apps. By segmenting all these directories out, the app becomes prone to a lot more duplication just from confusion of "this thing could go in this place and that place".

This can sometimes make it hard to find related files (query objects, service objects, etc.).

I'm not sure how. If you're looking for a service object, and you look in the services folder, it should be pretty easy to find, no? Plus, worst case is you bust out your grep fu 😛

I think a structure like you're proposing might be ok for brand new apps from the ground up, but porting over existing ones (like my company is doing) makes things a lot more difficult since it means re-architecting.

[BlakeWilliams]

Ah, I didn't even think about autoloading everything. For better or worse I was in a React mindset where you have to import everything you use explicitly. :)

I do like the idea of loading everything in common first, and then loading app code afterwards. I think your last suggestion, or your first suggestion are great (with the first suggestion meaning separate directories).

I'm not super familiar with the specifics and pitfalls of requiring dependencies in Crystal, but I could see having a file where you explicitly require your folders be nice in cases where load order is causing issues.

[paulcsmith]

@jwoertink Yeah I guess it isn't hard to find, but more that it is hard to find what is already made for an app. Part of me also just likes seeing things organized this way because it makes more sense to me.

the app becomes prone to a lot more duplication just from confusion of "this thing could go in this place and that place".

I think in this case it'd go in src/common. A lot of frameworks that have done this don't have a nice place or structure for shared stuff (IMO).

Luckily even if this structure changed it'd be super easy to use the old way because you just need to change a few lines in src/app.cr to load the folders you want.

I'm not 100% sold on this approach so I'd love to hear other opinions too. Maybe this could be optional? I don't love the idea of have two ways to structure things though 🤔

[jwoertink]

One thing to note about doing those mass glob requires is that there has been talk about removing that feature since it causes a lot of confusion (though, I really like having it). But the main reason was because in some cases you have to make sure you files are required in a specific order.

As for a question about this proposed structure, I have an app that has a user model. The user model has a flag to denote if the record is an admin. When logging in, if the user is admin, they are directed to an admin interface, and if they're a regular user, they go to a whole different members dashboard section. How would that structure look? Would there still be a users folder?

[paulcsmith]

@jwoertink Yeah I really hope they don't remove that, especially because there is no way to reference files relative to project root. If they do though you'd need to do the same require dance with either structure :(

I'd structure it like this probably:

- src
  - admin
    - products
      - index.cr
   - dashboards
     - show.cr

So pretty much the folders would match whatever the resource is. But I dunno, would that make sense in your case?

[jwoertink]

That would probably solve my case, but now it feels like each app is having to change its folder structure. So if I'm building apps for clients, each app I open I'm having to re-learn the structure of where things are in order to best suit the needs of that app. It feels very javascript/php to me.

Maybe we could look at some popular apps, and think about how they would be structured like Twitter, Youtube, Simple Blog, e-comm store, and something multi-tenant like Shopify (single engine, multiple domains). I think seeing something like that might help to clarify the concept like "If you wanted to build an app like A, then the structure would look like B".

[paulcsmith]

I am concerned about the same thing ("it feels like each app is having to change its folder structure"). But I also don't love putting things in folders by type because I think it can be hard to find what forms or service objects are intended to be used for which parts of the app. I also like the idea of having fewer deeply nested folders, e.g. src/users/index.cr instead of src/actions/users/index.cr. Small, but nice.

So if I'm building apps for clients, each app I open I'm having to re-learn the structure of where things are in order to best suit the needs of that app

I'm not totally sold on this point. I think the convention is:

1. Look in src/ and you'll see all the folders for the app
2. If you want to see pages, actions, etc. for users, look for src/users
3. If it isn't there, check src/common (for example src/common/models/user.cr)

What would you have to re-learn? I really am curious. Since I thought about this structure a lot it is hard to view it with fresh eyes!

I am still concerned about making it harder to developer because people have to overthink where to put things. I had that issue with Phoenix contexts. But I think the default for Lucky would be: folder structure should match the resource name. Extract to something else once you feel comfortable with a better name. But maybe that still is too much overhead?

I love the idea of what some sample apps would look like. Here's one I can think of that I've been working with:

- src
  - common
    - models
      - vehicle.cr
      - dealer.cr
      - customer.cr
    - queries
      - deal_query.cr
      - customer_query.cr
      - etc.
     - forms
       - vehicle_form.cr
  # These all have actions, pages, serializers, etc. in them that are specific to the resource
  - dealer
    - customers
    - vehicles
    - deliveries
  - admin
    - stores
    - customers
       - admin_customer_form.cr # Put more specific forms/queries in this folder, otherwise src/common
    - dealers
  - customers
    - valuations
    - trade_ins
 - api
   - customers
   - dealers

Or for GitHub

- src
  - organizations # multi-tenant but still uses structure that matches what the action is `Organizations::Show`
    - repos
  - repos
    - pulls
    - issues
  - users

So the basic structure here matches the route namespace by default. If you want you could group things differently maybe src/vehicles has an admin folder and dealer folder for example. But by default you just match your url routes. So Api::Customers::Index goes in src/api/customers/index.cr

Does that makes sense? What do you think about that?

[paulcsmith]

I also updated the original description to reflect this new class name -> folder name convention, along with examples. I also added another example of a recent problem I had on a project where I spent a lot of time tracking down which files and classes were used for a pretty complex part of the business

[perezperret]

I'm sorry I can't read through the whole thread right now, but wanted to pitch my 2 cents real quick. Hope there isn't too much repetition.

Another advantage I see in the apps/contexts approach is that you don't communicate a restriction on the type of objects you should have, which happens, for instance in Ruby on Rails, where people (mostly beginners) often feel it's not ok to add things outside of models, views and controllers.

On the other hand, I'm not sure if this convention also adds a little value to Rails, where it is relatively easy to write engines and plugins that can be modified by overriding models, views and controllers. I can't think of a way the apps/context approach hampers this extensibility, but it's something worth thinking about.

[jwoertink]

Ok, so actions and pages would fall under a resource, as opposed to a group? Where would static pages like /about or /robots.txt go? Would there be a resource or random actions with no pages, and another for random actions with static pages? Or would that just go in common? What about if you have pages that mix resources like a page that has reporting on it with reports of dealers and customers and vehicles all on the same page.

Also, would a brand new empty lucky app just generate a src folder, and then give a general guide as to what folders you should make? Almost like a padrino app where it's halfway between sinatra and rails? Well, I guess a src/common since it seems like that would always be there.

Assets would be tied to a resource/context too, right? So you'd have your customers related js in src/customers/assets/javascripts and your vehicles javascripts would be in src/vehicles/assets/javascripts? And then all your other common stuff like bootstrap.js would just be in src/common/assets/javascripts? @BlakeWilliams mentioned it was similar to some react apps, but I've never worked with a react app, so I'm not sure how they get structured in this case. 😕

[paulcsmith]

These are excellent questions that I hadn't thought of at all.

Ok, so actions and pages would fall under a resource, as opposed to a group

If I understand the question correctly, either one, but by default it would match the class name, which usually is named after the resource. Api::Users::Show goes in src/api/users/show.cr. You can optionally put it in a group if you want and if you feel that makes sense. But even then I'd probably use a class namespace so it would still match the class name, e.g. Store::Products::Show -> src/store/products/show.cr

Where would static pages like /about or /robots.txt go?

This is a tricky one for either file structure I think. In the current structure I guess I'd still make a group called src/actions/static/about.cr and src/actions/static/robots.cr or something. I'd do something similar with the apps/contexts structure. src/static/about_us.cr and src/static/robots.

Would there be a resource or random actions with no pages, and another for random actions with static pages?

I'm not sure I understand. Could you give an example of what you'd do in the current structure?

What about if you have pages that mix resources like a page that has reporting on it with reports of dealers and customers and vehicles all on the same page.

This is more confusing in the current structure I think because what I see most people do (myself included) is put the page in either one of the two folders, even though it belongs to both. Either that or I'd put it in src/pages/shared. In the new file structure I'd put it in src/common/pages/my_cool_report_page.cr. As soon as something is shared across folders I'd move it to src/common

Also, would a brand new empty lucky app just generate a src folder, and then give a general guide as to what folders you should make? Almost like a padrino app where it's halfway between sinatra and rails? Well, I guess a src/common since it seems like that would always be there.

It would generate the config files and src/common with the default layout files, default browser_action and api_action, etc. Also if you generate it with auth it will have folders like these:

- src
  - sign_ups
    - new.cr
    - new_page.cr
   - password_resets
    - new.cr
    - new_page.cr
   - sign_ins
    - new.cr
    - new_page.cr
   - etc.

Even without auth you'd have a home folder for the default page:

- src
  - home
    - index.cr

The generators would also use this new structure. For example lucky gen.action Admin::Users::New would generate an action in src/admin/users/new.cr. lucky gen.page Admin::Users::NewPage would go to src/admin/users/new_page.cr. The model generators would put stuff in src/common, e.g. lucky gen.model Product would put files in src/common/{forms, queries,models}

There would also be the new lucky gen.resource.browser that would generate pages, actions, forms, etc. for a resource that you could learn from.

Assets would be tied to a resource/context too, right? So you'd have your customers related js in src/customers/assets/javascripts and your vehicles javascripts would be in src/vehicles/assets/javascripts?

I'm not sure. I'd have to see how/if that would work with web pack, but I think that would be really nice to have JS files there. Of course once something is shared I'd move it to src/common/js though. I'd also put stuff like button css in src/common as well.

What do you think? Does that make sense?

[paulcsmith]

Thanks for your thoughts @perezperret

Another advantage I see in the apps/contexts approach is that you don't communicate a restriction on the type of objects you should have, which happens, for instance in Ruby on Rails, where people (mostly beginners) often feel it's not ok to add things outside of models, views and controllers

I hadn't thought of that! Great point.

On the other hand, I'm not sure if this convention also adds a little value to Rails, where it is relatively easy to write engines and plugins that can be modified by overriding models, views and controllers. I can't think of a way the apps/context approach hampers this extensibility, but it's something worth thinking about

Hmm I'm not sure. I'll keep that in mind though!

[jwoertink]

Ok, I'll say that I'm still not 100% sold, but I think it's a lot more clear to me now, and I can see how a different structure like that could be pretty nice. I think I'd have to actually build an app in that style to see where I run in to issues, and feel it out. I feel like it wouldn't be too bad, but obviously there's so many variables when it comes to building an app, that we could be missing some major hurdles.

Thanks for explaining!

[neurodynamic]

When I moved from building apps mostly with Rails to building apps mostly with Phoenix, contexts were one of the things I appreciated the most. That said, for me the biggest win wasn't the folder structure itself, it was the idea of having each context be an API surface. This felt like it massively simplified testing in particular, especially when dealing with a operations that involve multiple models changing or interacting in the same operation. Regardless of the complexity of what happened, there was always just one function that needed to be tested to see if that operation was working. Huge relief.

I don't know how hard or easy or canonical this would be in an object oriented language, but if this change in Lucky also made it easy to, for example, create a module for each context that served as an API surface for all the contained business logic, I think that would probably make a big positive difference for me.

[paulcsmith]

@jwoertink I'm glad that helped a bit, and I'm glad you brought all that up because it helped clarify things for me too. I'm not 100% sold on it yet either. Maybe I'll make the change and we can experiment with it. I'm totally fine rolling it back if we (the community) are finding it is more painful than helpful.

@neurodynamic Thank you for reaching out. I wasn't totally in love with contexts, but that may be just me. I do like the idea of having a simple interface that is easy to test. You can definitely do this in Lucky/Crystal using a module or a class. Forms were also made to encapsulate a lot of what you'd do in these operations. They are fairly simple to test, but I still need to write a guide on how to do it :) But you'd do something like this once the test helpers are done:

params = Lucky::Params.new(email: "paul@thoughtbot.com", password: "")
SignUpForm.create(params) do |form, user|
  form.password.errors.should eq ["is required"]
  WelcomeEmail.new(email: "paul@thoughtbot.com").should_not be_delivered
end

You could so something similar with a service object like Accounts::SignUp or something. Is that roughly what you meant?

[neurodynamic]

@paulcsmith That seems similar, yes. I should say that I'm speaking from a position of relative ignorance about Lucky itself, so it's possible I'm just missing the ways that what I want is already possible. I've been following the development interestedly, but I am still working primarily in Phoenix right now.

I also agree with you that contexts do complicate things in some ways as well in terms of decisions about which context a particular piece of functionality that might be ambiguous or shared should go in. Overall I have still preferred them to the Rails way of doing things, mostly because of how much more I enjoy testing with Phoenix, but I think the pros and cons you are citing are real.

[damianham]

I am a big fan of the Principle of Proximity so that any objects that are closely related should be placed together and those that are not related should be placed apart. In software development this leads to a structure where objects related to a particular feature are placed in a folder for that feature and unrelated objects are somewhere else. Software is developed in layers. A lower layer provides services to upper layers, i.e. shared objects provide services to feature objects. A User object is (usually) shared among features so it is a lower level object and would be placed in a common/core/shared folder hierarchy. Everything distinctly related to the xyz feature (models, actions, views, business logic, javascript, stylesheets) can be placed in the xyz folder. In practical terms in my (Amber) application my folder structure is

spec/

• controllers
• lib
• models
• modules
  • xyz
    src/
• assets
• controllers
• models
• views

All pretty standard so far (from an Amber/Rails perspective) but these folders only contain lower level objects that are used across the application or are not directly related to a feature

• lib - shared business logic and shared javascript , e.g

  • js - common/shared/core javascript libraries
  • patches - monkey patches to core language classes

• modules - a collection of application features (maybe in future I will call this features because that is what they are)

  • js - javascript objects that are shared between 2 or more features but are more feature related than core functions
  • abc - everything directly related to the abc feature only
    • js - javascript directly related to the abc feature only
  • xyz - ditto
  • profile - e.g. modifying a User profile is an application feature so User views etc. would be here

So if I am working on the abc feature, be it the api or the views or the javascript it is all located within the src/modules/abc folder. It is a toss up whether having javascript shared between one or more features should be in src/lib/js or src/modules/js - it doesn't matter a great deal as long as I am comfortable with the choice. I prefer src/modules/js because that is the upper level of features abc and xyz and is more conformant with the principle of proximity. I find there is no need for assets/javascripts in the pathname when the abbreviation 'js' is clearly well known and understood.

In contrast I recently worked on a Ruby on Rails contract that had a combined 2383 files in the codebase. To work on a feature I had to navigate around the source tree to find the place where a file was located that I wanted to view/edit and this involved looking in:

confile/locales/nl-BE
config/locales/nl-BE/production
test/unit/xyz
test/functional/xyz
app/controllers - 230 controllers
app/controller/production
app/helpers
app/models - 312 models
app/views/production/xyz
app/assets/stylesheets
app/assets/stylesheets/production
app/assets/templates
app/assets/templates/production
app/assets/templates/production/xyz
app/assets/javascripts/
app/assets/javascripts/production
app/assets/javascripts/backbone/views
app/assets/javascripts/backbone/views/production

Not to mention the 545 migrations in db. Suffice to say there was a great deal of scrolling and hunting involved. This project had started small - like so many Rails projects but had grown over the years into a huge monolith, and this was just the api and CMS. The customer facing frontend application was another 1181 files. In my structure I would reduce 14 folders to 1 folder. It is my view that once your application grows and you have invested so much time in a flat codebase structure it is more difficult to change to a more hierarchical and more easily managed structure. Therefore it is better to start with the right structure from the beginning as this proposal suggests. The only question for me is whether the feature folders are better in a src/(features|modules) folder or up a level as src/feature_name so that they align more closely with the URL. Having the the codebase organised in levels allows me import the levels in a specific order, e.g

require "src/lib/**"    # import lower level core objects
require "src/modules/**"  # import upper level features

If I was going to place feature folders directly in src rather than in a modules folder then I would probably create a features file in src and require that in my application file and require each module explicitly in the features file. Also when generating a new feature with the scaffold generator I would want the generator to add a require statement for the feature to the features file.

With regard to test suite objects I hope to one day get time to sort out a process so that when I modify a file in a feature folder an appropriate test process is started that tests that feature only and when a common/shared file is modified the whole test suite is run. I hope that this will also allow me to put the test suite objects for a feature in the same feature folder alongside the artifacts that implement the feature so that all of my application is modularized.

BTW we solved this modular application problem in Amber with support for recipes and creating a modular recipe. You might want to consider that route as it would also add a lot more to the Lucky framework while leaving the 'by object type' code organisation option for those that prefer the old school way :)

[mwlang]

One thing about learning a new language after living so long in another ecosystem (Ruby and Ruby on Rails in particular), one gets to take a step back and think about these issues from a fresh perspective.

One thing I loved about Ruby on Rails is convention over configuration. One thing I hated about Ruby on Rails was convention over configuration. :-)

Convention is great because:

• newcomers get started quickly.
• new projects are fast to start and ramp up.
• guides, blogs, and tutorial pieces all feel fairly familiar right away.

For these points, I love convention. What I hate about it:

• Reluctance to break outside the box.
• Shoehorning logic into places it doesn't belong (fat controllers, skinny models, convoluted views, anyone?).
• Not considering other effective patterns (MVVC, Service objects, etc.) that don't fit neatly into the conventions established.
• Lack of blog posts, tutorials, examples for more advanced use cases.

Not to get too far off topic, one thing I was looking at today as I built my first set of working pages in Lucky was the file structure we have. One thing I'm liking is that it's breaking out controllers, actions, and rendering in a way that encourages (Single Responsibility Principle)[https://en.wikipedia.org/wiki/Single_responsibility_principle] and (Separation of Concern)[https://en.wikipedia.org/wiki/Separation_of_concerns]. What I'm not liking is all the extra typing (and clicking on directory folders) to bring up the files to edit.

When I'm working on a feature, I'm typically highly focused on the full CRUD of the data being updated, so I'm thinking collectively about my controller, actions, and views all at once. One idea came to mind (and I'm not suggesting it's adopted here), which might help with this discussion: What about grouping by higher level concerns? For example, finding all the parts related to Users during authentication and profile management was quite a hurdle in this first Lucky project I'm working on and it made me immediately wish I had something like this:

- src
  - users
    - actions.cr
    - pages
       - index.cr
       - show.cr
       - new.cr
        - ...
  - profile
    - actions.cr
    - pages
      - index.cr
      - show.cr
      - ...

That is, for everything I'm going to hang off /users/..., I would house under the users folder. For anything with the account/profile of that user hanging off the /profile/... I would house under the profile folder.

Basically, the folder structure mimics the routes I'm matching them to. Anything shared can live in appropriate folders off the ./src folder. ./src/partials, ./src/layouts, ./src/controllers (where controllers here mean high-level ones like Public, Auth, and Admin), to which actions.cr files inherit from in the other sub-folders.

Another wording up above that caught my eye was "interfaces" The "public" (unauthenticated) interface, the Admin interface, the "private" (authenticated/logged in) interface. That immediately suggested to me another level to the basic folder structure that is basically /<concern_route>/[concern files]

If it's shared, it lives off an immediate subfolder of "./src/..." or "./src/shared/..." (a.k.a. "./src/common"). Otherwise, it's organized by feature/concern closely following the intended service route URL.

[testbird]

+1 For some default grouping by concern/route instead of file content.

May it make sense to also name the files with a "concern-prefix", by convention?, to also allow dropping all files in a single folder, or folders sorted however desired?

For example, I'd like omitting the /shared or /common subdir for just placing the common files in the parent folder.

Supporting "container" folders with files "shared" by subfolders could also be nice if there are many folders.

So just reading in all files from the entire tree, plus mapping e.g. all static/ or public/ ./public_html/ directories found somewhere in the tree into the root route, might be good.

[paulcsmith]

Hey @testbird! Thanks for chiming in. I'm having a hard time visualizing the suggestion. Could you share an example of what that file structure would look like, with some examples actions, models, etc?

[testbird]

Hi, hello everybody!
I can second that a good, logical, modular, and flexible structure is really worth a lot!

New to this, I can't say very much concerning a specific optimal default structure, only that I do (currently?) prefer folders that group files that "belong together" instead of by "type".

Concerning specific things to consider, I can only, and really like to recommend two examples I still remember years later, as having been extremely well thought out. [Minutes spend might make things easier later (modules, content level files,...?) ]
https://web.archive.org/web/20160424053516/http://zenadmin.org/en/documentation/Wiki/list334.html (It's the templating level (created on top of rails) there, but good ideas could already be applied more basically.)
https://neos.readthedocs.io/en/stable/References/CodingGuideLines/PHP.html#naming (many aspects, module compat, shipped, vendor, local, ...)

The ideas I had, were independent from whichever structure may be best for a default or for particular (example) apps. Actually they are rather allowing for adaptions by the users, however it may fit them (the possibility to override everything).

Basics

• File extension already determine file type, further specification within the file.
• Rely on file content containing authoritative namespace identifiers (for self and references)
• Let files rely on a maximally universal file inclusion / parsing method, instead of absolute path inclusions (next paragraph).

Make folder structure modifiable for different purposes, by keeping it optional.

• For full flexibility, allow to drop all files in a single directory (flat files, minimal example)
• A nice default flle naming convention makes this possible without conflict. (For example, <class>_<some-thing>_<some-sub-form-or-mode>.cr for code (again optional).
• Static files may be added in any folder position, by placing them below a ./pubilc_html/ subdirectory in any folder.

Does it make some sense?

Should pretty much allow to put and move the files in any custom structure, not withstanding a default structure..

[testbird]

Example:
If the file src/actions/profile/show.cr
becomes src/actions/profile/profile-action-show.cr,
such files could be freely placed in other default structure schemes, or a custom directory structure, while all profile related files etc. would still be grouped together due to the name beginning with profile-*.