refactor: migrate to DDD architecture with Dishka DI

Complete architectural refactoring from simple MVC to Clean Architecture/DDD pattern:

Domain Layer:

- Add entities (Post, BaseEntity) with business logic

- Add value objects (Title, Content, Slug) with validation

- Add repository interfaces (PostRepository)

- Add domain exceptions

Application Layer:

- Add use cases (CreatePost, GetPost, UpdatePost, DeletePost, ListPosts, PublishPost)

- Add DTOs for data transfer

- Add TransactionManager interface

Infrastructure Layer:

- Add SQLAlchemy models and async database connection

- Add SQLAlchemyPostRepository implementation

- Add Dishka DI container with providers

- Add error handlers and middleware

Presentation Layer:

- Add FastAPI routes with Dishka integration

- Add Pydantic schemas

- Add dependency injection using FromDishka[T]

Other Changes:

- Remove old flat structure (api/, common/, core/, modules/)

- Add hatchling build system for package scripts

- Add blog CLI command

- Update AGENTS.md with new architecture docs

- All 48 tests passing, mypy clean, ruff clean

app/application/__init__.py

@@ -0,0 +1,28 @@
+"""Application layer exports."""
+
+from app.application.dtos import CreatePostDTO, PostResponseDTO, UpdatePostDTO
+from app.application.interfaces import TransactionManager
+from app.application.use_cases import (
+    CreatePostUseCase,
+    DeletePostUseCase,
+    GetPostUseCase,
+    ListPostsUseCase,
+    PublishPostUseCase,
+    UpdatePostUseCase,
+)
+
+__all__ = [
+    # DTOs
+    "CreatePostDTO",
+    "UpdatePostDTO",
+    "PostResponseDTO",
+    # Interfaces
+    "TransactionManager",
+    # Use Cases
+    "CreatePostUseCase",
+    "GetPostUseCase",
+    "UpdatePostUseCase",
+    "DeletePostUseCase",
+    "ListPostsUseCase",
+    "PublishPostUseCase",
+]

app/application/dtos/__init__.py

@@ -0,0 +1,5 @@
+"""Application DTOs."""
+
+from app.application.dtos.post import CreatePostDTO, PostResponseDTO, UpdatePostDTO
+
+__all__ = ["CreatePostDTO", "UpdatePostDTO", "PostResponseDTO"]

app/application/dtos/post.py

