Ten architecture words.Three real questions.

opsvo/              ← a single git repository
  apps/
    api/
    storefront/
    admin-console/
  packages/
    ui/
    shared-types/

opsvo-api/          ← repo 1
opsvo-storefront/   ← repo 2
opsvo-admin/        ← repo 3
opsvo-ui/           ← repo 4, published to npm

Level 2: the workspace wiring that makes a monorepo bearable.

In a monorepo, apps reference shared packages by name, and the workspace tool links them on disk instead of downloading from a registry. No version numbers, no publishing.

// pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

// apps/api/package.json
{
  "dependencies": {
    "@opsvo/shared-types": "workspace:*"   ← linked locally, not downloaded
  }
}

The payoff is the atomic commit. Change a type and its consumer together, and CI verifies the whole thing at once:

$ git commit -m "add currency to Order"
  modified: packages/shared-types/order.ts
  modified: apps/api/src/orders/create.ts
  modified: apps/storefront/src/cart.tsx
# one commit. one review. never half-migrated.

In polyrepo that same change is three pull requests plus a version bump, and there is a window where the published package and its consumers disagree.

Level 3: what breaks at scale, and how teams fix it.

Monorepos fail on CI time. The fix is an affected graph: the tool computes which projects depend on the changed files and only builds those.

$ npx nx affected --target=test --base=origin/main

  ✓ shared-types  (changed)
  ✓ api           (depends on shared-types)
  - storefront     skipped, not affected
  - admin-console  skipped, not affected

# 2 of 4 projects built. this is why the tooling exists.

Three more things serious monorepos add:

• Remote build cache: a task with identical inputs is never rebuilt, on any machine. CI restores the previous output instead.
• Module boundary rules: a lint rule that fails the build when a project imports something it should not. This is what stops a monorepo becoming a mud ball.
• Sparse checkout: at Google scale nobody clones everything; you materialise only the paths you touch.

Here is a boundary rule, which matters far more than it looks. It is the same idea that will make modular monoliths work later:

// .eslintrc: nx enforce-module-boundaries
{
  "sourceTag": "scope:storefront",
  "onlyDependOnLibsWithTags": ["scope:shared"]
}

// storefront importing from admin now fails CI:
import { AuditLog } from '@opsvo/admin/internals'
   ✗ scope:storefront cannot depend on scope:admin

The polyrepo failure mode is the mirror image: no CI problem, but a "diamond dependency" mess where two services need incompatible versions of the same shared library, and nobody can upgrade without coordinating a release train.

src/
  modules/
    orders/
      index.ts        ← the ONLY file others may import
      service.ts      ← private
      repository.ts   ← private
    inventory/
      index.ts
      service.ts

import { placeOrder } from '../orders'          ✓ goes through index.ts

import { OrderRepo } from '../orders/repository'  ✗ reaches inside

Level 2: making the rule real instead of aspirational.

A rule nobody checks is a suggestion. Put it in CI with dependency-cruiser or an ESLint boundaries plugin:

// .dependency-cruiser.js
{
  name: 'no-deep-module-imports',
  severity: 'error',
  from: { path: '^src/modules/([^/]+)/' },
  to:   {
    path: '^src/modules/([^/]+)/.+',
    pathNot: '^src/modules/$1/',      own folder is fine
    pathNot: '^src/modules/[^/]+/index.ts$'  public door is fine
  }
}

Then the data half, which people skip and later regret. Each module gets its own schema, so a cross-module join is not merely discouraged: it is visible in the SQL:

// prisma/schema.prisma
model Order {
  id     String @id
  @@schema("orders")
}
model StockItem {
  id     String @id
  @@schema("inventory")
}

-- this now looks obviously wrong in a code review:
SELECT * FROM orders.order o JOIN inventory.stock_item s ...

Modules ask each other in code, not in SQL:

// orders/service.ts
const ok = await inventory.reserve(items)   ← a normal function call

Level 3: designing for the extraction you may never do.

The advanced move is to make every cross-module call look exactly like a network call would, without being one. Define the contract as an interface, inject the implementation:

// orders/ports.ts: orders declares what it NEEDS
export interface InventoryPort {
  reserve(items: LineItem[]): Promise<Reservation>
}

// wiring/container.ts, today it is in-process
const inventoryPort: InventoryPort = new LocalInventoryAdapter(inventoryService)

// tomorrow, if you ever extract it: one line changes
const inventoryPort: InventoryPort = new HttpInventoryAdapter('https://inventory.internal')

Because the call was always async and always went through an interface, extraction becomes configuration rather than a rewrite. But note carefully what that one line silently introduces:

