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

Source: Dev.to

Repository Management – Why a Monorepo Makes Sense

There’s no shortage of content about how fast AI can accelerate prototyping — but medium‑term maintainability deserves equal attention.
(If this ends up being a one‑off article, my apologies in advance.)

My Conclusion Up‑Front

Go with a monorepo.

What Is a Monorepo?

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

Quick Aside on Microservices

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

The Practical Answer: Turborepo

Turborepo has become the de‑facto standard for monorepo setups in TypeScript projects. Although 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).

Representative Directory Structure (Web Frontend + Backend)

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

• apps/ holds your individual applications.
• packages/ holds shared code — utilities, UI components, and config files like tsconfig.

You could replicate this layout without Turborepo, but Turborepo adds real value by:

1. Reading each package.json.
2. Running builds and tests in bulk or in parallel.
3. Handling build cache intelligently — a huge advantage when build times start to hurt.

Knowledge‑Base Management in the AI Era

A knowledge base only has value if it’s actually referenced. To be referenced easily, knowledge needs to be close together.

With a monorepo, cloning a single GitHub repository gives you everything in one place:

• Application code
• Development documentation
• Agent skills (e.g., Claude, Codex)

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.

Common Objection & Re‑framing

“Frontend and backend only need to communicate via API contracts — mixing their contexts is unnecessary.”

In the age of AI‑assisted coding, the leverage comes from architectures that let you see the full picture and move fast — not from strict context separation.

When Monorepos Shine (Especially with AI‑Era Development)

1. Your backend is written in TypeScript

   • A mixed stack (e.g., TypeScript frontend, Python backend) can technically be a monorepo, but shared packages/ become frontend‑only, narrowing their value.
   • You also end up managing linting, formatting, and tooling for two different languages.
   • Note: 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.

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.
   • If you still enforce 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.

Real‑World Example: Chronock

My own app, Chronock, is built as a monorepo with TypeScript across the full stack.

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 main app, giving the whole product—including its public‑facing site—one source of truth.
• Shared contracts, i18n utilities, and TypeScript configuration are centralized in packages/, reducing duplication.
• Specs and AI‑agent skill definitions (.claude/, .codex/) sit right next to the code they describe, making the knowledge base instantly accessible.

TL;DR

• Monorepos provide a single source of truth for code, docs, and AI‑agent skills.
• Turborepo is the go‑to tool for TypeScript‑centric monorepos, offering parallel builds, intelligent caching, and a unified workflow.
• Align your stack on TypeScript and adapt your review process for AI‑assisted development to reap the biggest benefits.

Stay tuned for the next installment, where we’ll dive into version‑control strategies and CI/CD pipelines for AI‑first monorepos.

Overview

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.

Front‑end ↔ Back‑end Communication

• Uses Connect RPC (Protocol Buffers).
• The .proto definition files live in packages/contract, making it seamless to manage the interface definition and run code generation for both front‑end and back‑end from a single location.

Repository Structure

• Product specs and agent skills live in the same repository.
• This centralization makes coding agents noticeably more effective—they have the context they need without jumping across repos.

Summary

Architecture choices for the AI era

1. Centralize context in a monorepo and treat it as a living knowledge base.
2. Align your stack on TypeScript – it pays off in multiple ways.
3. The pull‑request problem doesn’t solve itself; it needs its own dedicated solution.

That’s a wrap for Part 1.