How 0xtheprodev/fastapi-clean-example works
Main Components
• Main Entry Point: The main.py file is the entry point that wires up the FastAPI application.
• Routers: Located under the “routers” directory (with versioning under routers/v1), these modules define the REST endpoints for Authors and Books.
• GraphQL Schemas: Inside the “schemas/graphql” directory, these files define the GraphQL types, queries, and mutations.
• Business Logic (Services): The “services” directory encapsulates the core business logic for Authors and Books.
• Data Access (Repositories): The “repositories” directory implements the Repository Pattern. It abstracts data handling and storage mechanics for the different entities.
• Domain Models: Found in the “models” directory, these files outline the database or domain representation (including relationships like BookAuthorAssociation).
• Configurations: The “configs” directory holds setup information for Database connections, GraphQL configuration, and environment settings.
• Metadata & Schemas (Validation): The “metadata” and “schemas/pydantic” directories provide extra context and request/response validation using Pydantic.
• Testing: While not a runtime part of the architecture, the __tests__ directory shows where unit tests for services and repositories reside.
Relationships and Interactions
• The FastAPI entry (main.py) initializes the application and loads configurations.
• Routers (REST endpoints) route incoming HTTP requests to their corresponding service methods.
• Services implement the business logic; they are invoked by the routers and, in turn, call the repositories for data persistence or retrieval.
• Repositories abstract the underlying data access layer and interact with the models which represent the database schema.
• GraphQL endpoints similarly leverage GraphQL schemas which connect to business logic, potentially reusing the same service or repository classes used for REST.
• Configurations are referenced throughout to provide environmental settings (such as database connections), while metadata supplements the domain logic.
Architectural Patterns and Design Principles
• Hexagonal (Clean) Architecture: The system is designed to separate the core business logic (services and models) from external concerns (routers, GraphQL interface, database configurations).
• Repository Pattern: To abstract data access and provide a consistent interface for interacting with domain models.
• Separation of Concerns: Each layer (routers, services, repositories, configurations) is decoupled, making the system easier to test and maintain.
• Use of Pydantic: For schema validation and type checking, found in the “schemas/pydantic” portion.
Technologies, Framework, and Libraries
• FastAPI: The underlying framework that provides asynchronous web handling and OpenAPI integration.
• Uvicorn: The ASGI server used to run the application.
• GraphQL: Enabled via dedicated schemas for flexible API interactions.
• Pydantic: For data validation within request/response schemas.
• Pipenv: Used for dependency management.
• Python 3 and standard testing frameworks (unittest, pytest) for test automation.
• Start at the top with the “Client” (representing API consumers that access REST endpoints or GraphQL).
• Next, from “Services,” branch out to “Repositories” which then connect to “Domain Models.”
• On the side, place “Configs” that supply necessary settings (database, environment, GraphQL config) to appropriate components.