• The call can now time out, and you will not know whether the reservation happened.
• You need a retry policy, and therefore an idempotency key so a retry does not double-reserve.
• You lose the shared database transaction that used to make order-plus-reservation atomic.

Which is why the honest advice is: build the seam, then do not use it until something forces you. Keep a checklist of what a module must satisfy before it earns extraction: owns its tables, no shared transactions with others, communicates only through its port, has its own metrics.

The transactional point is the one that bites hardest. In-process you get this for free:

await db.$transaction(async (tx) => {
  await orders.create(tx, order)
  await inventory.reserve(tx, items)   both commit or neither does
})

Split them across services and that guarantee is gone. You replace it with a saga: reserve first, create the order, and if the order fails, issue a compensating action that releases the reservation. That is real work, and it is the true price of the split.

Modular monolith
  rebuild 1 image → redeploy → everything restarts together
  deploy units: 1   → not distributed

Microservices
  rebuild checkout-service → redeploy it alone
  orders-service never restarts and does not notice
  deploy units: many → distributed

Level 2: the timeout that has no answer.

Here is the failure that does not exist in a monolith:

try {
  await paymentService.charge(orderId, amount)   HTTP call
} catch (e) {
  // e.code === 'ETIMEDOUT'
  // Did the customer get charged? UNKNOWABLE from here.
}

You cannot fix this by retrying blindly, because a retry might charge twice. You fix it by making the operation idempotent: the caller sends a key, the callee remembers it:

// caller: same key on every retry of the same logical charge
await payments.charge({
  idempotencyKey: `order-${orderId}-charge`,
  amount
})

// callee: seen this key? return the old result, do nothing new
const prior = await db.charges.findUnique({ where: { key } })
if (prior) return prior.result

Every distributed system ends up building this. It is not optional, and it is pure overhead you did not need in-process.

Level 3: the tax bill in full.

Once you are distributed, these stop being nice-to-haves:

• Correlation IDs and distributed tracing: a stack trace no longer spans the request. You need OpenTelemetry to reassemble one user action from five services' logs.
• Circuit breakers and timeouts everywhere: a slow dependency will otherwise exhaust your connection pool and take you down with it.
• Backpressure: a fast producer will drown a slow consumer unless something pushes back.
• Contract versioning: you cannot deploy both sides at once, so every change must be backward compatible for at least one release. Expand, migrate, contract.
• Eventual consistency: different services briefly disagree about the truth, and the UI has to be honest about that.

The backward-compatible rollout is the one people underestimate. You cannot rename a field:

// ✗ deploys are not simultaneous: this breaks in the gap
- { total: number }
+ { totalAmount: number }

// ✓ expand → migrate → contract, over three releases
release 1: { total: number, totalAmount: number }  write both
release 2: all consumers read totalAmount
release 3: { totalAmount: number }                 drop the old field

And the deepest one: you cannot have consistency, availability and partition tolerance all at once. Partitions happen whether you like it or not, so every distributed design is really choosing between staying consistent and staying available when the network splits. In a monolith that question never arises.

GET /assets/main-a3f2b1.js
     ↑ shell + cart + search + checkout, all in one file

# one request. one file. one deploy produced it.

// apps/shell/src/App.tsx
import { CartWidget } from '@opsvo/cart'
import { SearchBar }  from '@opsvo/search'

// just imports. nothing clever happening.

Level 2: ownership without a network, plus lazy loading.

You get real boundaries from CODEOWNERS and lint rules, exactly like the modular monolith on the backend:

# .github/CODEOWNERS
/packages/cart/     @opsvo/team-cart
/packages/search/   @opsvo/team-search
/apps/shell/        @opsvo/team-platform

People often confuse code splitting with micro-frontends. It is not the same thing. Lazy loading splits the bundle, but it is still one deploy:

const Checkout = React.lazy(() => import('@opsvo/checkout'))

// browser now fetches:
GET /assets/main-a3f2b1.js
GET /assets/checkout-7d21c9.js   ← separate FILE...

// ...but produced by the SAME build, from the SAME deploy.
// still one deploy unit. still not distributed.

Deploy units are counted by "how many things can I ship separately", not by "how many files does the browser fetch".

Level 3: scaling this to many teams before reaching for runtime.

Most teams that think they need runtime micro-frontends actually need a better build-time setup. Three techniques buy you a long runway:

• Affected builds: CI only rebuilds and retests the packages a change touched, so a shared deploy is still fast.
• Contract-tested boundaries: each package exports a typed public API, and a type test fails CI if it changes incompatibly.
• Trunk-based deploys with feature flags: teams merge continuously and control their own release timing by flag, not by deploy. This is the key move: it gives you release independence without deploy independence.

