{"id":25750638,"url":"https://github.com/walber-vaz/learn_clean_arch_fastapi","last_synced_at":"2026-05-14T17:39:51.443Z","repository":{"id":279239395,"uuid":"938152525","full_name":"walber-vaz/learn_clean_arch_fastapi","owner":"walber-vaz","description":"Estudos sobre Arquitetura limpa usando fastapi","archived":false,"fork":false,"pushed_at":"2025-02-24T14:23:24.000Z","size":64,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-24T15:31:24.918Z","etag":null,"topics":["clean-architecture","fastapi","poetry","sqlmodel"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/walber-vaz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-24T14:01:23.000Z","updated_at":"2025-02-24T14:23:27.000Z","dependencies_parsed_at":"2025-02-24T15:31:41.243Z","dependency_job_id":"e4d70de3-f7f9-4ee9-b76f-6f1ea3bb6535","html_url":"https://github.com/walber-vaz/learn_clean_arch_fastapi","commit_stats":null,"previous_names":["walber-vaz/learn_clean_arch_fastapi"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walber-vaz%2Flearn_clean_arch_fastapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walber-vaz%2Flearn_clean_arch_fastapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walber-vaz%2Flearn_clean_arch_fastapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/walber-vaz%2Flearn_clean_arch_fastapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/walber-vaz","download_url":"https://codeload.github.com/walber-vaz/learn_clean_arch_fastapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240858553,"owners_count":19869001,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clean-architecture","fastapi","poetry","sqlmodel"],"created_at":"2025-02-26T13:18:16.443Z","updated_at":"2026-05-14T17:39:51.436Z","avatar_url":"https://github.com/walber-vaz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Projeto FastAPI com Clean Architecture\n\nUma aplicação web moderna construída com FastAPI, SQLModel e princípios de Clean Architecture.\n\n## Visão Geral da Arquitetura\n\nEste projeto segue os princípios da Clean Architecture para manter a separação de responsabilidades e garantir testabilidade e manutenibilidade.\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                     Camada de Apresentação              │\n│                                                         │\n│  ┌─────────────────┐          ┌───────────────────┐     │\n│  │   Controllers   │          │      Schemas      │     │\n│  └─────────────────┘          └───────────────────┘     │\n└───────────────────────────────────────────────────┬─────┘\n                                                    │\n                                                    ▼\n┌─────────────────────────────────────────────────────────┐\n│                     Camada de Use Cases                 │\n│                                                         │\n│  ┌─────────────────┐    ┌──────────────────────┐        │\n│  │   Casos de Uso  │    │  Interface de Casos  │        │\n│  └─────────────────┘    │        de Uso        │        │\n│                         └──────────────────────┘        │\n└───────────────────────────────────────────────────┬─────┘\n                                                    │\n                                                    ▼\n┌─────────────────────────────────────────────────────────┐\n│                     Camada de Domínio                   │\n│                                                         │\n│  ┌─────────────────┐    ┌───────────────┐               │\n│  │    Entidades    │    │ Interfaces de │               │\n│  └─────────────────┘    │  Repositório  │               │\n│                         └───────────────┘               │\n│                                                         │\n└──────────────────────────────┬──────────────────────────┘\n                               │\n                               ▼\n┌─────────────────────────────────────────────────────────┐\n│                  Camada de Infraestrutura               │\n│                                                         │\n│  ┌─────────────────┐    ┌───────────────────────┐       │\n│  │  Configuração   │    │   Implementações de   │       │\n│  │   do Banco      │    │      Repositório      │       │\n│  └─────────────────┘    └───────────────────────┘       │\n│                                                         │\n│  ┌─────────────────────────────────────────────┐        │\n│  │               Dependências                  │        │\n│  └─────────────────────────────────────────────┘        │\n└─────────────────────────────────────────────────────────┘\n```\n\n### Test coverage\n\nOs estão em desenvolvimento, mas já é possível ver a cobertura de testes.\n\n```\nAll checks passed!\n================ test session starts =================\nplatform linux -- Python 3.13.2, pytest-8.3.4, pluggy-1.5.0\ncachedir: .pytest_cache\nconfigfile: pyproject.toml\ntestpaths: tests\nplugins: order-1.3.0, anyio-4.8.0, cov-6.0.0, asyncio-0.25.3\nasyncio: mode=Mode.AUTO, asyncio_default_fixture_loop_scope=session\ncollected 38 items\n\ntests/unit/infrastructure/repositories/test_sqlmodel_user_repository.py::test_create_user PASSED\ntests/unit/presentation/controllers/test_create_user_user_controller.py::test_create_user_endpoint PASSED\ntests/unit/presentation/controllers/test_get_user_user_controller.py::test_get_user_success PASSED\ntests/unit/presentation/controllers/test_list_users_user_controller.py::test_list_users_endpoint PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_create_request_valid_data PASSED\ntests/unit/use_cases/user/test_create_user.py::test_create_user_use_case_success PASSED\ntests/unit/use_cases/user/test_get_user.py::test_get_user_use_case_success PASSED\ntests/unit/use_cases/user/test_list_users.py::test_list_users_use_case_success PASSED\ntests/unit/infrastructure/repositories/test_sqlmodel_user_repository.py::test_find_by_email PASSED\ntests/unit/presentation/controllers/test_create_user_user_controller.py::test_create_user_endpoint_value_error PASSED\ntests/unit/presentation/controllers/test_get_user_user_controller.py::test_get_user_not_found PASSED\ntests/unit/presentation/controllers/test_list_users_user_controller.py::test_list_users_empty PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_create_request_invalid_name_characters PASSED\ntests/unit/use_cases/user/test_create_user.py::test_create_user_use_case_email_already_exists PASSED\ntests/unit/use_cases/user/test_get_user.py::test_get_user_use_case_user_not_found PASSED\ntests/unit/use_cases/user/test_list_users.py::test_list_users_use_case_empty_result PASSED\ntests/unit/infrastructure/repositories/test_sqlmodel_user_repository.py::test_list_users PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_create_request_short_name PASSED\ntests/unit/use_cases/user/test_list_users.py::test_list_users_use_case_exact_page_size PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_create_request_short_password PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_create_request_password_no_uppercase PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_create_request_password_no_digit PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_create_request_password_no_special_character PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_update_request_empty PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_update_request_name_only PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_update_request_email_only PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_update_request_password_only PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_update_request_all_fields PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_update_request_invalid_name_characters PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_update_request_short_name PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_update_request_name_capitalization PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_update_request_invalid_email PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_update_request_short_password PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_update_request_password_no_uppercase PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_update_request_password_no_digit PASSED\ntests/unit/presentation/schemas/user/test_request.py::test_user_update_request_password_no_special_character PASSED\ntests/unit/domain/entities/test_user.py::test_user_entities_creation PASSED\ntests/unit/infrastructure/security/test_password.py::test_password_hash PASSED\n\n---------- coverage: platform linux, python 3.13.2-final-0 -----------\nName                                                              Stmts   Miss  Cover\n-------------------------------------------------------------------------------------\nsrc/app/__init__.py                                                   0      0   100%\nsrc/app/constants.py                                                 12      0   100%\nsrc/app/domain/__init__.py                                            0      0   100%\nsrc/app/domain/entities/__init__.py                                   3      0   100%\nsrc/app/domain/entities/user.py                                      14      0   100%\nsrc/app/domain/repositories/__init__.py                               0      0   100%\nsrc/app/domain/repositories/user_repository.py                       13      0   100%\nsrc/app/infrastructure/__init__.py                                    0      0   100%\nsrc/app/infrastructure/config/__init__.py                             0      0   100%\nsrc/app/infrastructure/config/database.py                            12      3    75%\nsrc/app/infrastructure/config/settings.py                             8      0   100%\nsrc/app/infrastructure/dependencies/__init__.py                       0      0   100%\nsrc/app/infrastructure/dependencies/user_dependencies.py             11      0   100%\nsrc/app/infrastructure/repositories/__init__.py                       0      0   100%\nsrc/app/infrastructure/repositories/sqlmodel_user_repository.py      26      0   100%\nsrc/app/infrastructure/security/__init__.py                           0      0   100%\nsrc/app/infrastructure/security/password.py                           6      0   100%\nsrc/app/main.py                                                       5      0   100%\nsrc/app/presentation/__init__.py                                      0      0   100%\nsrc/app/presentation/controllers/__init__.py                          0      0   100%\nsrc/app/presentation/controllers/user_controller.py                  30      0   100%\nsrc/app/presentation/schemas/__init__.py                              0      0   100%\nsrc/app/presentation/schemas/common/__init__.py                       0      0   100%\nsrc/app/presentation/schemas/common/pagination.py                    13      0   100%\nsrc/app/presentation/schemas/user/__init__.py                         0      0   100%\nsrc/app/presentation/schemas/user/request.py                         45      0   100%\nsrc/app/presentation/schemas/user/response.py                        10      0   100%\nsrc/app/use_cases/__init__.py                                         0      0   100%\nsrc/app/use_cases/interfaces/__init__.py                              0      0   100%\nsrc/app/use_cases/interfaces/use_case.py                              7      0   100%\nsrc/app/use_cases/user/__init__.py                                    0      0   100%\nsrc/app/use_cases/user/create_user.py                                26      0   100%\nsrc/app/use_cases/user/get_user.py                                   18      0   100%\nsrc/app/use_cases/user/list_users.py                                 23      0   100%\n-------------------------------------------------------------------------------------\nTOTAL                                                               282      3 99%                                                              294     38    87%\n```\n\n## Características\n\n- Padrão de design Clean Architecture\n- FastAPI para desenvolvimento de API de alto desempenho\n- SQLModel para operações de banco de dados com segurança de tipos\n- Docker e Docker Compose para fácil implantação\n- Poetry para gerenciamento de dependências\n- Banco de dados PostgreSQL\n\n## Primeiros Passos\n\n### Pré-requisitos\n\n- Python 3.13+\n- Docker e Docker Compose\n- Poetry\n\n### Instalação\n\n1. Clone o repositório:\n\n```bash\ngit clone https://github.com/walber-vaz/learn_clean_arch_fastapi.git\ncd learn_clean_arch_fastapi\n```\n\n2. Instale as dependências:\n\n```bash\npoetry install\n```\n\n3. Inicie o ambiente de desenvolvimento:\n\n```bash\ndocker-compose up -d\n```\n\n4. Execute a aplicação:\n\n```bash\npoetry run uvicorn src.app.main:app --reload\n```\n\n5. Acesse a documentação da API:\n\n```\nhttp://localhost:8000/docs\n```\n\n## Estrutura do Projeto\n\n```\n.\n├── alembic.ini\n├── compose.yml\n├── Dockerfile\n├── .editorconfig\n├── .gitignore\n├── LICENSE\n├── poetry.lock\n├── .pre-commit-config.yaml\n├── pyproject.toml\n├── .python-version\n├── README.md\n├── requirements-dev.txt\n├── requirements.txt\n├── migrations\n│   ├── env.py\n│   ├── README\n│   ├── script.py.mako\n│   └── versions\n│       └── b4d2e3210ead_init.py\n├── postgres\n│   ├── create-databases.sh\n│   └── Dockerfile\n├── src\n│   └── app\n│       ├── constants.py\n│       ├── main.py\n│       ├── domain\n│       │   ├── entities\n│       │   │   └── user.py\n│       │   └── repositories\n│       │       └── user_repository.py\n│       ├── infrastructure\n│       │   ├── config\n│       │   │   ├── database.py\n│       │   │   └── settings.py\n│       │   ├── dependencies\n│       │   │   └── user_dependencies.py\n│       │   ├── repositories\n│       │   │   └── sqlmodel_user_repository.py\n│       │   └── security\n│       │       └── password.py\n│       ├── presentation\n│       │   ├── controllers\n│       │   │   └── user_controller.py\n│       │   └── schemas\n│       │       ├── common\n│       │       │   └── pagination.py\n│       │       └── user\n│       │           ├── request.py\n│       │           └── response.py\n│       └── use_cases\n│           ├── interfaces\n│           │   └── use_case.py\n│           └── user\n│               ├── create_user.py\n│               ├── get_user.py\n│               └── list_users.py\n└── tests\n    ├── conftest.py\n    ├── mocks\n    │   └── user.py\n    └── unit\n        ├── domain\n        │   └── entities\n        │       └── test_user.py\n        ├── infrastructure\n        │   ├── repositories\n        │   │   └── test_sqlmodel_user_repository.py\n        │   └── security\n        │       └── test_password.py\n        ├── presentation\n        │   ├── controllers\n        │   │   ├── test_create_user_user_controller.py\n        │   │   ├── test_get_user_user_controller.py\n        │   │   └── test_list_users_user_controller.py\n        │   └── schemas\n        │       └── user\n        │           └── test_request.py\n        └── use_cases\n            └── user\n                ├── test_create_user.py\n                ├── test_get_user.py\n                └── test_list_users.py\n```\n\n## Camadas da Clean Architecture\n\n### Camada de Domínio\n\nO núcleo da aplicação, contendo:\n\n- **Entidades**: Objetos de negócio\n- **Interfaces de Repositório**: Interfaces abstratas para acesso a dados\n- **Casos de Uso**: Regras de negócio específicas da aplicação\n\n### Camada de Infraestrutura\n\nLida com preocupações externas:\n\n- **Implementações de Repositório**: Implementações concretas das interfaces de repositório\n- **Configuração de Banco de Dados**: Configuração de conexão e gerenciamento de sessão\n- **Dependências**: Injeção de dependências para casos de uso e repositórios\n\n### Camada de Apresentação\n\nLida com requisições e respostas HTTP:\n\n- **Controllers**: Endpoints de API\n- **Schemas**: Modelos de dados para Requisição/Resposta\n\n## Desenvolvimento\n\n### Adicionando uma Nova Entidade\n\n1. Crie a entidade em `domain/entities/`\n2. Defina a interface do repositório em `domain/repositories/`\n3. Implemente os casos de uso em `domain/use_cases/`\n4. Adicione a implementação do repositório em `infrastructure/repositories/`\n5. Adicione as dependências em `infrastructure/dependencies/`\n6. Crie os schemas em `presentation/schemas/`\n7. Adicione o controller em `presentation/controllers/`\n\n### Executando Testes\n\n```bash\npoetry run pytest\n```\n\n## Implantação\n\nA aplicação está containerizada para fácil implantação:\n\n```bash\n# Construir e iniciar containers\ndocker-compose up --build\n\n# Executar em modo desanexado\ndocker-compose up -d\n```\n\n## Gráfico\n\n```mermaid\ngraph TD\n    subgraph \"Presentation Layer\"\n        direction TB\n        Controllers[\"Controllers\\nuser_controller.py\"]\n        Schemas[\"Schemas\\nuser/request.py\\nuser/response.py\"]\n    end\n\n    subgraph \"Use Cases Layer\"\n        direction TB\n        UseCases[\"User Use Cases\\ncreate_user.py\\nget_user.py\\nlist_users.py\"]\n        UseCaseInterface[\"Use Case Interface\\ninterfaces/use_case.py\"]\n    end\n\n    subgraph \"Domain Layer\"\n        direction TB\n        Entities[\"Entities\\nuser.py\"]\n        Repositories[\"Repository Interfaces\\nuser_repository.py\"]\n    end\n\n    subgraph \"Infrastructure Layer\"\n        direction TB\n        DbConfig[\"Database Config\\ndatabase.py\\nsettings.py\"]\n        RepImpl[\"Repository Implementation\\nsqlmodel_user_repository.py\"]\n        Dependencies[\"Dependencies\\nuser_dependencies.py\"]\n        Security[\"Security\\npassword.py\"]\n    end\n\n    Controllers --\u003e Schemas\n    Controllers --\u003e UseCases\n    UseCases --\u003e UseCaseInterface\n    UseCases --\u003e Entities\n    UseCases --\u003e Repositories\n    RepImpl --\u003e Repositories\n    RepImpl --\u003e DbConfig\n    RepImpl --\u003e Entities\n    Dependencies --\u003e RepImpl\n    Dependencies --\u003e UseCases\n    Security --\u003e UseCases\n\n    classDef presentation fill:#FFB6C1,stroke:#fff,stroke-width:1px;\n    classDef usecases fill:#FFA07A,stroke:#fff,stroke-width:1px;\n    classDef domain fill:#87CEEB,stroke:#fff,stroke-width:1px;\n    classDef infrastructure fill:#98FB98,stroke:#fff,stroke-width:1px;\n\n    class Controllers,Schemas presentation;\n    class UseCases,UseCaseInterface usecases;\n    class Entities,Repositories domain;\n    class DbConfig,RepImpl,Dependencies,Security infrastructure;\n```\n\n## Licença\n\nDistribuído sob a licença BSD-3. Veja `LICENSE` para mais informações.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwalber-vaz%2Flearn_clean_arch_fastapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwalber-vaz%2Flearn_clean_arch_fastapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwalber-vaz%2Flearn_clean_arch_fastapi/lists"}