backend code layout: maybe group by resources

[mgfinch]

IMHO, the current layout is not very practical for adding new / removing resources, therefore I would like to suggest differently pivoted organization of code.

I think most people will continue from this cookiecutter by adding / removing resources like Items and Users.

Example usecase

Lets say that apart from Users and Items you want to add Ideas to your app.
Currently you need to visit each directory: api, crud, db, db_models, tests/* and add the file named idea(s).py.

Maybe you start to think that the Ideas are better and you want to get rid of Items now...

Suggested layout

• /users/

  • __init__.py
  • model.py
  • db.py
  • api.py
  • crud.py
  • utils.py

• /items/

  • __init__.py
  • model.py
  • db.py
  • api.py
  • crud.py

• /tokens/

  • ...

• tests should be structured analogically

I am not yet sure how other parts should be layed out, but I would try to squash remaining files in now almost empty subpackages to core.

What do you think?

[dmontagu]

I agree with this point -- I think the current organization makes it harder to build composable units of functionality (e.g., an auth system) that can be reused since you need to grab files from many places. (But maybe that's more of an issue of not being more intentional about it at the outset.)

I'm not sure what the ideal organization is -- you'd probably still want a place to put endpoints, etc., that touch multiple resources. But I think this point is definitely worth considering.

[omrihar]

I'm also spending some time thinking about the best layout, and I have been thinking along similar lines. It could make it much easier to add more resources. A different approach we're looking into is using a template to generate all these files in their respective directories. But the templating approach would work in either case.

[dmontagu]

Yeah, it would be nice to be able to easily generate resources in a modularity-oriented set of files. On that note, I would be especially interested in something that could generate pydantic and sqlalchemy models together! Or at least, an XCreate and XInDB model from a sqlalchemy model X (default behavior: all fields optional on the Create, all fields required on the InDB).

[tiangolo]

Thanks for the discussion here!

Yeah, for some cases where sections are clearly separated it would probably be better to have them separated by the specific feature/resource.

But there are also many use cases that require references across different parts of the application, for example "add user John's note to the board X", should the crud utils for that live under "notes", "boards", "users"?

And if another of the components needs to access the same utils, would it import them from that external component? How would one decide on which component to put that logic, so that when other team members come looking for that, they also find it instead of re-implementing it in the other component?

Of course, there are many use cases that would benefit from your proposed structure, and the current one wouldn't be ideal for them, but it would probably still "work". Nevertheless, the new structure would probably make some use cases more cumbersome.

That's also why I've tried to keep this project relatively simple so that you can remove entire sections easily and add your preferred style. That's also why I haven't made any of the code in this project available as a third-party package or similar, because I don't think it's the "best" solution, or that it would apply for all the use cases, but it's a somewhat acceptable starting point 🤷 😅

In fact, I think I would like to simplify some parts of this project, to make it easier to discard and/or refactor entire sections, to simplify the Docker Compose files, even if that means some duplication, etc.

[github-actions]

Assuming the original issue was solved, it will be automatically closed now. But feel free to add more comments or create new issues.