Silence render-disposed spam, unbreak bundled skills, drop board wake
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.
This commit is contained in:
1 parent
7a9a6779b0
commit
e74dafcd36
287 files changed
+59858
-10
No files matched your search
@@ -0,0 +1,412 @@
|
||||
# Technology Decision Guide
|
||||
|
||||
Decision frameworks and comparison matrices for common technology choices.
|
||||
|
||||
## Decision Frameworks Index
|
||||
|
||||
1. [Database Selection](#1-database-selection)
|
||||
2. [Caching Strategy](#2-caching-strategy)
|
||||
3. [Message Queue Selection](#3-message-queue-selection)
|
||||
4. [Authentication Strategy](#4-authentication-strategy)
|
||||
5. [Frontend Framework Selection](#5-frontend-framework-selection)
|
||||
6. [Cloud Provider Selection](#6-cloud-provider-selection)
|
||||
7. [API Style Selection](#7-api-style-selection)
|
||||
|
||||
---
|
||||
|
||||
## 1. Database Selection
|
||||
|
||||
### SQL vs NoSQL Decision Matrix
|
||||
|
||||
| Factor | Choose SQL | Choose NoSQL |
|
||||
|--------|-----------|--------------|
|
||||
| Data relationships | Complex, many-to-many | Simple, denormalized OK |
|
||||
| Schema | Well-defined, stable | Evolving, flexible |
|
||||
| Transactions | ACID required | Eventual consistency OK |
|
||||
| Query patterns | Complex joins, aggregations | Key-value, document lookups |
|
||||
| Scale | Vertical (some horizontal) | Horizontal first |
|
||||
| Team expertise | Strong SQL skills | Document/KV experience |
|
||||
|
||||
### Database Type Selection
|
||||
|
||||
**Relational (SQL):**
|
||||
| Database | Best For | Avoid When |
|
||||
|----------|----------|------------|
|
||||
| PostgreSQL | General purpose, JSON support, extensions | Simple key-value only |
|
||||
| MySQL | Web applications, read-heavy | Complex queries, JSON-heavy |
|
||||
| SQLite | Embedded, development, small apps | Concurrent writes, scale |
|
||||
|
||||
**Document (NoSQL):**
|
||||
| Database | Best For | Avoid When |
|
||||
|----------|----------|------------|
|
||||
| MongoDB | Flexible schema, rapid iteration | Complex transactions |
|
||||
| CouchDB | Offline-first, sync required | High throughput |
|
||||
|
||||
**Key-Value:**
|
||||
| Database | Best For | Avoid When |
|
||||
|----------|----------|------------|
|
||||
| Redis | Caching, sessions, real-time | Persistence critical |
|
||||
| DynamoDB | Serverless, auto-scaling | Complex queries |
|
||||
|
||||
**Wide-Column:**
|
||||
| Database | Best For | Avoid When |
|
||||
|----------|----------|------------|
|
||||
| Cassandra | Write-heavy, time-series | Complex queries, small scale |
|
||||
| ScyllaDB | Cassandra alternative, performance | Small datasets |
|
||||
|
||||
**Time-Series:**
|
||||
| Database | Best For | Avoid When |
|
||||
|----------|----------|------------|
|
||||
| TimescaleDB | Time-series with SQL | Non-time-series data |
|
||||
| InfluxDB | Metrics, monitoring | Relational queries |
|
||||
|
||||
**Search:**
|
||||
| Database | Best For | Avoid When |
|
||||
|----------|----------|------------|
|
||||
| Elasticsearch | Full-text search, logs | Primary data store |
|
||||
| Meilisearch | Simple search, fast setup | Complex analytics |
|
||||
|
||||
### Quick Decision Flow
|
||||
|
||||
```
|
||||
Start
|
||||
│
|
||||
├─ Need ACID transactions? ──Yes──► PostgreSQL/MySQL
|
||||
│
|
||||
├─ Flexible schema needed? ──Yes──► MongoDB
|
||||
│
|
||||
├─ Write-heavy (>50K/sec)? ──Yes──► Cassandra/ScyllaDB
|
||||
│
|
||||
├─ Key-value access only? ──Yes──► Redis/DynamoDB
|
||||
│
|
||||
├─ Time-series data? ──Yes──► TimescaleDB/InfluxDB
|
||||
│
|
||||
├─ Full-text search? ──Yes──► Elasticsearch
|
||||
│
|
||||
└─ Default ──────────────────────► PostgreSQL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Caching Strategy
|
||||
|
||||
### Cache Type Selection
|
||||
|
||||
| Type | Use Case | Invalidation | Complexity |
|
||||
|------|----------|--------------|------------|
|
||||
| Read-through | Frequent reads, tolerance for stale | On write/TTL | Low |
|
||||
| Write-through | Data consistency critical | Automatic | Medium |
|
||||
| Write-behind | High write throughput | Async | High |
|
||||
| Cache-aside | Fine-grained control | Application | Medium |
|
||||
|
||||
### Cache Technology Selection
|
||||
|
||||
| Technology | Best For | Limitations |
|
||||
|------------|----------|-------------|
|
||||
| Redis | General purpose, data structures | Memory cost |
|
||||
| Memcached | Simple key-value, high throughput | No persistence |
|
||||
| CDN (CloudFront, Fastly) | Static assets, edge caching | Dynamic content |
|
||||
| Application cache | Per-instance, small data | Not distributed |
|
||||
|
||||
### Cache Patterns
|
||||
|
||||
**Cache-Aside (Lazy Loading):**
|
||||
```
|
||||
Read:
|
||||
1. Check cache
|
||||
2. If miss, read from DB
|
||||
3. Store in cache
|
||||
4. Return data
|
||||
|
||||
Write:
|
||||
1. Write to DB
|
||||
2. Invalidate cache
|
||||
```
|
||||
|
||||
**Write-Through:**
|
||||
```
|
||||
Write:
|
||||
1. Write to cache
|
||||
2. Cache writes to DB
|
||||
3. Return success
|
||||
|
||||
Read:
|
||||
1. Read from cache (always hit)
|
||||
```
|
||||
|
||||
**TTL Guidelines:**
|
||||
|
||||
| Data Type | Suggested TTL |
|
||||
|-----------|---------------|
|
||||
| User sessions | 24-48 hours |
|
||||
| API responses | 1-5 minutes |
|
||||
| Static content | 24 hours - 1 week |
|
||||
| Database queries | 5-60 minutes |
|
||||
| Feature flags | 1-5 minutes |
|
||||
|
||||
---
|
||||
|
||||
## 3. Message Queue Selection
|
||||
|
||||
### Queue Technology Comparison
|
||||
|
||||
| Feature | RabbitMQ | Kafka | SQS | Redis Streams |
|
||||
|---------|----------|-------|-----|---------------|
|
||||
| Throughput | Medium (10K/s) | Very High (100K+/s) | Medium | High |
|
||||
| Ordering | Per-queue | Per-partition | FIFO optional | Per-stream |
|
||||
| Durability | Configurable | Strong | Strong | Configurable |
|
||||
| Replay | No | Yes | No | Yes |
|
||||
| Complexity | Medium | High | Low | Low |
|
||||
| Cost | Self-hosted | Self-hosted | Pay-per-use | Self-hosted |
|
||||
|
||||
### Decision Matrix
|
||||
|
||||
| Requirement | Recommendation |
|
||||
|-------------|----------------|
|
||||
| Simple task queue | SQS or Redis |
|
||||
| Event streaming | Kafka |
|
||||
| Complex routing | RabbitMQ |
|
||||
| Log aggregation | Kafka |
|
||||
| Serverless integration | SQS |
|
||||
| Real-time analytics | Kafka |
|
||||
| Request/reply pattern | RabbitMQ |
|
||||
|
||||
### When to Use Each
|
||||
|
||||
**RabbitMQ:**
|
||||
- Complex routing logic (topic, fanout, headers)
|
||||
- Request/reply patterns
|
||||
- Priority queues
|
||||
- Message acknowledgment critical
|
||||
|
||||
**Kafka:**
|
||||
- Event sourcing
|
||||
- High throughput requirements (>50K messages/sec)
|
||||
- Message replay needed
|
||||
- Stream processing
|
||||
- Log aggregation
|
||||
|
||||
**SQS:**
|
||||
- AWS-native applications
|
||||
- Simple queue semantics
|
||||
- Serverless architectures
|
||||
- Don't want to manage infrastructure
|
||||
|
||||
**Redis Streams:**
|
||||
- Already using Redis
|
||||
- Moderate throughput
|
||||
- Simple streaming needs
|
||||
- Real-time features
|
||||
|
||||
---
|
||||
|
||||
## 4. Authentication Strategy
|
||||
|
||||
### Method Selection
|
||||
|
||||
| Method | Best For | Avoid When |
|
||||
|--------|----------|------------|
|
||||
| Session-based | Traditional web apps, server-rendered | Mobile apps, microservices |
|
||||
| JWT | SPAs, mobile apps, microservices | Need immediate revocation |
|
||||
| OAuth 2.0 | Third-party access, social login | Internal-only apps |
|
||||
| API Keys | Server-to-server, simple auth | User authentication |
|
||||
| mTLS | Service mesh, high security | Public APIs |
|
||||
|
||||
### JWT vs Sessions
|
||||
|
||||
| Factor | JWT | Sessions |
|
||||
|--------|-----|----------|
|
||||
| Scalability | Stateless, easy to scale | Requires session store |
|
||||
| Revocation | Difficult (need blocklist) | Immediate |
|
||||
| Payload | Can contain claims | Server-side only |
|
||||
| Security | Token in client | Server-controlled |
|
||||
| Mobile friendly | Yes | Requires cookies |
|
||||
|
||||
### OAuth 2.0 Flow Selection
|
||||
|
||||
| Flow | Use Case |
|
||||
|------|----------|
|
||||
| Authorization Code | Web apps with backend |
|
||||
| Authorization Code + PKCE | SPAs, mobile apps |
|
||||
| Client Credentials | Machine-to-machine |
|
||||
| Device Code | Smart TVs, CLI tools |
|
||||
|
||||
**Avoid:** Implicit flow (deprecated), Resource Owner Password (legacy only)
|
||||
|
||||
### Token Lifetimes
|
||||
|
||||
| Token Type | Suggested Lifetime |
|
||||
|------------|-------------------|
|
||||
| Access token | 15-60 minutes |
|
||||
| Refresh token | 7-30 days |
|
||||
| API key | No expiry (rotate quarterly) |
|
||||
| Session | 24 hours - 7 days |
|
||||
|
||||
---
|
||||
|
||||
## 5. Frontend Framework Selection
|
||||
|
||||
### Framework Comparison
|
||||
|
||||
| Factor | React | Vue | Angular | Svelte |
|
||||
|--------|-------|-----|---------|--------|
|
||||
| Learning curve | Medium | Low | High | Low |
|
||||
| Ecosystem | Largest | Large | Complete | Growing |
|
||||
| Performance | Good | Good | Good | Excellent |
|
||||
| Bundle size | Medium | Small | Large | Smallest |
|
||||
| TypeScript | Good | Good | Native | Good |
|
||||
| Job market | Largest | Growing | Enterprise | Niche |
|
||||
|
||||
### Decision Matrix
|
||||
|
||||
| Requirement | Recommendation |
|
||||
|-------------|----------------|
|
||||
| Large team, enterprise | Angular |
|
||||
| Startup, rapid iteration | React or Vue |
|
||||
| Performance critical | Svelte or Solid |
|
||||
| Existing React team | React |
|
||||
| Progressive enhancement | Vue or Svelte |
|
||||
| Component library needed | React (most options) |
|
||||
|
||||
### Meta-Framework Selection
|
||||
|
||||
| Framework | Best For |
|
||||
|-----------|----------|
|
||||
| Next.js (React) | Full-stack React, SSR/SSG |
|
||||
| Nuxt (Vue) | Full-stack Vue, SSR/SSG |
|
||||
| SvelteKit | Full-stack Svelte |
|
||||
| Remix | Data-heavy React apps |
|
||||
| Astro | Content sites, multi-framework |
|
||||
|
||||
### When to Use SSR vs SPA vs SSG
|
||||
|
||||
| Rendering | Use When |
|
||||
|-----------|----------|
|
||||
| SSR | SEO critical, dynamic content, auth-gated |
|
||||
| SPA | Internal tools, highly interactive, no SEO |
|
||||
| SSG | Content sites, blogs, documentation |
|
||||
| ISR | Mix of static and dynamic |
|
||||
|
||||
---
|
||||
|
||||
## 6. Cloud Provider Selection
|
||||
|
||||
### Provider Comparison
|
||||
|
||||
| Factor | AWS | GCP | Azure |
|
||||
|--------|-----|-----|-------|
|
||||
| Market share | Largest | Growing | Enterprise strong |
|
||||
| Service breadth | Most comprehensive | Strong ML/data | Best Microsoft integration |
|
||||
| Pricing | Complex, volume discounts | Simpler, sustained use | EA discounts |
|
||||
| Kubernetes | EKS | GKE (best managed) | AKS |
|
||||
| Serverless | Lambda (mature) | Cloud Functions | Azure Functions |
|
||||
| Database | RDS, DynamoDB | Cloud SQL, Spanner | SQL, Cosmos |
|
||||
|
||||
### Decision Factors
|
||||
|
||||
| If You Need | Consider |
|
||||
|-------------|----------|
|
||||
| Microsoft ecosystem | Azure |
|
||||
| Best Kubernetes experience | GCP |
|
||||
| Widest service selection | AWS |
|
||||
| Machine learning focus | GCP or AWS |
|
||||
| Government compliance | AWS GovCloud or Azure Gov |
|
||||
| Startup credits | All offer programs |
|
||||
|
||||
### Multi-Cloud Considerations
|
||||
|
||||
**Go multi-cloud when:**
|
||||
- Regulatory requirements mandate it
|
||||
- Specific service (e.g., GCP BigQuery) is best-in-class
|
||||
- Negotiating leverage with vendors
|
||||
|
||||
**Stay single-cloud when:**
|
||||
- Team is small
|
||||
- Want to minimize complexity
|
||||
- Deep integration needed
|
||||
|
||||
### Service Mapping
|
||||
|
||||
| Need | AWS | GCP | Azure |
|
||||
|------|-----|-----|-------|
|
||||
| Compute | EC2 | Compute Engine | Virtual Machines |
|
||||
| Containers | ECS, EKS | GKE, Cloud Run | AKS, Container Apps |
|
||||
| Serverless | Lambda | Cloud Functions | Azure Functions |
|
||||
| Object Storage | S3 | Cloud Storage | Blob Storage |
|
||||
| SQL Database | RDS | Cloud SQL | Azure SQL |
|
||||
| NoSQL | DynamoDB | Firestore | Cosmos DB |
|
||||
| CDN | CloudFront | Cloud CDN | Azure CDN |
|
||||
| DNS | Route 53 | Cloud DNS | Azure DNS |
|
||||
|
||||
---
|
||||
|
||||
## 7. API Style Selection
|
||||
|
||||
### REST vs GraphQL vs gRPC
|
||||
|
||||
| Factor | REST | GraphQL | gRPC |
|
||||
|--------|------|---------|------|
|
||||
| Use case | General purpose | Flexible queries | Microservices |
|
||||
| Learning curve | Low | Medium | High |
|
||||
| Over-fetching | Common | Solved | N/A |
|
||||
| Caching | HTTP native | Complex | Custom |
|
||||
| Browser support | Native | Native | Limited |
|
||||
| Tooling | Mature | Growing | Strong |
|
||||
| Performance | Good | Good | Excellent |
|
||||
|
||||
### Decision Matrix
|
||||
|
||||
| Requirement | Recommendation |
|
||||
|-------------|----------------|
|
||||
| Public API | REST |
|
||||
| Mobile apps with varied needs | GraphQL |
|
||||
| Microservices communication | gRPC |
|
||||
| Real-time updates | GraphQL subscriptions or WebSocket |
|
||||
| File uploads | REST |
|
||||
| Internal services only | gRPC |
|
||||
| Third-party developers | REST + OpenAPI |
|
||||
|
||||
### When to Choose Each
|
||||
|
||||
**Choose REST when:**
|
||||
- Building public APIs
|
||||
- Need HTTP caching
|
||||
- Simple CRUD operations
|
||||
- Team experienced with REST
|
||||
|
||||
**Choose GraphQL when:**
|
||||
- Multiple clients with different data needs
|
||||
- Rapid frontend iteration
|
||||
- Complex, nested data relationships
|
||||
- Want to reduce API calls
|
||||
|
||||
**Choose gRPC when:**
|
||||
- Service-to-service communication
|
||||
- Performance critical
|
||||
- Streaming required
|
||||
- Strong typing important
|
||||
|
||||
### API Versioning Strategies
|
||||
|
||||
| Strategy | Pros | Cons |
|
||||
|----------|------|------|
|
||||
| URL path (`/v1/`) | Clear, easy to implement | URL pollution |
|
||||
| Query param (`?version=1`) | Flexible | Easy to miss |
|
||||
| Header (`Accept-Version: 1`) | Clean URLs | Less discoverable |
|
||||
| No versioning (evolve) | Simple | Breaking changes risky |
|
||||
|
||||
**Recommendation:** URL path versioning for public APIs, header versioning for internal.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Decision | Default Choice | Alternative When |
|
||||
|----------|----------------|------------------|
|
||||
| Database | PostgreSQL | Scale/flexibility → MongoDB, DynamoDB |
|
||||
| Cache | Redis | Simple needs → Memcached |
|
||||
| Queue | SQS (AWS) / RabbitMQ | Event streaming → Kafka |
|
||||
| Auth | JWT + Refresh | Traditional web → Sessions |
|
||||
| Frontend | React + Next.js | Simplicity → Vue, Performance → Svelte |
|
||||
| Cloud | AWS | Microsoft shop → Azure, ML-first → GCP |
|
||||
| API | REST | Mobile flexibility → GraphQL, Internal → gRPC |
|
||||
Reference in new issue
Block a user