DEV Community: Takahiro Ikeuchi

Rethinking Architecture in the AI Era — Part 1: Repository Management

Takahiro Ikeuchi — Mon, 16 Mar 2026 06:24:31 +0000

This is the first installment of a series on software product architecture for the AI age. There's no shortage of content about how fast AI can accelerate prototyping — but I believe medium-term maintainability deserves equal attention. (If this ends up being a one-off article, my apologies in advance.)

Today's topic: repository management. My conclusion upfront: go with a monorepo.

What Is a Monorepo?

For those new to the concept, a monorepo is the practice of managing multiple applications within a single repository. "Multiple apps" can mean any of the following:

A frontend and a backend living together
Full-stack apps for Service A and Service B side by side
Application code alongside shared libraries

A quick aside on microservices: while monorepos are sometimes discussed in that context, I don't have hands-on experience combining the two, so I'll leave that out of scope here. My instinct is that getting the most out of a monorepo requires keeping your tech stack reasonably unified — which arguably conflicts with what microservices are trying to achieve. The monorepo style I'm describing here probably isn't a great fit for microservices.

All that said, rather than dwelling on definitions, the practical answer is simple: use Turborepo.

What Is Turborepo?

Turborepo has become the de facto standard for monorepo setups in TypeScript projects. While it's technically positioned as a general-purpose build tool, in practice you reach for it when adopting a monorepo (or when you want smarter build caching).

Turborepo

Turborepo is a build system optimized for JavaScript and TypeScript, written in Rust.

turborepo.dev

Here's a representative directory structure for a web frontend + backend project using Turborepo:

my-turborepo/
├── apps/
│   ├── web/                  # Frontend app (e.g. Next.js)
│   │   ├── src/
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── api/                  # Backend app (e.g. Hono, Express)
│       ├── src/
│       ├── package.json
│       └── tsconfig.json
├── packages/
│   ├── ui/                   # Shared UI component library
│   │   ├── src/
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── tsconfig/             # Shared TypeScript config
│   │   ├── base.json
│   │   ├── nextjs.json
│   │   └── package.json
│   └── utils/                # Shared utilities
│       ├── src/
│       ├── package.json
│       └── tsconfig.json
├── .claude/
│   ├── CLAUDE.md
│   └── skills/
├── .codex/
│   └── skills/
├── turbo.json
├── biome.json
├── package.json
├── pnpm-workspace.yaml
└── tsconfig.json

The pattern is straightforward: apps/ holds your individual applications; packages/ holds shared code — utilities, UI components, and config files like tsconfig.

You could technically replicate this directory structure without Turborepo, but Turborepo adds real value by reading each package.json, running builds and tests in bulk or in parallel, and handling build cache intelligently — a significant advantage for larger projects where build times start to hurt.

Why a Monorepo in the AI Era?

Knowledge base management is increasingly recognized as critical in AI-era product development — and that knowledge base naturally includes your codebase. A knowledge base only has value if it's actually referenced. And to be referenced easily, knowledge needs to be close together.

With a monorepo, the moment you clone a single GitHub repository, you have everything in one place: application code, development documentation, agent skills — the full knowledge base for your product. You could devise ways to help AI recognize multiple repositories as belonging to the same project, but why bother? A monorepo gives you that coherence for free.

A common objection goes something like: "Frontend and backend only need to communicate via API contracts — mixing their contexts is unnecessary." I'd argue this mental model is worth updating. In the age of AI coding, the leverage comes from architectures that let you see the full picture and move fast — not from strict context separation.

Conditions for Monorepo Success

Monorepos pair well with AI-era development, but a few conditions make them work significantly better.

1. Your backend is written in TypeScript

A mixed stack — TypeScript frontend, Python backend — can technically be a monorepo, but the shared packages/ become frontend-only, narrowing their value. You also end up managing linting, formatting, and tooling for two different languages.

Worth noting: Turborepo is built around TypeScript (and package.json as the primary unit of configuration), so aligning your stack on TypeScript is the path of least resistance here too.

2. Your review process is adapted for AI-assisted development

