tomevault-io Design
Code, component, and API design evaluation.
Abstraction Quality
Naming
- Does
processData()actually process data? - Do names reveal intent?
- Consistent vocabulary (don't mix "user" and "account" for same concept)?
Red flags:
Manager,Handler,Processor,Utils— often god classes- Single-letter names outside tight loops
- Abbreviations that aren't universally known
Single Responsibility
- One reason to change?
- Can you describe the class without using "and"?
Test: "The {ClassName} is responsible for..." — if you need "and", split it.
Leaky Abstractions
- Does implementation leak through interface?
- Are internal data structures exposed?
Example leak:
// Leaky — exposes internal Map structure
class Cache {
getAll(): Map<string, Value> { return this.internal; }
}
// Clean — hides implementation
class Cache {
entries(): Array<[string, Value]> { return [...this.internal]; }
}
Tell, Don't Ask
- Behavior on objects vs external orchestration?
- Objects should do things, not just hold data
Ask (bad):
if (order.status === 'pending' && order.items.length > 0) {
order.status = 'confirmed';
}
Tell (good):
order.confirm(); // Object owns its state transitions
SOLID Compliance
| Principle | Question | Violation Signal |
|---|---|---|
| Single Responsibility | One reason to change? | Class has multiple "and"s |
| Open/Closed | Extend without modifying? | Switch statements on types |
| Liskov Substitution | Subtypes substitutable? | Instanceof checks |
| Interface Segregation | Clients use what they depend on? | Empty method implementations |
| Dependency Inversion | Depend on abstractions? | new ConcreteClass() in domain |
API Design
Protocol Selection
| Protocol | Best For | Avoid When |
|---|---|---|
| REST | CRUD, public APIs, caching | Real-time, complex queries |
| GraphQL | Flexible queries, multi-client | Simple CRUD, N+1 risk |
| gRPC | Internal services, performance | Browser clients |
| WebSocket/SSE | Real-time updates | Request-response |
Universal Principles
- Contract-First: Define API before implementation
- Consistency: Same patterns everywhere
- Evolvability: Version from day one
- DX: Clear errors, good docs
DX (Developer Experience)
- Onboarding: Can a new dev understand in 15 minutes?
- Error Messages: Actionable or cryptic?
- Documentation: Matches reality?
- Conventions: Consistent with ecosystem?
Guild Members for Design
Primary: Karman (naming/abstractions), Ace (DX), Burner (coupling) Secondary: Dijkstra (correctness), Vector (auth for APIs)
Output Format
## Design Review: {Component}
### Abstraction Quality
- {Finding 1}
- {Finding 2}
### SOLID Violations
- {Principle}: {violation}
### API Assessment (if applicable)
- {Finding}
### DX Friction Points
- {Point 1}
### Recommendations
1. {Action}
2. {Action}
Additional Resources
references/solid-gotchas.md— Common SOLID violations with fixesreferences/api-rest.md— REST production gotchasreferences/api-graphql.md— GraphQL N+1, complexity, caching trapsreferences/api-grpc.md— gRPC streaming, versioning gotchas
Converted and distributed by TomeVault — claim your Tome and manage your conversions.