That last one deserves the code, because it solves the actual problem people buy Module Federation for:

// the cart team ships code every day, dark, behind a flag
export function CartWidget() {
  const flags = useFlags()
  return flags.cartRedesign
    ? <CartV2 />
    : <CartV1 />
}

// release = flip a flag in the dashboard, no deploy at all.
// rollback = flip it back, in seconds, not a revert + rebuild.

Compare the rollback stories honestly. Flag flip: seconds, no build. Runtime micro-frontend rollback: republish the previous remote bundle and hope no other remote depended on the new one. Feature flags are strictly better for most teams, and cost a fraction as much.

GET /assets/shell-9c1d.js       ← shell team's deploy
GET /cart/remoteEntry.js        ← cart team's deploy
GET /search/remoteEntry.js      ← search team's deploy

# three files from three separate deployments,
# assembled in the browser at load time.

Level 2: the configuration, and the line that matters most.

// cart/vite.config.ts, the REMOTE (producer)
federation({
  name: 'cart',
  filename: 'remoteEntry.js',
  exposes: { './CartWidget': './src/CartWidget' },
  shared: { react: { singleton: true, requiredVersion: '^18.2.0' } }
})

// shell/vite.config.ts, the HOST (consumer)
federation({
  name: 'shell',
  remotes: { cart: 'https://cdn.opsvo.in/cart/remoteEntry.js' },
  shared: { react: { singleton: true } }
})

Consuming it looks almost normal, except the import target does not exist on your disk:

const CartWidget = React.lazy(() => import('cart/CartWidget'))
// resolved over HTTP at runtime, from someone else's deploy

singleton: true is the line that keeps you alive. Without it two copies of React load, hooks break in ways that make no sense, and context providers silently stop reaching their consumers.

Level 3: everything that will actually go wrong.

1. Version skew is a runtime failure your CI cannot see. The remote was built against React 18.3; the shell negotiated 18.2. Nothing fails at build time on either side, because they were never built together.

// what you see in production, with no useful stack trace:
Uncaught TypeError: Cannot read properties of null (reading 'useState')
// meaning: two React copies. hooks resolved against the wrong one.

2. A broken remote takes down the shell unless you defend every mount point:

<ErrorBoundary fallback={<CartUnavailable />}>
  <Suspense fallback={<Skeleton />}>
    <CartWidget />
  </Suspense>
</ErrorBoundary>

// without this, one 404 on remoteEntry.js = white screen.

3. Types do not cross the boundary for free. TypeScript cannot see into a URL, so you need generated declaration packages published by each remote, which reintroduces exactly the version coordination you were trying to escape.

4. Everything else gets harder: end-to-end tests need every remote deployed somewhere; CSS leaks between independently built bundles unless scoped; tracing a bug means correlating three deploy histories; and the design system becomes a shared dependency that drifts per remote.

// order.ts
import { prisma } from '../db'
import Stripe from 'stripe'

export async function placeOrder(userId, items) {
  const order = await prisma.order.create({ data: {...} })
  await new Stripe(KEY).charges.create({ amount: order.total })
}

// domain/ports.ts, the plug shapes
export interface OrderRepository { save(o: Order): Promise<void> }
export interface PaymentGateway  { charge(a: Money): Promise<Receipt> }

// domain/place-order.ts, imports NOTHING from prisma/stripe
export async function placeOrder(
  deps: { orders: OrderRepository, payments: PaymentGateway },
  cmd: PlaceOrderCommand
) { /* pure business rules */ }

// infrastructure/prisma-order-repository.ts
import { OrderRepository } from '../domain/ports'   ← arrow points INWARD
export class PrismaOrderRepository implements OrderRepository { ... }

Level 2: why the tests get dramatically better.

This is the payoff you feel daily. The business rule test needs no database, no network, no mocking library:

// a fake that is 4 lines, not a mock framework
class InMemoryOrders implements OrderRepository {
  saved: Order[] = []
  async save(o: Order) { this.saved.push(o) }
}

test('orders over 50k need approval', async () => {
  const orders = new InMemoryOrders()
  await placeOrder({ orders, payments: new FakePayments() }, bigOrder)
  expect(orders.saved[0].status).toBe('PENDING_APPROVAL')
})

// runs in 3ms. no docker. no test database. no flakiness.

Then wiring, which is where the real implementations get plugged in, in one place at startup:

// wiring/container.ts, the only file that knows about BOTH sides
export const deps = {
  orders:   new PrismaOrderRepository(prisma),
  payments: new RazorpayGateway(process.env.RAZORPAY_KEY)
}

