{"id":45638180,"url":"https://github.com/Peopl3s/litestar-hexagonal-architecture-example","last_synced_at":"2026-03-09T07:01:35.241Z","repository":{"id":320135899,"uuid":"1080934227","full_name":"Peopl3s/litestar-hexagonal-architecture-example","owner":"Peopl3s","description":":star2: Litestar Hexagonal Architecture Project Example: litestar + dishka + faststream + sqlalchemy + pydantic","archived":false,"fork":false,"pushed_at":"2025-11-28T04:34:31.000Z","size":308,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-27T12:59:52.748Z","etag":null,"topics":["alembic","dishka","docker","faststream","granian","hexagonal","hexagonal-architecture","hexagonal-architecture-example","hexagonal-architecture-template","httpx","litestar","litestar-boilerplate","litestar-example","litestar-template","pydantic","pytest","sqlalchemy","stamina","uv"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Peopl3s.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-22T04:31:06.000Z","updated_at":"2025-11-28T04:34:35.000Z","dependencies_parsed_at":"2025-10-22T06:28:21.253Z","dependency_job_id":"a19a1e60-5b45-4374-8151-74dd21dda877","html_url":"https://github.com/Peopl3s/litestar-hexagonal-architecture-example","commit_stats":null,"previous_names":["peopl3s/litestar-hexagonal-architecture-example"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Peopl3s/litestar-hexagonal-architecture-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Peopl3s%2Flitestar-hexagonal-architecture-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Peopl3s%2Flitestar-hexagonal-architecture-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Peopl3s%2Flitestar-hexagonal-architecture-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Peopl3s%2Flitestar-hexagonal-architecture-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Peopl3s","download_url":"https://codeload.github.com/Peopl3s/litestar-hexagonal-architecture-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Peopl3s%2Flitestar-hexagonal-architecture-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30286028,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T02:57:19.223Z","status":"ssl_error","status_checked_at":"2026-03-09T02:56:26.373Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["alembic","dishka","docker","faststream","granian","hexagonal","hexagonal-architecture","hexagonal-architecture-example","hexagonal-architecture-template","httpx","litestar","litestar-boilerplate","litestar-example","litestar-template","pydantic","pytest","sqlalchemy","stamina","uv"],"created_at":"2026-02-24T02:00:29.452Z","updated_at":"2026-03-09T07:01:35.195Z","avatar_url":"https://github.com/Peopl3s.png","language":"Python","funding_links":[],"categories":["Third-Party Extensions"],"sub_categories":["Projects"],"readme":"# :star2: Litestar Hexagonal Architecture Project Example\n\n[![Python 3.12+](https://img.shields.io/badge/Python-3.12+-000000?style=for-the-badge\u0026logo=python\u0026logoColor=white)](https://www.python.org/downloads/)[![GitHub Stars](https://img.shields.io/github/stars/Peopl3s/litestar-hexagonal-architecture-example?style=for-the-badge\u0026logo=github\u0026logoColor=white\u0026color=000000)](https://github.com/Peopl3s/litestar-hexagonal-architecture-example/stargazers)\n[![Last Commit](https://img.shields.io/github/last-commit/Peopl3s/litestar-hexagonal-architecture-example?style=for-the-badge\u0026color=000000)](https://github.com/Peopl3s/litestar-hexagonal-architecture-example/commits/main)\n[![License](https://img.shields.io/github/license/Peopl3s/litestar-hexagonal-architecture-example?style=for-the-badge\u0026color=000000)](./LICENSE)\n\n![Litestar](https://img.shields.io/badge/Litestar-000000?style=for-the-badge\u0026logo=litestar\u0026logoColor=white)\n![FastStream](https://img.shields.io/badge/FastStream-000000?style=for-the-badge\u0026logo=faststream\u0026logoColor=white)\n![Dishka](https://img.shields.io/badge/Dishka-000000?style=for-the-badge\u0026logoColor=white)\n![Hexagonal Architecture](https://img.shields.io/badge/Hexagonal_Architecture-000000?style=for-the-badge\u0026logoColor=white)\n--------\n\n\n💫 [Litestar Clean Acrhitecture Project Template](https://github.com/Peopl3s/clean-architecture-litestar-project-template)\n\n🔌 [FastAPI Clean Architecture Project Template](https://github.com/Peopl3s/clean-architecture-fastapi-project-template)\n\n---\n\nHexagonal Architecture, also known as **Ports and Adapters Architecture**, was proposed by Alistair Cockburn as a design approach for building applications centered around a core of business logic that remains independent from external dependencies (such as databases, UIs, external APIs, etc.).\n\nIn this architecture, there are **no traditional \"layers\"** like in layered architectures (e.g., presentation → business → data). Instead, it revolves around an **application core**, surrounded by **ports and adapters**. However, for clarity, we can identify the following **logical components**:\n\n#### 1. **Application Core (Hexagon)**\n\n- Contains **pure business logic** (domain logic).\n- **Has no dependencies** on external systems: databases, web frameworks, UIs, etc.\n- Interacts with the outside world **exclusively through ports**.\n\n#### 2. **Ports**\n\n- These are **interfaces** defining **how the core communicates with the outside world**.\n- There are two types:\n    - **Primary (Driving) Ports** — used by **external systems to invoke the core** (e.g., REST APIs, CLI, UI).\n    - **Secondary (Driven) Ports** — used by **the core to invoke external systems** (e.g., databases, external services).\n\n#### 3. **Adapters**\n\n- Concrete implementations of ports.\n- **Bridge external technologies to the core** via corresponding ports.\n- Also divided into:\n    - **Primary Adapters** — invoke the core (e.g., Spring controllers, HTTP request handlers).\n    - **Secondary Adapters** — are invoked by the core (e.g., repositories, external API clients).\n\n#### Advantages:\n\n- Easy testing (adapters can be replaced with mocks).\n- Independence from frameworks and infrastructure.\n- Flexibility: UIs, databases, or integration methods can be easily swapped.\n\n#### Example:\n\n- **Core**: Order processing service.\n- **Primary Port**: `OrderService` (interface).\n- **Primary Adapter**: REST controller calling `OrderService`.\n- **Secondary Port**: `OrderRepository` (interface for persisting orders).\n- **Secondary Adapter**: PostgreSQL-based implementation of `OrderRepository`.\n\nThus, in Hexagonal Architecture, traditional **\"layers\" are replaced by a \"core + ports + adapters\"** structure, ensuring architectural clarity and flexibility.\n\n```\n│\n├── app/\n│   ├── __init__.py\n│   │\n│   ├── core/                     # ← Application Core (Hexagon)\n│   │   ├── __init__.py\n│   │   ├── models.py             # ← Domain models (plain, no ORM/Pydantic)\n│   │   └── services.py           # ← Business logic (Use Cases)\n│   │\n│   ├── ports/                    # ← Ports (interfaces)\n│   │   ├── __init__.py\n│   │   ├── user_ports.py         # ← IUserRepository, etc.\n│   │   └── auth_ports.py\n│   │\n│   ├── adapters/                 # ← Adapters\n│   │   ├── __init__.py\n│   │   │\n│   │   ├── primary/              # ← Primary (Driving) Adapters\n│   │   │   ├── __init__.py\n│   │   │   └── api/              # ← Litestar routes\n│   │   │       ├── __init__.py\n│   │   │       ├── controllers.py\n│   │   │       └── dtos.py       # ← DTOs: request/response models (Pydantic)\n│   │   │\n│   │   └── secondary/            # ← Secondary (Driven) Adapters\n│   │       ├── __init__.py\n│   │       ├── database/         # ← Repositories, ORM models\n│   │       │   ├── __init__.py\n│   │       │   ├── models.py     # ← SQLAlchemy models\n│   │       │   └── repositories.py  # ← Port implementations\n│   │       └── external/         # ← External APIs, file systems, etc.\n│   │\n│   └── main.py                   # ← Litestar entry point\n│   └── config.py                 # ← Project settings\n│   └── ioc.py                    # ← DI\n│\n├── tests/\n│   ├── unit/\n│   └── integration/\n│\n├── ...\n└── README.md\n```\n\n## Stack\n* Main framework - Litestar\n* Message broker framework - Faststream\n* DI - dishka\n* Database - SQLAlchemy + alembic\n* Validation - Pydantic\n* Package manager - uv\n* HTTP-requests - httpx\n* Retries - stamina\n* Deployment - Docker + granian\n* Tests - pytest\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPeopl3s%2Flitestar-hexagonal-architecture-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPeopl3s%2Flitestar-hexagonal-architecture-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPeopl3s%2Flitestar-hexagonal-architecture-example/lists"}