Vanity Engineering Review

# Vanity Engineering Detection Patterns

Concrete patterns to scan for during review. Each pattern includes what to look for,
why it qualifies as vanity, and what the simpler alternative is.

---

## Category 1: Premature Abstraction

### Single-Implementation Interfaces
**Signal**: Interface/abstract class/trait with exactly one concrete implementation.
**Why vanity**: Abstraction without variation is indirection. It adds a file, a concept,
and a navigation hop for zero polymorphic benefit.
**Simpler alternative**: Use the concrete implementation directly. Extract an interface
when (not if) a second implementation actually materialises.
**Severity**: V1 (one or two instances), V2 (systemic pattern across the codebase)

### Plugin Systems with No Plugins
**Signal**: Registration/discovery/loading mechanism for extensibility, with 0-2 "plugins"
that are all maintained by the same team.
**Why vanity**: Plugin architecture is one of the most expensive abstractions to maintain.
It introduces indirection, configuration complexity, versioning concerns, and testing
surface area. Justified only when third parties actually write plugins.
**Simpler alternative**: Direct function calls. If-else chains. A switch statement.
**Severity**: V2 minimum, V3 if other code must conform to the plugin API

### Generic-Everything
**Signal**: Extensive use of generics/templates where only one or two concrete types
are ever used. Type parameters that could be replaced with the actual type.
**Why vanity**: Generics are useful when you genuinely operate over multiple types.
When you do not, they are noise that makes every type signature harder to read.
**Simpler alternative**: Use concrete types. Genericise when you add the second type.
**Severity**: V1

---

## Category 2: Resume-Driven Architecture

### Microservices at Monolith Scale
**Signal**: Multiple deployed services, service mesh, API gateway — serving traffic
that a single process could handle. Fewer than 10 requests per second across all services.
**Why vanity**: Microservices trade code complexity for operational complexity. This trade
only pays off at scale that demands independent deployment and scaling. Below that, you
are paying the operational tax (networking, serialisation, distributed tracing, deployment
orchestration) for zero benefit.
**Simpler alternative**: Monolith with clean module boundaries. Deploy as one thing.
**Severity**: V3 (forces every feature to deal with network boundaries)

### Kubernetes for a Single Container
**Signal**: K8s manifests, Helm charts, operators — for an application that runs as
one replica with no scaling requirements.
**Why vanity**: Kubernetes is an orchestration platform for managing many containers at scale.
Using it to run one container is like hiring a logistics company to deliver a letter.
**Simpler alternative**: Docker Compose. Or just a systemd service.
**Severity**: V2

### Event-Driven Architecture for Synchronous Workflows
**Signal**: Message queues, event buses, pub/sub — for workflows that are inherently
request-response and need the result immediately.
**Why vanity**: Async messaging adds eventual consistency, retry logic, dead letter queues,
and debugging difficulty. Justified for decoupled, high-throughput, fire-and-forget
workloads. Not justified for "user clicks button, needs result now."
**Simpler alternative**: Function call. HTTP request. Database query.
**Severity**: V2

---

## Category 3: Complexity Theater

### Custom Implementations of Solved Problems
**Signal**: Hand-rolled authentication, custom ORM, bespoke state management, homegrown
logging framework, custom build tooling — where battle-tested alternatives exist.
**Why vanity**: "Not invented here" syndrome. The custom version is always worse than the
community-maintained version because it has one contributor and zero external scrutiny.
**Simpler alternative**: Use the established library. Passport/Auth.js for auth. Prisma/Drizzle
for ORM. Pino/Winston for logging. Un