ZacharyZhang-NY
e74dafcd36
Three independently ugly bugs that all fed the same log flood:
* Electron's `WebFrameMain.send` writes every "Render frame was disposed"
to stderr via `console.error`. When the worker fans a second
agent-event past a reloading renderer, we produced thousands of
identical lines and stalled the main loop on stderr I/O. Added a
`mainFrame.detached` guard so the send is short-circuited before
Electron's own catch block fires, and installed a targeted filter in
`suppress-warnings.ts` (now actually imported from the entry point)
so the specific `console.error("Error sending from webFrameMain:"…)`
noise never reaches the terminal. Any other payload still surfaces.
* `dispatchAgentMessage` accepted the human-reader sentinel as a wake
target when an agent replied to `__board__` — `wakeAgentIfPossible`
then called `db.getAgent("__board__")`, threw, and the dispatcher
kept repeating on every send. Strip `HUMAN_SENDER_ID` at
`resolveMessageWakeTargets`, and keep a defense-in-depth guard in the
heartbeat so a stray caller (future automation fan-out) cannot
reintroduce the crash.
* Pi's skills loader rejects any SKILL.md whose frontmatter `name`
diverges from its parent directory. The four bundled `my-writing-style`
copies declared `name: writing-style-skill`, so every install emitted
a warning and dropped the skill. They also lived as orphan gitlinks
(mode 160000 without .gitmodules), and the global `*.md` gitignore
hid every other SKILL.md from version control. Fixed the frontmatter
to match the dir, converted the dangling submodules to plain trees,
and allowlisted `builtin-skills/**/*.md` so a fresh clone carries the
catalogue instead of silently losing it.
95 lines
5.7 KiB
Markdown
95 lines
5.7 KiB
Markdown
---
|
|
title: Services Must Have Internal Clean Architecture
|
|
impact: MEDIUM-HIGH
|
|
impactDescription: microservices don't replace architecture, they require it
|
|
tags: bound, services, microservices, internal
|
|
---
|
|
|
|
## Services Must Have Internal Clean Architecture
|
|
|
|
Breaking a monolith into microservices doesn't solve architectural problems. Each service still needs internal architecture. Services are a deployment option, not an architecture.
|
|
|
|
**Incorrect (microservices as architecture replacement):**
|
|
|
|
```text
|
|
"We use microservices architecture"
|
|
|
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
│ order-service │ │ user-service │ │ payment-service │
|
|
│ │ │ │ │ │
|
|
│ routes.js │ │ routes.js │ │ routes.js │
|
|
│ database.js │ │ database.js │ │ database.js │
|
|
│ helpers.js │ │ helpers.js │ │ helpers.js │
|
|
│ │ │ │ │ │
|
|
│ (No layers, │ │ (No layers, │ │ (No layers, │
|
|
│ no boundaries,│ │ no boundaries,│ │ no boundaries,│
|
|
│ just smaller │ │ just smaller │ │ just smaller │
|
|
│ messes) │ │ messes) │ │ messes) │
|
|
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
|
|
|
# Result: Distributed monolith
|
|
# All the downsides of microservices (network, deployment, consistency)
|
|
# None of the benefits (each service still a tangled mess)
|
|
```
|
|
|
|
**Correct (clean architecture within each service):**
|
|
|
|
```text
|
|
┌───────────────────────────────────────────────────────────┐
|
|
│ order-service │
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
│ │ domain/ │ │
|
|
│ │ Order.ts OrderLine.ts OrderStatus.ts │ │
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
│ │ application/ │ │
|
|
│ │ PlaceOrderUseCase.ts │ │
|
|
│ │ ports/ │ │
|
|
│ │ OrderRepository.ts │ │
|
|
│ │ PaymentGateway.ts ← calls payment-service │ │
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
│ │ infrastructure/ │ │
|
|
│ │ PostgresOrderRepository.ts │ │
|
|
│ │ HttpPaymentGateway.ts → payment-service API │ │
|
|
│ │ KafkaEventPublisher.ts │ │
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
│ │ interface/ │ │
|
|
│ │ OrderController.ts │ │
|
|
│ │ OrderEventHandler.ts │ │
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
└───────────────────────────────────────────────────────────┘
|
|
|
|
# Each service has:
|
|
# - Domain layer with business rules
|
|
# - Application layer with use cases and ports
|
|
# - Infrastructure layer implementing ports
|
|
# - Clean dependency direction within service
|
|
```
|
|
|
|
**Cross-service communication:**
|
|
```typescript
|
|
// application/ports/PaymentGateway.ts
|
|
interface PaymentGateway {
|
|
charge(amount: Money, method: PaymentMethod): Promise<PaymentResult>
|
|
}
|
|
|
|
// infrastructure/HttpPaymentGateway.ts
|
|
class HttpPaymentGateway implements PaymentGateway {
|
|
async charge(amount: Money, method: PaymentMethod): Promise<PaymentResult> {
|
|
// Calls payment-service over HTTP
|
|
// Service boundary is an infrastructure detail
|
|
const response = await fetch('http://payment-service/charge', { ... })
|
|
return this.mapResponse(response)
|
|
}
|
|
}
|
|
```
|
|
|
|
**Benefits:**
|
|
- Services testable without other services
|
|
- Can extract or merge services without rewriting business logic
|
|
- Network boundaries don't compromise internal architecture
|
|
|
|
Reference: [Clean Architecture - Services: Great and Small](https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/ch27.xhtml)
|