How to use this

copier copy . <target_path_of_create_project>

API Architecture

Database

1. SQLAlchemy base model with auto-generated __tablename__ and type_annotation_map for more strict python to SQL type conversion.
2. Local database session defines on reusable database pools.
3. Custom types (with type keyword - python 3.12+) which require custom mapping in type_annotation_map.
4. Generic mapped_column helpers.

Repositories

1. All basic CRUD repositories defined as generic methods.
2. Works as a layer to communicate with database only.

Services

1. Generic services are in line with corresponding CRUD repositories.
2. Adding to repositories layers with data validation, exceptions handling and logging.
3. Errors are handled by using @handle_exceptions decorator, which use single dispatch pattern. All missing exceptions should be handled in app/utils/exceptions.py like:

@handle_exception.register
def _(exc: YourCustomException, _: str) -> HTTPException:
    return HTTPException(status_code=404, detail={your details})

Sub-applications models

1. Should use just Mapped. If mapped_column is needed, it's better to create new generic helper in app/database.py.

Sub-applications services

1. Both concrete repositories and services should be created from generic instances. All additional methods should be defined here. If repositories needs to be splitted into different modules, it's suggested to use inheritance and keep all the methods in one repository class.

Sub-applications views

1. API endpoint, which use services to perform operations.
2. Services return SQLALchemy models, but @router.HTTP_METHOD decorator should use response_model parameter to automatically transform them into pydantic models (which should be defined in sub-application schemas.py).
3. @format_response decorator (which is implemented using decorator factory pattern in app/utils/api_utils/py) transforms pydantic object response into JSONResposne with HATEOAS links attached to create RESTful API.
4. Additional relations (like user_rels in the example) will be added to HATEOAS links.
5. Default status code is 200. If another is required, should be defined in both decorators (@router add information to swagger docs, while @format_response make sure it will be status code returned by an endpoint).