In a monorepo with AI coding, implementing a single feature often means the AI writes frontend and backend code in one go. Pull requests naturally reflect that end-to-end implementation. You could split them up — but if you're still enforcing pre-AI-era review rituals, humans become the bottleneck. At minimum, integrating AI-assisted code review is necessary; a broader rethink of your PR workflow is worth considering.

A Real Example: Chronock

My own app, Chronock, is built as a monorepo with TypeScript across the full stack. Here's the structure:

chronock/
├── apps/
│   ├── chronock-app/              # Frontend (React + TanStack Start)
│   ├── chronock-backend/          # Backend (Bun + Connect RPC)
│   ├── chronock-book/             # Booking page (React + TanStack Start)
│   └── chronock-www/              # Marketing site (Astro)
│
├── packages/
│   ├── contract/                  # Proto definitions & generated code
│   ├── i18n/                      # Internationalization utilities
│   └── typescript-config/         # Shared TypeScript config
│
├── specs/                         # Product specifications
│
├── .claude/
│   ├── CLAUDE.md
│   └── skills/
├── .codex/
│   └── skills/
├── biome.jsonc                    # Linter / Formatter config
├── bunfig.toml                    # Bun config
├── docker-compose.local.yml
├── package.json
└── turbo.json                     # Turborepo config

A few things worth highlighting:

The marketing site (Astro) lives in the monorepo alongside the app. This makes tasks like "reflect new feature messaging on the website" or "check for inconsistencies between the latest implementation and the landing page copy" natural things to hand off to an AI agent.
Frontend–backend communication uses Connect RPC (Protocol Buffers). The .proto definition files live in packages/contract, making it seamless to manage the interface definition and run codegen for both frontend and backend from one place.
Product specs and agent skills live in the same repository, which makes coding agents noticeably more effective — they have the context they need without jumping across repos.

Summary

Architecture choices for the AI era:

Centralize context in a monorepo and treat it as a living knowledge base
Aligning your stack on TypeScript pays off in multiple ways
The pull request problem doesn't solve itself — it needs its own dedicated solution

That's a wrap for Part 1.

How to get started DDD & Onion-Architecture in Python web application

Takahiro Ikeuchi — Fri, 22 Apr 2022 11:29:23 +0000

I published the following code for sharing knowledge of DDD & Onion Architecture in Python web applications.

iktakahiro / dddpy

Python DDD & Onion Architecture Example and Techniques

Python DDD & Onion-Architecture Example and Techniques

English | 日本語

Go implementation: oniongo

NOTE: This repository is an example to demonstrate "how to implement DDD architecture in a Python web application." If you use this as a reference, ensure to implement authentication and security before deploying it to a real-world environment!

DeepWiki powered by Devin: https://deepwiki.com/iktakahiro/dddpy
My blog post: https://iktakahiro.dev/python-ddd-onion-architecture

Tech Stack

Prerequisites

Python 3.13 or higher
uv - Python package installer and resolver

Project Setup

Install dependencies using uv:

make install

Run the web app

make dev

Code Architecture

The directory structure is based on Onion Architecture:

├── main.py
├── dddpy
│   ├── domain
│   │   └── todo
│   │       ├── entities
│   │       │   └── todo.py
│   │       ├── value_objects
│   │       │   ├── todo_title.py
│   │       │   ├── todo_description.py
│   │       │   ├── todo_id.py
│   │       │   └── todo_status.py
│

…

View on GitHub

I've also written a git of it on README. But in some ways, DDD is too difficult for us to understand; I would like to explain this architecture.

Motivation

My day job is to develop apps for smartphones using Flutter. In this development, I've adopted DDD with Onion architecture. This approach has worked well so far. On the other hand, the requirements of a native application are more complex than for typical web apps. So, I wanted to see what would happen if I applied DDD to a thin web app.

Conclusion

DDD can be adopted in the Python world as well.
For users familiar with MVC through prominent frameworks such as Django, this codebase may seem bizarre. But I believe it will help in many ways, especially to ensure maintainability and testability.
The variety of interfaces that make up DDD is not necessarily compatible with the dynamically typed language. However, it is achievable using the standard features provided by Python.