@@ -0,0 +1,39 @@
+"""DTOs for post use cases."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from uuid import UUID
+
+
+@dataclass(frozen=True)
+class CreatePostDTO:
+    """DTO for creating a post."""
+
+    title: str
+    content: str
+    author_id: str
+    tags: list[str] | None = None
+
+
+@dataclass(frozen=True)
+class UpdatePostDTO:
+    """DTO for updating a post."""
+
+    title: str | None = None
+    content: str | None = None
+    tags: list[str] | None = None
+
+
+@dataclass(frozen=True)
+class PostResponseDTO:
+    """DTO for post response."""
+
+    id: UUID
+    title: str
+    content: str
+    slug: str
+    author_id: str
+    published: bool
+    tags: list[str]
+    created_at: datetime
+    updated_at: datetime

app/application/interfaces/__init__.py

@@ -0,0 +1,5 @@
+"""Application interfaces."""
+
+from app.application.interfaces.transaction_manager import TransactionManager
+
+__all__ = ["TransactionManager"]

app/application/interfaces/transaction_manager.py

@@ -0,0 +1,17 @@
+"""Transaction Manager interface for managing database transactions."""
+
+from abc import ABC, abstractmethod
+
+
+class TransactionManager(ABC):
+    """Abstract Transaction Manager for controlling transaction boundaries."""
+
+    @abstractmethod
+    async def commit(self) -> None:
+        """Commit the current transaction."""
+        ...
+
+    @abstractmethod
+    async def rollback(self) -> None:
+        """Rollback the current transaction."""
+        ...

app/application/use_cases/__init__.py

@@ -0,0 +1,17 @@
+"""Use cases."""
+
+from app.application.use_cases.create_post import CreatePostUseCase
+from app.application.use_cases.delete_post import DeletePostUseCase
+from app.application.use_cases.get_post import GetPostUseCase
+from app.application.use_cases.list_posts import ListPostsUseCase
+from app.application.use_cases.publish_post import PublishPostUseCase
+from app.application.use_cases.update_post import UpdatePostUseCase
+
+__all__ = [
+    "CreatePostUseCase",
+    "GetPostUseCase",
+    "UpdatePostUseCase",
+    "DeletePostUseCase",
+    "ListPostsUseCase",
+    "PublishPostUseCase",
+]

app/application/use_cases/create_post.py

@@ -0,0 +1,62 @@
+"""Create post use case."""
+
+from app.application.dtos.post import CreatePostDTO, PostResponseDTO
+from app.application.interfaces import TransactionManager
+from app.domain.entities import Post
+from app.domain.exceptions import AlreadyExistsException
+from app.domain.repositories import PostRepository
+
+
+class CreatePostUseCase:
+    """Use case for creating a new blog post."""
+
+    def __init__(
+        self,
+        post_repo: PostRepository,
+        tx_manager: TransactionManager,
+    ) -> None:
+        self._post_repo = post_repo
+        self._tx_manager = tx_manager
+
+    async def execute(self, dto: CreatePostDTO) -> PostResponseDTO:
+        """Execute the use case."""
+        # Generate slug from title
+        from app.domain.value_objects import Slug
+
+        slug = Slug.from_title(dto.title)
+
+        # Check if slug already exists
+        if await self._post_repo.slug_exists(slug.value):
+            raise AlreadyExistsException(
+                f"Post with slug '{slug.value}' already exists"
+            )
+
+        # Create domain entity
+        post = Post.create(
+            title_str=dto.title,
+            content_str=dto.content,
+            author_id=dto.author_id,
+            tags=dto.tags or [],
+        )
+
+        # Persist entity
+        await self._post_repo.add(post)
+
+        # Commit transaction
+        await self._tx_manager.commit()
+
+        return self._map_to_dto(post)
+
+    def _map_to_dto(self, post: Post) -> PostResponseDTO:
+        """Map domain entity to response DTO."""
+        return PostResponseDTO(
+            id=post.id,
+            title=post.title.value,
+            content=post.content.value,
+            slug=post.slug.value,
+            author_id=post.author_id,
+            published=post.published,
+            tags=post.tags.copy(),
+            created_at=post.created_at,
+            updated_at=post.updated_at,
+        )

app/application/use_cases/delete_post.py

@@ -0,0 +1,35 @@
+"""Delete post use case."""
+
+from uuid import UUID
+
+from app.application.interfaces import TransactionManager
+from app.domain.exceptions import ForbiddenException, NotFoundException
+from app.domain.repositories import PostRepository
+
+
+class DeletePostUseCase:
+    """Use case for deleting a blog post."""
+
+    def __init__(
+        self,
+        post_repo: PostRepository,
+        tx_manager: TransactionManager,
+    ) -> None:
+        self._post_repo = post_repo
+        self._tx_manager = tx_manager
+
+    async def execute(self, post_id: UUID, current_user_id: str) -> None:
+        """Execute the use case."""
+        post = await self._post_repo.get_by_id(post_id)
+        if not post:
+            raise NotFoundException(f"Post with id '{post_id}' not found")
+
+        # Check authorization
+        if post.author_id != current_user_id:
+            raise ForbiddenException("You can only delete your own posts")
+
+        # Delete the post
+        await self._post_repo.delete(post_id)
+
+        # Commit transaction
+        await self._tx_manager.commit()

app/application/use_cases/get_post.py

@@ -0,0 +1,49 @@
+"""Get post use case."""
+
+from uuid import UUID
+
+from app.application.dtos.post import PostResponseDTO
+from app.application.interfaces import TransactionManager
+from app.domain.entities import Post
+from app.domain.exceptions import NotFoundException
+from app.domain.repositories import PostRepository
+
+
+class GetPostUseCase:
+    """Use case for retrieving a post by ID or slug."""
+
+    def __init__(
+        self,
+        post_repo: PostRepository,
+        tx_manager: TransactionManager,
+    ) -> None:
+        self._post_repo = post_repo
+        self._tx_manager = tx_manager
+
+    async def by_id(self, post_id: UUID) -> PostResponseDTO:
+        """Get post by ID."""
+        post = await self._post_repo.get_by_id(post_id)
+        if not post:
+            raise NotFoundException(f"Post with id '{post_id}' not found")
+        return self._map_to_dto(post)
+
+    async def by_slug(self, slug: str) -> PostResponseDTO:
+        """Get post by slug."""
+        post = await self._post_repo.get_by_slug(slug)
+        if not post:
+            raise NotFoundException(f"Post with slug '{slug}' not found")
+        return self._map_to_dto(post)
+
+    def _map_to_dto(self, post: Post) -> PostResponseDTO:
+        """Map domain entity to response DTO."""
+        return PostResponseDTO(
+            id=post.id,
+            title=post.title.value,
+            content=post.content.value,
+            slug=post.slug.value,
+            author_id=post.author_id,
+            published=post.published,
+            tags=post.tags.copy(),
+            created_at=post.created_at,
+            updated_at=post.updated_at,
+        )

app/application/use_cases/list_posts.py

@@ -0,0 +1,57 @@
+"""List posts use case."""
+
+from app.application.dtos.post import PostResponseDTO
+from app.application.interfaces import TransactionManager
+from app.domain.entities import Post
+from app.domain.repositories import PostRepository
+
+
+class ListPostsUseCase:
+    """Use case for listing blog posts with filtering."""
+
+    def __init__(
+        self,
+        post_repo: PostRepository,
+        tx_manager: TransactionManager,
+    ) -> None:
+        self._post_repo = post_repo
+        self._tx_manager = tx_manager
+
+    async def all_posts(self) -> list[PostResponseDTO]:
+        """Get all posts."""
+        posts = await self._post_repo.get_all()
+        return [self._map_to_dto(post) for post in posts]
+
+    async def published_posts(self) -> list[PostResponseDTO]:
+        """Get all published posts."""
+        posts = await self._post_repo.get_published()
+        return [self._map_to_dto(post) for post in posts]
+
+    async def by_author(self, author_id: str) -> list[PostResponseDTO]:
+        """Get posts by author."""
+        posts = await self._post_repo.get_by_author(author_id)
+        return [self._map_to_dto(post) for post in posts]
+
+    async def by_tag(self, tag: str) -> list[PostResponseDTO]:
+        """Get posts by tag."""
+        posts = await self._post_repo.get_by_tag(tag)
+        return [self._map_to_dto(post) for post in posts]
+
+    async def search(self, query: str) -> list[PostResponseDTO]:
+        """Search posts."""
+        posts = await self._post_repo.search(query)
+        return [self._map_to_dto(post) for post in posts]
+
+    def _map_to_dto(self, post: Post) -> PostResponseDTO:
+        """Map domain entity to response DTO."""
+        return PostResponseDTO(
+            id=post.id,
+            title=post.title.value,
+            content=post.content.value,
+            slug=post.slug.value,
+            author_id=post.author_id,
+            published=post.published,
+            tags=post.tags.copy(),
+            created_at=post.created_at,
+            updated_at=post.updated_at,
+        )

app/application/use_cases/publish_post.py

@@ -0,0 +1,65 @@
+"""Publish post use case."""
+
+from uuid import UUID
+
+from app.application.dtos.post import PostResponseDTO
+from app.application.interfaces import TransactionManager
+from app.domain.entities import Post
+from app.domain.exceptions import ForbiddenException, NotFoundException
+from app.domain.repositories import PostRepository
+
+
+class PublishPostUseCase:
+    """Use case for publishing/unpublishing a blog post."""
+
+    def __init__(
+        self,
+        post_repo: PostRepository,
+        tx_manager: TransactionManager,
+    ) -> None:
+        self._post_repo = post_repo
+        self._tx_manager = tx_manager
+
+    async def publish(self, post_id: UUID, current_user_id: str) -> PostResponseDTO:
+        """Publish a post."""
+        post = await self._post_repo.get_by_id(post_id)
+        if not post:
+            raise NotFoundException(f"Post with id '{post_id}' not found")
+
+        if post.author_id != current_user_id:
+            raise ForbiddenException("You can only publish your own posts")
+
+        post.publish()
+        await self._post_repo.update(post)
+        await self._tx_manager.commit()
+
+        return self._map_to_dto(post)
+
+    async def unpublish(self, post_id: UUID, current_user_id: str) -> PostResponseDTO:
+        """Unpublish a post."""
+        post = await self._post_repo.get_by_id(post_id)
+        if not post:
+            raise NotFoundException(f"Post with id '{post_id}' not found")
+
+        if post.author_id != current_user_id:
+            raise ForbiddenException("You can only unpublish your own posts")
+
+        post.unpublish()
+        await self._post_repo.update(post)
+        await self._tx_manager.commit()
+
+        return self._map_to_dto(post)
+
+    def _map_to_dto(self, post: Post) -> PostResponseDTO:
+        """Map domain entity to response DTO."""
+        return PostResponseDTO(
+            id=post.id,
+            title=post.title.value,
+            content=post.content.value,
+            slug=post.slug.value,
+            author_id=post.author_id,
+            published=post.published,
+            tags=post.tags.copy(),
+            created_at=post.created_at,
+            updated_at=post.updated_at,
+        )

app/application/use_cases/update_post.py

@@ -0,0 +1,73 @@
+"""Update post use case."""
+
+from uuid import UUID
+
+from app.application.dtos.post import PostResponseDTO, UpdatePostDTO
+from app.application.interfaces import TransactionManager
+from app.domain.entities import Post
+from app.domain.exceptions import ForbiddenException, NotFoundException
+from app.domain.repositories import PostRepository
+from app.domain.value_objects import Content, Title
+
+
+class UpdatePostUseCase:
+    """Use case for updating a blog post."""
+
+    def __init__(
+        self,
+        post_repo: PostRepository,
+        tx_manager: TransactionManager,
+    ) -> None:
+        self._post_repo = post_repo
+        self._tx_manager = tx_manager
+
+    async def execute(
+        self,
+        post_id: UUID,
+        dto: UpdatePostDTO,
+        current_user_id: str,
+    ) -> PostResponseDTO:
+        """Execute the use case."""
+        post = await self._post_repo.get_by_id(post_id)
+        if not post:
+            raise NotFoundException(f"Post with id '{post_id}' not found")
+
+        # Check authorization
+        if post.author_id != current_user_id:
+            raise ForbiddenException("You can only update your own posts")
+
+        # Update fields
+        if dto.title is not None:
+            post.update_title(Title(dto.title))
+
+        if dto.content is not None:
+            post.update_content(Content(dto.content))
+
+        if dto.tags is not None:
+            # Replace all tags
+            for tag in post.tags[:]:
+                post.remove_tag(tag)
+            for tag in dto.tags:
+                post.add_tag(tag)
+
+        # Persist changes
+        await self._post_repo.update(post)
+
+        # Commit transaction
+        await self._tx_manager.commit()
+
+        return self._map_to_dto(post)
+
+    def _map_to_dto(self, post: Post) -> PostResponseDTO:
+        """Map domain entity to response DTO."""
+        return PostResponseDTO(
+            id=post.id,
+            title=post.title.value,
+            content=post.content.value,
+            slug=post.slug.value,
+            author_id=post.author_id,
+            published=post.published,
+            tags=post.tags.copy(),
+            created_at=post.created_at,
+            updated_at=post.updated_at,
+        )