Swapping Stripe for Razorpay is now a one-line change in one file, because no domain code ever mentioned either.

The vocabulary map, so you can read any of the three literatures:

Level 3: the mistakes that look like the pattern but are not.

Leaking the ORM through the port. The most common failure. This looks hexagonal and is not:

// ✗ the "domain" now depends on Prisma's generated types
import type { Order } from '@prisma/client'
export interface OrderRepository { save(o: Order): Promise<void> }

// ✓ the domain owns its own type; infrastructure maps to it
export class Order { constructor(readonly id: OrderId, ...) {} }
export interface OrderRepository { save(o: Order): Promise<void> }

If your grep for prisma in src/domain/ hits a type import, you have not done it.

Anemic domain. If your entities are bare data bags and every rule lives in a service, you have layered architecture with extra folders, not hexagonal. Rules belong on the objects that own the data.

Ports defined by the provider, not the need. A port named StripePort with methods mirroring Stripe's API is an adapter wearing an interface. The domain should declare PaymentGateway.charge(Money) because that is what the business needs: the shape comes from the inside, not the vendor.

Enforce it mechanically, or it decays within two sprints:

// .dependency-cruiser.js
{
  name: 'domain-stays-pure',
  severity: 'error',
  from: { path: '^src/domain' },
  to:   { path: 'node_modules|^src/infrastructure|^src/http' }
}

And the payoff that connects back to axis 2: a module whose domain imports nothing can be lifted into its own service by writing one new adapter. A module welded to the framework is a rewrite. Hexagonal architecture is what buys you the option to go distributed without forcing you to.

src/
  controllers/    HTTP in, HTTP out
  services/       business logic
  repositories/   database access
  models/         data shapes

// the rule: each layer calls only downward.
controller → service → repository → database

[ browser ]  ←HTTP→  [ app server ]  ←SQL→  [ database ]
   tier 1              tier 2                 tier 3

Level 2: the leak, and Redux as one concrete GUI pattern.

Here is how layered quietly turns into a mess:

// services/order-service.ts, the "business" layer
import type { Order } from '@prisma/client'   ← the leak

export async function approve(order: Order) { ... }

// business logic now depends on the database schema.
// rename a column → business layer changes. this is what
// hexagonal was invented to stop.

On the UI side, the unidirectional pattern is the one you will actually meet:

// 1. something happens → an ACTION describes it
dispatch({ type: 'cart/itemAdded', payload: { sku, qty } })

// 2. a REDUCER computes the new truth. pure function.
function cart(state, action) {
  if (action.type === 'cart/itemAdded')
    return { ...state, items: [...state.items, action.payload] }
  return state
}

// 3. the VIEW re-renders from the new truth
// data flows ONE way. the view never mutates state directly.

Notice that reducer is a pure business rule with no framework in it: the same instinct as hexagonal, arrived at from the UI side.

Level 3: choosing between the GUI patterns, and how tiers stack.

The useful realisation: a full system runs several axis-3 answers at once, one per tier, and that is completely normal.

tier 1: browser
   Flux/MVU inside          (actions → reducers → render)

tier 2: application server
   Hexagonal inside         (ports, adapters, pure domain)
   + a BFF layer shaping responses for this specific UI

tier 3: database
   schema per module        (from the modular monolith rules)

One more thing worth knowing, because it explains a lot of real systems: the BFF (backend for frontend) is a thin tier-2 layer that exists purely to shape data for one client. Mobile and web get different BFFs over the same domain, so neither client has to make six round trips or receive fields it will not use.

Finally, the honest verdict on layered versus hexagonal: layered is easier to teach and fine for CRUD. The moment your business rules become interesting, the leak in the middle layer starts costing you, and that is your signal to invert the dependency.

// DIRECT: order module now depends on three modules
await inventory.reserve(items)
await email.sendConfirmation(order)
await analytics.track(order)

// EVENT-DRIVEN: order module depends on nothing
await bus.publish(new OrderPlaced(order))

// inventory/subscribers.ts
bus.on('OrderPlaced', e => reserve(e.items))

// email/subscribers.ts
bus.on('OrderPlaced', e => sendConfirmation(e.orderId))

Level 2: in-process events, which is where you should start.

You do not need Kafka to be event-driven. This is a complete, useful implementation:

// shared/bus.ts, the entire "infrastructure"
type Handler = (e: any) => Promise<void>
const handlers = new Map<string, Handler[]>()

export const bus = {
  on(type: string, h: Handler) {
    handlers.set(type, [...(handlers.get(type) ?? []), h])
  },
  async publish(e: { type: string }) {
    for (const h of handlers.get(e.type) ?? []) await h(e)
  }
}