Overview

Code Architecture

DDD & Onion Architecture

├── main.py
├── dddpy
│   ├── domain
│   │   └── book
│   │       ├── book.py  # Entity
│   │       ├── book_exception.py  # Exception definitions
│   │       ├── book_repository.py  # Repository interface
│   │       └── isbn.py  # Value Object
│   ├── infrastructure
│   │   └── sqlite
│   │       ├── book
│   │       │   ├── book_dto.py  # DTO using SQLAlchemy
│   │       │   ├── book_query_service.py  # Query service implementation
│   │       │   └── book_repository.py  # Repository implementation
│   │       └── database.py
│   ├── presentation
│   │   └── schema
│   │       └── book
│   │           └── book_error_message.py
│   └── usecase
│       └── book
│           ├── book_command_model.py  # Write models including schemas of the RESTFul API
│           ├── book_command_usecase.py
│           ├── book_query_model.py  # Read models including schemas
│           ├── book_query_service.py  # Query service interface
│           └── book_query_usecase.py
└── tests

Tech Stack

FastAPI

FastAPI framework, high performance, easy to learn, fast to code, ready for production

fastapi.tiangolo.com

SQLAlchemy - The Database Toolkit for Python

The Database Toolkit for Python

sqlalchemy.org

Techniques

Repository pattern
Data Transfer Object
CQRS pattern
Unit of Work pattern
Dependency Injection (using FastAPI feature)

How to implement components of DDD

The assumption is that you are familiar with Eric Evans' book and Onion architecture, so I will not explain them. In the following, I will explain how you can implement each DDD component in the Python world.

Entity

To represent an Entity in Python, use __eq__() method to ensure the object's identity.

https://github.com/iktakahiro/dddpy/blob/main/dddpy/domain/book/book.py

class Book:
    def __init__(
        self,
        id: str,
        title: str,
    ):
        self.id: str = id
        self.title: str = title

    def __eq__(self, o: object) -> bool:
        if isinstance(o, Book):
            return self.id == o.id

        return False

In this example, it's anemic. You have to implement more behaviors. I would add that the use of getter and setter is not Pythonic code. On the other hand, I think we can use it if necessary.

Value Object

As I understand it, the requirements for Value Object are the following:

It's not an Entity
If all the properties are the same, The objects are identical.
As a result, they are interchangeable.

To represent a Value Object, use @dataclass decorator with eq=True and frozen=True.

https://github.com/iktakahiro/dddpy/blob/main/dddpy/domain/book/isbn.py

@dataclass(init=False, eq=True, frozen=True)
class Isbn:
    """Isbn represents an ISBN code as a value object"""

    value: str

    def __init__(self, value: str):
        if pattern.match(value) is None:
            raise ValueError("isbn should be a valid format.")

        object.__setattr__(self, "value", value)

Value Objects do not necessarily have to be immutable, but it is better to protect robustness.

Interface (abstract Class)

On a duck-typing language, IMO, it does not go well with defining interfaces. But Abstract Base class helps us to prepare them.

https://github.com/iktakahiro/dddpy/blob/main/dddpy/domain/book/book_repository.py

class BookRepository(ABC):
    @abstractmethod
    def create(self, book: Book) -> Optional[Book]:
        raise NotImplementedError

    @abstractmethod
    def find_by_id(self, id: str) -> Optional[Book]:
        raise NotImplementedError

Program to an interface, not an implementation.

Data Transfer Object and a factory method

DTO (Data Transfer Object) is a good practice to isolate domain objects from the infrastructure layer.

https://github.com/iktakahiro/dddpy/blob/main/dddpy/infrastructure/sqlite/book/book_dto.py

class BookDTO(Base):
    __tablename__ = "book"
    id: Union[str, Column] = Column(String, primary_key=True, autoincrement=False)
    title: Union[str, Column] = Column(String, nullable=False)

On a minimum MVC architecture, models often inherit a base class provided by an O/R Mapper. But in that case, the domain layer would be dependent on the outer layer.

To solve this problem, we can set two rules:

