Docs: Explain the intended usage of respositories and services

[ghferrari]

Summary

This package looks very useful but it is (as I'm sure you know) missing some essential documentation. In particular, it would be useful to have more documentation about repositories and services and their intended use cases. I've browsed through the litestar-fullstack application, which uses both, and it's not especially clear to me what are the different intended use cases of each. Not sure if I'm missing some essential background knowledge here that would make the difference clearer, but if so, it would be nice to have it explained. Thanks for listening!

[Seemone]

I agree it's not clear. My take is that repositories handle the DB representation of data on the DB backend, and thus deal with data. Services, in turn, handle what is being done with the data itself, so they are geared towards the controllers

[ghferrari]

As a follow up, I've since spent some time with other API frameworks which also distinguish between between repositories and services, so I suspect the authors are to some extent relying on this terminology already being understood.

For those that don't understand it, I'd describe it something like this:

• Repositories are there to provide a suite of relatively low-level database access functions. Essentially they provide methods for pure database queries and updates.
• Services are there to provide higher-level business logic, which at least sometimes might combine multiple repository queries, together with connections to external resources, as well as business logic that isn't captured simply in the database schema.

So in a typical application, you might define the repository layer, then a service layer which calls the repository layer as well as any other external services or other business logic tools. Finally, the controller layer will call the service layer (but not the repository directly).