Now the important design decision: should the event be part of the caller's transaction?

// SYNCHRONOUS in-process: subscribers run inside the same
// transaction. if email fails, the ORDER rolls back. usually wrong.

// better: commit first, then publish
await db.$transaction(tx => orders.save(tx, order))
await bus.publish(new OrderPlaced(order))   ← after commit

Event names matter more than people expect. Name them as facts in the past tense: OrderPlaced, PaymentCaptured. If you find yourself writing SendEmailCommand, that is a command, not an event, and it belongs as a direct call.

Level 3: what changes when the bus becomes a real broker.

Swap the in-memory bus for Kafka or SNS and you have crossed onto axis 2: you are now distributed, with every cost from that section. Three problems appear immediately.

1. The dual-write problem. This code is broken and it looks fine:

await db.orders.save(order)          ✓ committed
await kafka.publish(orderPlaced)    ✗ process dies here

// order exists. nobody was ever told. permanently inconsistent.

The fix is the transactional outbox: write the event into your own database in the same transaction, and let a separate process publish it.

await db.$transaction(async tx => {
  await tx.orders.create({ data: order })
  await tx.outbox.create({ data: { type: 'OrderPlaced', payload } })
})
// both commit or neither. a relay polls outbox → publishes → marks sent.

2. Delivery is at-least-once, so handlers must be idempotent. Your email subscriber will eventually receive the same event twice. Deduplicate on event ID.

3. Choreography drifts. With enough events reacting to events, no one can answer "what happens when an order is placed" without reading the whole system. The counterweight is orchestration: a single explicit workflow that calls steps in order and owns the compensations. Rule of thumb: choreography for notifications, orchestration for anything with money in it.

One more distinction worth carrying, because it decides your payload design:

$ cat access.log | grep ERROR | cut -d' ' -f4 | sort | uniq -c

# four stages. none knows about the others.
# each reads text, writes text, and stops thinking.

type Stage<A, B> = (input: A) => Promise<B>

const fetch:  Stage<Url, Raw>      = url => http.get(url)
const parse:  Stage<Raw, Record[]> = raw => xml.parse(raw)
const enrich: Stage<Record[], Record[]> = rs => rs.map(addMeta)
const store:  Stage<Record[], void> = rs => db.insertMany(rs)

// composed:
await store(await enrich(await parse(await fetch(url))))

Level 2: composition, and why streaming matters.

Nested calls get ugly fast, so pipelines are usually composed:

const pipeline = compose(fetch, parse, enrich, store)
await pipeline(url)

// adding a stage is now a one-line edit, no neighbours touched:
const pipeline = compose(fetch, parse, validate, enrich, store)

The failure that catches everyone: loading everything into memory between stages. With 34 million records this dies.

// ✗ each stage materialises the FULL dataset
const all = await parse(raw)      // 34M records in RAM

// ✓ stream: records flow through one at a time
await pipeline(
  fs.createReadStream('dump.xml'),
  parseStream(),
  enrichStream(),
  batchInsertStream(1000)
)
// constant memory, regardless of input size.
// backpressure is automatic: a slow writer slows the reader.

Level 3: durable pipelines and where stages become distributed.

An in-process pipeline dies with the process. For long jobs you make each stage a queue, which gives you retries, persistence and independent scaling per stage:

// each stage = its own queue and worker
new Worker('fetch',  async job => {
  const raw = await http.get(job.data.url)
  await parseQueue.add('parse', { raw })       hand off
})

new Worker('parse',  async job => { ... }, { concurrency: 4  })
new Worker('enrich', async job => { ... }, { concurrency: 20 })  ← the slow one
new Worker('store',  async job => { ... }, { concurrency: 2  })

Now you have independently tunable stages, and you have also quietly become distributed, so every rule from that section applies: stages must be idempotent, because a worker crash means the job is retried.

Two design points that separate a real pipeline from a fragile one:

• Failure routing. One bad record must not stop 34 million good ones. Bad records go to a dead-letter queue for inspection; the pipeline continues.
• Per-stage observability. Measure throughput and depth at each stage. The stage whose queue grows without bound is your bottleneck, and this is the only easy way to find it.

Finally, note how the patterns compose rather than compete. A realistic request in a well-built system is all of them at once:

An HTTP adapter (hexagonal) in the app tier (multi-tier)
invokes a use case that publishes OrderPlaced (event-driven),
which a worker picks up and runs through
fetch → validate → enrich → persist (pipeline).

Four axis-3 patterns, one request, no conflict. Choose per module by what that module's work actually looks like: transformation work wants a pipeline, fan-out work wants events, business-rule work wants ports and adapters.