Domain layer classes (such as an Entity or a Value Object) DO NOT extend the SQLAlchemy Base class.
Data transfer Objects extend the O/R mapper class.

Those, including my friend, who assert a DTO and a repository pattern are an overzealous approach.

I'm trying to tell you that you are not using the repository pattern to replace RDBs in the future. You have to take it to ensure testability today.

Read/Write models and request validation

It is helpful to separate a read-only model from a write-only model to implement the CQRS pattern.

I hadn't anticipated this, but this approach also worked well for managing input/output validation.

class BookReadModel(BaseModel):
    id: str = Field(example="vytxeTZskVKR7C7WgdSP3d")
    isbn: str = Field(example="978-0321125217")

FastAPI can set response_model and request_model. Amazingly, by associating the Read model with the Response model and the Write model with the Request model, API documentation can be generated and validated.

https://github.com/iktakahiro/dddpy/blob/main/main.py#L66

@app.post(
    "/books",
    response_model=BookReadModel,
    status_code=status.HTTP_201_CREATED,
    responses={
        status.HTTP_409_CONFLICT: {
            "model": ErrorMessageBookIsbnAlreadyExists,
        },
    },
)
async def create_book(
    data: BookCreateModel,
    book_command_usecase: BookCommandUseCase = Depends(book_command_usecase),
):
    try:
        book = book_command_usecase.create_book(data)
    except BookIsbnAlreadyExistsError as e:
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail=e.message,
        )
    except Exception as e:
        logger.error(e)
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
        )

    return book

Amazingly, by associating read models with the response_model and write models with the request model, the framework can generate API documentation and validate the request body.

CQRS pattern

I will skip a general explanation of CQRS. Instead, I would like to show the specific sequence in the figure below.

By splitting the Read model and Write model, we can flexibly respond to requests' input and output. My dear seniors educated me about DRY for a long time, but I've come to realize that it's not always absolute.

Unit of Work pattern

In this short project, the missing piece is transaction management. For the gap, the Unit of Work pattern fits almost entirely. But first, I would like to say that this is something that I would not strongly recommend to others, including you, because it is redundant, even for me, who suggested the repository pattern so much. However, I can't think of any other way to do transaction management without the assistance of a framework and its middleware.

https://github.com/iktakahiro/dddpy/blob/main/dddpy/usecase/book/book_command_usecase.py#L18

class BookCommandUseCaseUnitOfWork(ABC):
    book_repository: BookRepository

    @abstractmethod
    def begin(self):
        raise NotImplementedError

    @abstractmethod
    def commit(self):
        raise NotImplementedError

    @abstractmethod
    def rollback(self):
        raise NotImplementedError

https://github.com/iktakahiro/dddpy/blob/main/dddpy/infrastructure/sqlite/book/book_repository.py#L63

class BookCommandUseCaseUnitOfWorkImpl(BookCommandUseCaseUnitOfWork):
    def __init__(
        self,
        session: Session,
        book_repository: BookRepository,
    ):
        self.session: Session = session
        self.book_repository: BookRepository = book_repository

    def begin(self):
        self.session.begin()

    def commit(self):
        self.session.commit()

    def rollback(self):
        self.session.rollback()

Dependency Injection

This is a last topic, Dependency Injection sounds like an exaggeration, but it essentially means assigning a class instance to a property of other classes. One of the reasons I like FastAPI is that it provides a DI mechanism by default.

https://github.com/iktakahiro/dddpy/blob/main/main.py#L53

def book_query_usecase(session: Session = Depends(get_session)) -> BookQueryUseCase:
    book_query_service: BookQueryService = BookQueryServiceImpl(session)
    return BookQueryUseCaseImpl(book_query_service)


def book_command_usecase(session: Session = Depends(get_session)) -> BookCommandUseCase:
    book_repository: BookRepository = BookRepositoryImpl(session)
    uow: BookCommandUseCaseUnitOfWork = BookCommandUseCaseUnitOfWorkImpl(
        session, book_repository=book_repository
    )
    return BookCommandUseCaseImpl(uow)

I don't think there is a widely known methodology for practicing DDD in Python. If you are going to try it, please refer to it.