📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -0,0 +1,346 @@
|
||||
---
|
||||
name: architecture
|
||||
description: This skill should be used when designing systems, evaluating architectures, making technology decisions, or planning for scale. Provides technology selection frameworks, scalability planning, and architectural tradeoff analysis.
|
||||
metadata:
|
||||
version: "2.1.0"
|
||||
---
|
||||
|
||||
# Software Architecture
|
||||
|
||||
Design question → options with tradeoffs → documented decision.
|
||||
|
||||
<when_to_use>
|
||||
|
||||
- Designing new systems or major features
|
||||
- Evaluating architectural approaches
|
||||
- Making technology stack decisions
|
||||
- Planning for scale and performance
|
||||
- Analyzing design tradeoffs
|
||||
|
||||
NOT for: trivial tech choices, premature optimization, undocumented requirements
|
||||
|
||||
</when_to_use>
|
||||
|
||||
<stages>
|
||||
|
||||
Load the **maintain-tasks** skill for stage tracking. Stages advance only, never regress.
|
||||
|
||||
| Stage | Trigger | activeForm |
|
||||
|-------|---------|------------|
|
||||
| Discovery | Session start | "Gathering requirements" |
|
||||
| Codebase Analysis | Requirements clear | "Analyzing codebase" |
|
||||
| Constraint Evaluation | Codebase understood | "Evaluating constraints" |
|
||||
| Solution Design | Constraints mapped | "Designing solutions" |
|
||||
| Documentation | Design selected | "Documenting architecture" |
|
||||
|
||||
Situational (insert before Documentation when triggered):
|
||||
- Review & Refinement → feedback cycles on complex designs
|
||||
|
||||
Edge cases:
|
||||
- Small questions: skip to Solution Design
|
||||
- Greenfield: skip Codebase Analysis
|
||||
- No ADR needed: skip Documentation
|
||||
- Iteration: Review & Refinement may repeat
|
||||
|
||||
Task format:
|
||||
|
||||
```text
|
||||
- Discovery { problem domain }
|
||||
- Analyze { codebase area }
|
||||
- Evaluate { constraint type }
|
||||
- Design { solution approach }
|
||||
- Document { decision type }
|
||||
```
|
||||
|
||||
Workflow:
|
||||
- Start: Create Discovery as `in_progress`
|
||||
- Transition: Mark current `completed`, add next `in_progress`
|
||||
- High start: skip to Solution Design for clear problems
|
||||
- Optional end: Documentation skippable if ADR not needed
|
||||
|
||||
</stages>
|
||||
|
||||
<principles>
|
||||
|
||||
## Proven over Novel
|
||||
|
||||
Favor battle-tested over bleeding-edge without strong justification.
|
||||
|
||||
Checklist:
|
||||
- 3+ years production at scale?
|
||||
- Strong community + active maintenance?
|
||||
- Available experienced practitioners?
|
||||
- Total cost of ownership (learning, tooling, hiring)?
|
||||
|
||||
Red flags: "Early adopters" without time budget, "Written in X" without benchmarks, "Everyone's talking" without case studies.
|
||||
|
||||
## Complexity Budget
|
||||
|
||||
Each abstraction must provide 10x value.
|
||||
|
||||
Questions:
|
||||
- What specific problem does this solve?
|
||||
- Can we solve with existing tools/patterns?
|
||||
- Maintenance burden (docs, onboarding, debugging)?
|
||||
- Impact on incident response?
|
||||
|
||||
## Unix Philosophy
|
||||
|
||||
Small, focused modules with clear contracts, single responsibilities.
|
||||
|
||||
Checklist:
|
||||
- Single, well-defined purpose?
|
||||
- Describe in one sentence without "and"?
|
||||
- Dependencies explicit and minimal?
|
||||
- Testable in isolation?
|
||||
- Clean, stable interface?
|
||||
|
||||
## Observability First
|
||||
|
||||
No system ships without metrics, tracing, alerting.
|
||||
|
||||
Required every service:
|
||||
- Metrics: RED (Rate, Errors, Duration) for all endpoints
|
||||
- Tracing: distributed traces with correlation IDs
|
||||
- Logging: structured logs with context
|
||||
- Alerts: SLO-based with runbooks
|
||||
- Dashboards: at-a-glance health
|
||||
|
||||
## Modern by Default
|
||||
|
||||
Use contemporary proven patterns for greenfield, respect legacy constraints.
|
||||
|
||||
Patterns (2025):
|
||||
- TypeScript strict mode for type safety
|
||||
- Rust for performance-critical services
|
||||
- Container deployment (Docker, K8s)
|
||||
- Infrastructure as Code (Terraform, Pulumi)
|
||||
- Distributed tracing (OpenTelemetry)
|
||||
- Event-driven architectures
|
||||
|
||||
Legacy respect: document why legacy exists, plan incremental migration, don't rewrite what works.
|
||||
|
||||
## Evolutionary
|
||||
|
||||
Design for change with clear upgrade paths.
|
||||
|
||||
Practices:
|
||||
- Version all APIs with deprecation policies
|
||||
- Feature flags for gradual rollouts
|
||||
- Design with migration paths in mind
|
||||
- Deployment independent from release
|
||||
- Automated compatibility testing
|
||||
|
||||
</principles>
|
||||
|
||||
<technology_selection_summary>
|
||||
|
||||
Load [technology-selection.md](references/technology-selection.md) for detailed guidance.
|
||||
|
||||
**Database**: Match data model to use case. PostgreSQL for ACID + complex queries. DynamoDB for flexibility + horizontal scaling. Redis for caching + pub/sub.
|
||||
|
||||
**Framework (TS)**: Hono for modern/serverless, Express for proven ecosystem, Fastify for speed, NestJS for enterprise.
|
||||
|
||||
**Framework (Rust)**: Axum for type-safe modern, Actix-web for raw performance.
|
||||
|
||||
**Frontend**: React + TanStack Router for complex apps, Solid for perf-critical, Next.js for SSR/SSG.
|
||||
|
||||
**Infrastructure**: Serverless for low-traffic/prototypes, K8s/ECS for multi-service at scale, PaaS for MVPs.
|
||||
|
||||
Selection criteria: team expertise, performance needs, ecosystem, type safety, deployment target.
|
||||
|
||||
</technology_selection_summary>
|
||||
|
||||
<design_patterns_summary>
|
||||
|
||||
Load [design-patterns.md](references/design-patterns.md) for detailed guidance.
|
||||
|
||||
**Service Decomposition**
|
||||
|
||||
Monolith first. Extract when hitting specific pain:
|
||||
- Different scaling needs
|
||||
- Different deployment cadences
|
||||
- Team boundaries
|
||||
- Technology constraints
|
||||
|
||||
Microservices: yes for 10+ engineers, clear domains, independent scaling. No for small teams, unclear domains.
|
||||
|
||||
**Communication**
|
||||
|
||||
| Pattern | Use when | Tradeoffs |
|
||||
|---------|----------|-----------|
|
||||
| Sync (REST, gRPC) | Immediate response needed | Tight coupling, cascading failures |
|
||||
| Async (queues, streams) | Eventual consistency OK | Complexity, ordering challenges |
|
||||
| Event-driven | Decoupling, audit trail | Event versioning, consistency |
|
||||
|
||||
**Data Management**
|
||||
|
||||
- Database per service: each service owns its data
|
||||
- CQRS: separate read/write when patterns differ
|
||||
- Event sourcing: when audit trail critical
|
||||
|
||||
</design_patterns_summary>
|
||||
|
||||
<scalability_summary>
|
||||
|
||||
Load [scalability.md](references/scalability.md) for detailed guidance.
|
||||
|
||||
**Key Metrics**: Latency (p50/p95/p99), throughput (RPS), utilization (CPU/mem/net/disk), error rates, saturation (queues, pools).
|
||||
|
||||
**Capacity Planning**: Baseline → load test → find limits → model growth → plan 30-50% headroom.
|
||||
|
||||
**Bottleneck Solutions**:
|
||||
|
||||
| Resource | Solutions |
|
||||
|----------|-----------|
|
||||
| Database | Indexing, read replicas, caching, sharding |
|
||||
| CPU | Horizontal scale, algorithm optimization, async |
|
||||
| Memory | Profiling, streaming, data structure optimization |
|
||||
| Network | Compression, CDN, HTTP/2, gRPC |
|
||||
| I/O | SSD, batching, async I/O, caching |
|
||||
|
||||
**Scaling Strategies**: Vertical (simple, limited), horizontal (stateless required), caching layers (L1/L2/L3), database scaling (replicas, sharding, pooling).
|
||||
|
||||
</scalability_summary>
|
||||
|
||||
<rust_summary>
|
||||
|
||||
Load [rust-architecture.md](references/rust-architecture.md) for detailed guidance.
|
||||
|
||||
**Choose Rust when**: Performance-critical, resource-constrained, memory safety critical, concurrent processing.
|
||||
|
||||
**Skip Rust when**: Prototype/MVP, small team without experience, standard CRUD, missing ecosystem libs.
|
||||
|
||||
**Stack**: tokio (runtime), axum/actix-web (framework), sqlx/diesel (database), serde (serialization), tracing (observability), thiserror/anyhow (errors).
|
||||
|
||||
**vs TypeScript**: Rust is 2-10x faster, 5-10x lower memory, compile-time bug detection, no GC. TS has faster iteration, massive ecosystem, easier hiring.
|
||||
|
||||
</rust_summary>
|
||||
|
||||
<common_patterns_summary>
|
||||
|
||||
Load [common-patterns.md](references/common-patterns.md) for detailed guidance.
|
||||
|
||||
| Pattern | Purpose |
|
||||
|---------|---------|
|
||||
| API Gateway | Single entry, routing, auth, rate limiting |
|
||||
| BFF | Per-client backends with optimized data shapes |
|
||||
| Circuit Breaker | Fail fast when downstream unhealthy |
|
||||
| Saga | Distributed transactions across services |
|
||||
| Strangler Fig | Gradual legacy migration via proxy |
|
||||
|
||||
</common_patterns_summary>
|
||||
|
||||
<implementation_summary>
|
||||
|
||||
Load [implementation-guidance.md](references/implementation-guidance.md) for detailed guidance.
|
||||
|
||||
**Phased Delivery**:
|
||||
- MVP (2-4 wks): Core workflow, simplest architecture, validate problem-solution fit
|
||||
- Beta (4-8 wks): Key features, monitoring, automated deploy, validate product-market fit
|
||||
- Production (8-12 wks): Full features, reliability, auto-scaling, DR
|
||||
- Optimization (ongoing): Performance tuning, cost optimization
|
||||
|
||||
**Critical Path**: Identify blocking dependencies, parallel workstreams, resource constraints, risk areas, decision points.
|
||||
|
||||
**Observability**: Metrics (RED), logging (structured + correlation IDs), tracing (OpenTelemetry), alerting (SLO-based + runbooks).
|
||||
|
||||
</implementation_summary>
|
||||
|
||||
<adr_summary>
|
||||
|
||||
Load [adr-template.md](references/adr-template.md) for the full template.
|
||||
|
||||
ADR structure:
|
||||
- Status, Date, Deciders, Context
|
||||
- Decision
|
||||
- Alternatives Considered (with pros/cons/why not)
|
||||
- Consequences (positive, negative, neutral)
|
||||
- Implementation Notes
|
||||
- Success Metrics
|
||||
- Review Date
|
||||
|
||||
</adr_summary>
|
||||
|
||||
<questions_summary>
|
||||
|
||||
Load [questions-checklist.md](references/questions-checklist.md) for the full checklist.
|
||||
|
||||
**Requirements**: Core workflows, data storage, integrations, critical vs nice-to-have.
|
||||
|
||||
**Non-functional**: Users (now + 1-2 yrs), latency targets, availability (99.9%? 99.99%?), consistency, compliance.
|
||||
|
||||
**Constraints**: Existing systems, current tech, team expertise, deployment env, budget, timeline, acceptable debt.
|
||||
|
||||
**Technology Selection**: Why this over alternatives? Production experience? Operational complexity? Lock-in risk? Hiring?
|
||||
|
||||
**Risk**: Blast radius? Rollback strategy? Detection? Contingency? Assumptions? Cost of being wrong?
|
||||
|
||||
</questions_summary>
|
||||
|
||||
<workflow>
|
||||
|
||||
Use `EnterPlanMode` when presenting options — enables keyboard navigation.
|
||||
|
||||
Structure:
|
||||
- Prose above tool: context, reasoning, recommendation
|
||||
- Inside tool: 2-3 options with tradeoffs + "Something else"
|
||||
- User selects: number, modifications, or combo
|
||||
|
||||
After user choice:
|
||||
- Restate decision
|
||||
- List implications
|
||||
- Surface concerns if any
|
||||
- Ask clarifying questions if gaps remain
|
||||
|
||||
Before documenting:
|
||||
- Verify all options considered
|
||||
- Confirm rationale is clear
|
||||
- Check success metrics defined
|
||||
- Validate migration path if applicable
|
||||
|
||||
At Documentation stage:
|
||||
- Create ADR if architectural decision
|
||||
- Skip if simple tech choice
|
||||
- Mark stage complete after delivery
|
||||
|
||||
</workflow>
|
||||
|
||||
<rules>
|
||||
|
||||
ALWAYS:
|
||||
- Create Discovery todo at session start
|
||||
- Update todos at stage transitions
|
||||
- Ask clarifying questions about requirements and constraints before proposing
|
||||
- Present 2-3 viable options with clear tradeoffs
|
||||
- Document decisions with rationale (ADR when appropriate)
|
||||
- Consider immediate needs and future scale
|
||||
- Evaluate team expertise and operational capacity
|
||||
- Account for budget and timeline constraints
|
||||
|
||||
NEVER:
|
||||
- Recommend bleeding-edge tech without strong justification
|
||||
- Over-engineer solutions for current scale
|
||||
- Skip constraint analysis (budget, timeline, team, existing systems)
|
||||
- Propose architectures the team can't operate
|
||||
- Ignore operational complexity in technology selection
|
||||
- Proceed without understanding non-functional requirements
|
||||
- Skip stage transitions when moving through workflow
|
||||
|
||||
</rules>
|
||||
|
||||
<references>
|
||||
|
||||
**Core**:
|
||||
|
||||
**Deep Dives**:
|
||||
- [technology-selection.md](references/technology-selection.md) — database, framework, infrastructure selection
|
||||
- [design-patterns.md](references/design-patterns.md) — service decomposition, communication, data management
|
||||
- [scalability.md](references/scalability.md) — performance modeling, bottlenecks, scaling strategies
|
||||
- [rust-architecture.md](references/rust-architecture.md) — when to use Rust, stack recommendations
|
||||
- [common-patterns.md](references/common-patterns.md) — API Gateway, BFF, Circuit Breaker, Saga, Strangler
|
||||
- [implementation-guidance.md](references/implementation-guidance.md) — phased delivery, observability
|
||||
- [adr-template.md](references/adr-template.md) — Architecture Decision Record template
|
||||
- [questions-checklist.md](references/questions-checklist.md) — requirements and risk questions
|
||||
|
||||
</references>
|
||||
@@ -0,0 +1,55 @@
|
||||
# Architecture Decision Record Template
|
||||
|
||||
```markdown
|
||||
# ADR-XXX: {TITLE}
|
||||
|
||||
**Status**: [Proposed | Accepted | Deprecated | Superseded]
|
||||
**Date**: YYYY-MM-DD
|
||||
**Deciders**: {WHO}
|
||||
**Context**: {PROBLEM}
|
||||
|
||||
## Decision
|
||||
|
||||
{WHAT_WE_DECIDED}
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Option 1: {NAME}
|
||||
- **Pros**: {BENEFITS}
|
||||
- **Cons**: {DRAWBACKS}
|
||||
- **Why not chosen**: {REASON}
|
||||
|
||||
### Option 2: {NAME}
|
||||
- **Pros**: {BENEFITS}
|
||||
- **Cons**: {DRAWBACKS}
|
||||
- **Why not chosen**: {REASON}
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive**:
|
||||
- {BENEFIT_1}
|
||||
- {BENEFIT_2}
|
||||
|
||||
**Negative**:
|
||||
- {TRADEOFF_1}
|
||||
- {TRADEOFF_2}
|
||||
|
||||
**Neutral**:
|
||||
- {IMPACT_1}
|
||||
- {IMPACT_2}
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- {TECHNICAL_DETAIL_1}
|
||||
- {TECHNICAL_DETAIL_2}
|
||||
- {MIGRATION_PATH}
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- {HOW_MEASURE_SUCCESS}
|
||||
- {WHAT_METRICS_TRACK}
|
||||
|
||||
## Review Date
|
||||
|
||||
{WHEN_REVISIT}
|
||||
```
|
||||
@@ -0,0 +1,44 @@
|
||||
# Common Architecture Patterns
|
||||
|
||||
## API Gateway
|
||||
|
||||
Single entry point for all client requests, handles routing, auth, rate limiting.
|
||||
|
||||
- **Use when**: Multiple backend services, need centralized auth/logging
|
||||
- **Options**: Kong, AWS API Gateway, custom Nginx
|
||||
- **Tradeoffs**: Single point of failure, added latency
|
||||
|
||||
## Backends for Frontends (BFF)
|
||||
|
||||
Separate backend for each frontend type.
|
||||
|
||||
- **Use when**: Different clients need different data shapes
|
||||
- **Benefits**: Optimized per-client, independent deployment
|
||||
- **Tradeoffs**: Code duplication, more services to maintain
|
||||
|
||||
## Circuit Breaker
|
||||
|
||||
Prevent cascading failures by failing fast when downstream unhealthy.
|
||||
|
||||
- **Implementation**: Track failure rate, open circuit after threshold, half-open to test recovery
|
||||
- **Libraries**: Hystrix (Java), Polly (.NET), Resilience4j (Java), opossum (Node)
|
||||
|
||||
## Saga Pattern
|
||||
|
||||
Manage distributed transactions across services.
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| Choreography | Services emit events, others listen and react |
|
||||
| Orchestration | Central coordinator manages workflow |
|
||||
|
||||
- **Use when**: Multi-service transaction, eventual consistency acceptable
|
||||
|
||||
## Strangler Fig
|
||||
|
||||
Gradually migrate from legacy by routing new features to new system.
|
||||
|
||||
1. Route all traffic through proxy/facade
|
||||
2. Build new features in new system
|
||||
3. Gradually migrate existing features
|
||||
4. Sunset legacy when complete
|
||||
@@ -0,0 +1,81 @@
|
||||
# Design Patterns
|
||||
|
||||
## Service Decomposition
|
||||
|
||||
**Monolith first, then extract:**
|
||||
|
||||
1. Start with well-organized monolith
|
||||
2. Identify bounded contexts as you learn domain
|
||||
3. Extract when hitting specific pain:
|
||||
- Different scaling needs (one service needs 10x instances)
|
||||
- Different deployment cadences (ML model updates vs API)
|
||||
- Team boundaries (separate teams, separate services)
|
||||
- Technology constraints (need Rust for one component)
|
||||
|
||||
**When to use microservices:**
|
||||
|
||||
| Signal | Microservices |
|
||||
|--------|---------------|
|
||||
| Large team (10+ engineers) | Yes |
|
||||
| Clear domain boundaries | Yes |
|
||||
| Independent scaling needs | Yes |
|
||||
| Polyglot requirements | Yes |
|
||||
| Small team (<5 engineers) | No |
|
||||
| Unclear domain | No |
|
||||
| Premature optimization | No |
|
||||
|
||||
## Communication Patterns
|
||||
|
||||
### Synchronous (REST, GraphQL, gRPC)
|
||||
|
||||
- **Use when**: Immediate response needed, simple request-response
|
||||
- **Tradeoffs**: Tight coupling, cascading failures, latency compounds
|
||||
- **Mitigation**: Circuit breakers, timeouts, retries with backoff
|
||||
|
||||
### Asynchronous (message queues, event streams)
|
||||
|
||||
- **Use when**: Eventual consistency acceptable, high volume, decoupling needed
|
||||
- **Tradeoffs**: Complexity, harder debugging, ordering challenges
|
||||
- **Patterns**: Message queues (RabbitMQ, SQS), event streams (Kafka, Kinesis)
|
||||
|
||||
### Event-driven architecture
|
||||
|
||||
Core: services publish events, others subscribe
|
||||
|
||||
**Benefits**: Loose coupling, easy to add consumers, audit trail
|
||||
|
||||
**Challenges**: Eventual consistency, event versioning, ordering
|
||||
|
||||
**Best practices**:
|
||||
- Schema registry for event contracts
|
||||
- Include correlation IDs for tracing
|
||||
- Design idempotent consumers
|
||||
- Plan for out-of-order delivery
|
||||
|
||||
## Data Management
|
||||
|
||||
### Database per service
|
||||
|
||||
- Each service owns its data
|
||||
- No direct database access across services
|
||||
- Communication via APIs or events
|
||||
- Tradeoff: data consistency challenges, no joins across services
|
||||
|
||||
### Shared database (anti-pattern for microservices)
|
||||
|
||||
- Multiple services access same database
|
||||
- Only acceptable: transitioning from monolith
|
||||
- Migration path: add service layer, restrict direct access
|
||||
|
||||
### CQRS (Command Query Responsibility Segregation)
|
||||
|
||||
- Separate write model from read model
|
||||
- Use when: read/write patterns very different, complex queries needed
|
||||
- Implementation: write to normalized DB, project to read-optimized views
|
||||
|
||||
### Event Sourcing
|
||||
|
||||
- Store events, not current state
|
||||
- Rebuild state by replaying events
|
||||
- Use when: audit trail critical, temporal queries needed
|
||||
- Challenges: migration complexity, eventual consistency
|
||||
+48
@@ -0,0 +1,48 @@
|
||||
# Implementation Guidance
|
||||
|
||||
## Phased Delivery
|
||||
|
||||
| Stage | Timeline | Focus |
|
||||
|-------|----------|-------|
|
||||
| MVP | 2-4 weeks | Core workflow only, simplest architecture, manual processes OK. Validate problem-solution fit. |
|
||||
| Beta | 4-8 weeks | Key features, basic scalability, monitoring, automated deployment. Validate product-market fit. |
|
||||
| Production | 8-12 weeks | Full features, production-grade reliability, auto-scaling, DR. Scale and optimize. |
|
||||
| Optimization | Ongoing | Performance tuning, cost optimization, feature refinement. Efficiency and experience. |
|
||||
|
||||
## Critical Path Analysis
|
||||
|
||||
For each stage identify:
|
||||
- **Blocking dependencies**: What must be done first?
|
||||
- **Parallel workstreams**: What can happen simultaneously?
|
||||
- **Resource constraints**: Who's needed, when?
|
||||
- **Risk areas**: What might delay us?
|
||||
- **Decision points**: What decisions can't be delayed?
|
||||
|
||||
## Observability Stack
|
||||
|
||||
### Metrics (quantitative health)
|
||||
|
||||
- Business metrics (signups, transactions, revenue)
|
||||
- System metrics (CPU, memory, disk, network)
|
||||
- Application metrics (request rate, latency, errors)
|
||||
|
||||
### Logging (what happened)
|
||||
|
||||
- Structured JSON logs
|
||||
- Correlation IDs across services
|
||||
- Context (user ID, request ID, session)
|
||||
- Appropriate levels: ERROR actionable, WARN concerning, INFO key events
|
||||
|
||||
### Tracing (where time spent)
|
||||
|
||||
- Distributed traces with OpenTelemetry
|
||||
- Critical path instrumentation
|
||||
- Database query timing
|
||||
- External API call timing
|
||||
|
||||
### Alerting (what needs attention)
|
||||
|
||||
- SLO-based alerts (error rate, latency, availability)
|
||||
- Actionable only (if it fires, someone must do something)
|
||||
- Runbooks for each alert
|
||||
- Escalation policies
|
||||
+63
@@ -0,0 +1,63 @@
|
||||
# Questions Checklist
|
||||
|
||||
## Understanding Requirements
|
||||
|
||||
### Functional
|
||||
|
||||
- Core user workflows?
|
||||
- What data stored, how long?
|
||||
- Required integrations?
|
||||
- Critical features vs nice-to-haves?
|
||||
|
||||
### Non-functional
|
||||
|
||||
- How many users (now and in 1-2 years)?
|
||||
- Acceptable latency? (p99 < 500ms? < 100ms?)
|
||||
- Availability target? (99.9%? 99.99%?)
|
||||
- Consistency requirement? (strong? eventual?)
|
||||
- Data retention policy?
|
||||
- Compliance requirements? (GDPR, HIPAA, SOC2?)
|
||||
|
||||
## Constraints
|
||||
|
||||
### Technical
|
||||
|
||||
- Existing systems to integrate with?
|
||||
- Technologies already in use?
|
||||
- Current team expertise?
|
||||
- Deployment environment? (cloud, on-prem, hybrid?)
|
||||
|
||||
### Business
|
||||
|
||||
- Budget for infrastructure?
|
||||
- Timeline for delivery?
|
||||
- Acceptable technical debt?
|
||||
- Long-term vision (1-2 years)?
|
||||
|
||||
### Organizational
|
||||
|
||||
- How many engineers will work on this?
|
||||
- Team structure and communication patterns?
|
||||
- Deployment frequency? (multiple/day, weekly, monthly?)
|
||||
- On-call and support model?
|
||||
|
||||
## Technology Selection
|
||||
|
||||
For each choice ask:
|
||||
- Why this over alternatives? (specific reasons, not "popular")
|
||||
- What production experience exists? (internal or external)
|
||||
- Operational complexity?
|
||||
- Vendor lock-in risk?
|
||||
- Community support and longevity?
|
||||
- Total cost of ownership?
|
||||
- Can we hire for this technology?
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
For each decision:
|
||||
- Blast radius if this fails?
|
||||
- Rollback strategy?
|
||||
- How will we detect problems?
|
||||
- Contingency plan?
|
||||
- What assumptions are we making?
|
||||
- Cost of being wrong?
|
||||
+61
@@ -0,0 +1,61 @@
|
||||
# Rust Architecture
|
||||
|
||||
## When to Choose Rust
|
||||
|
||||
**Strong fit:**
|
||||
- Performance-critical services (compute-heavy, low-latency)
|
||||
- Resource-constrained environments
|
||||
- Systems programming needs
|
||||
- Memory safety critical (no GC pauses)
|
||||
- Concurrent processing with correctness guarantees
|
||||
|
||||
**May not be worth it:**
|
||||
- Prototype/MVP stage (slower iteration)
|
||||
- Small team without Rust experience
|
||||
- Standard CRUD API (TS faster to develop)
|
||||
- Heavy dependency on ecosystem libraries only in other languages
|
||||
|
||||
## Stack Recommendations
|
||||
|
||||
### Web services
|
||||
|
||||
| Component | Recommendation |
|
||||
|-----------|----------------|
|
||||
| Runtime | `tokio` (async runtime, de facto standard) |
|
||||
| Web framework | `axum` (modern, type-safe) or `actix-web` (mature, fast) |
|
||||
| Database | `sqlx` (compile-time checked), `diesel` (full ORM) |
|
||||
| Serialization | `serde` + `serde_json`, `bincode` for binary |
|
||||
| Observability | `tracing` + `tracing-subscriber` |
|
||||
| Errors | `thiserror` (libraries), `anyhow` (applications) |
|
||||
|
||||
### Project structure
|
||||
|
||||
```
|
||||
my-service/
|
||||
├── Cargo.toml # Workspace manifest
|
||||
├── crates/
|
||||
│ ├── api/ # HTTP handlers, routing
|
||||
│ ├── domain/ # Business logic, pure Rust
|
||||
│ ├── persistence/ # Database access
|
||||
│ └── common/ # Shared utilities
|
||||
```
|
||||
|
||||
### Operational considerations
|
||||
|
||||
- Build times longer than TS (use `sccache`, `mold` linker)
|
||||
- Binary size larger (use `cargo-bloat` to analyze)
|
||||
- Memory usage lower at runtime
|
||||
- Deploy as single static binary (easy containerization)
|
||||
- Cross-compilation more complex
|
||||
|
||||
## Tradeoffs vs TypeScript
|
||||
|
||||
| Aspect | Rust | TypeScript |
|
||||
|--------|------|------------|
|
||||
| Memory | 5-10x lower | Higher |
|
||||
| Execution | 2-10x faster | Slower |
|
||||
| Bug detection | Compile-time (null, races) | Runtime possible |
|
||||
| GC pauses | None | Yes |
|
||||
| Development speed | Slower (borrow checker) | Faster iteration |
|
||||
| Ecosystem | Smaller for web | Massive (npm) |
|
||||
| Hiring | Harder | Easy |
|
||||
@@ -0,0 +1,58 @@
|
||||
# Scalability
|
||||
|
||||
## Performance Modeling
|
||||
|
||||
Key metrics:
|
||||
- **Latency**: p50, p95, p99 response times
|
||||
- **Throughput**: requests per second
|
||||
- **Resource utilization**: CPU, memory, network, disk I/O
|
||||
- **Error rates**: 4xx, 5xx responses
|
||||
- **Saturation**: queue depths, connection pools
|
||||
|
||||
Capacity planning:
|
||||
1. **Baseline**: measure current performance under normal load
|
||||
2. **Load test**: use realistic traffic patterns (gradual ramp, spike, sustained)
|
||||
3. **Find limits**: identify bottlenecks (CPU? DB? Network?)
|
||||
4. **Model growth**: project based on business metrics (users, transactions)
|
||||
5. **Plan headroom**: maintain 30-50% capacity buffer
|
||||
|
||||
## Bottleneck Identification
|
||||
|
||||
| Resource | Symptoms | Solutions |
|
||||
|----------|----------|-----------|
|
||||
| Database | High query latency, connection pool exhaustion | Indexing, query optimization, read replicas, caching, sharding |
|
||||
| CPU | High utilization, slow processing | Horizontal scaling, algorithm optimization, caching, async processing |
|
||||
| Memory | OOM errors, high GC pressure | Memory profiling, data structure optimization, streaming processing |
|
||||
| Network | High bandwidth, slow transfers | Compression, CDN, protocol optimization (HTTP/2, gRPC) |
|
||||
| I/O | Disk queue depth, slow reads/writes | SSD, batching, async I/O, caching |
|
||||
|
||||
## Scaling Strategies
|
||||
|
||||
### Vertical scaling (bigger machines)
|
||||
|
||||
- **Pros**: Simple, no code changes
|
||||
- **Cons**: Expensive, hard limits, single point of failure
|
||||
- **Use when**: Quick fix needed, not yet optimized
|
||||
|
||||
### Horizontal scaling (more machines)
|
||||
|
||||
- **Pros**: Cost-effective, no hard limits, fault tolerant
|
||||
- **Cons**: Requires stateless design, load balancing complexity
|
||||
- **Requirements**: Stateless services, shared state in DB/cache
|
||||
|
||||
### Caching layers
|
||||
|
||||
| Layer | Location | Tradeoffs |
|
||||
|-------|----------|-----------|
|
||||
| L1 | Application | Fastest, stale risk |
|
||||
| L2 | Distributed (Redis, Memcached) | Shared across instances |
|
||||
| L3 | CDN (CloudFlare, CloudFront) | Edge caching |
|
||||
|
||||
Strategies: cache-aside, write-through, write-behind based on needs
|
||||
|
||||
### Database scaling
|
||||
|
||||
- **Read replicas**: Route reads to replicas, writes to primary
|
||||
- **Sharding**: Partition data (customer, geography, hash)
|
||||
- **Connection pooling**: PgBouncer, connection reuse
|
||||
- **Query optimization**: Indexes, query tuning, explain plans
|
||||
+98
@@ -0,0 +1,98 @@
|
||||
# Technology Selection
|
||||
|
||||
## Database Selection
|
||||
|
||||
Decision factors:
|
||||
|
||||
1. **Data model fit**
|
||||
- Relational (structured, ACID, complex queries) → PostgreSQL, MySQL
|
||||
- Document (flexible schema, nested data) → MongoDB, DynamoDB
|
||||
- Graph (relationship-heavy) → Neo4j, DGraph
|
||||
- Time-series (metrics, events) → TimescaleDB, InfluxDB
|
||||
- Key-value (simple lookups, cache) → Redis, DynamoDB
|
||||
|
||||
2. **Consistency requirements**
|
||||
- Strong consistency → PostgreSQL, CockroachDB
|
||||
- Eventual consistency acceptable → DynamoDB, Cassandra
|
||||
- Hybrid needs → MongoDB, Cosmos DB
|
||||
|
||||
3. **Scale characteristics**
|
||||
- Read-heavy → read replicas, caching
|
||||
- Write-heavy → sharding, write-optimized DB
|
||||
- Both → consider CQRS pattern
|
||||
|
||||
4. **Operational complexity**
|
||||
- Managed service available? Use it unless special needs
|
||||
- Self-hosted required? Factor operational overhead
|
||||
- Multi-region? Consider distributed databases
|
||||
|
||||
Decision matrix:
|
||||
|
||||
```
|
||||
ACID + complex queries + proven? → PostgreSQL
|
||||
Flexibility + horizontal scaling + managed? → DynamoDB
|
||||
Document model + rich queries + open source? → MongoDB
|
||||
High write throughput + wide column? → Cassandra
|
||||
Caching + pub/sub + simple data? → Redis
|
||||
```
|
||||
|
||||
## Framework Selection
|
||||
|
||||
### Backend (TypeScript/JavaScript)
|
||||
|
||||
| Framework | Best for |
|
||||
|-----------|----------|
|
||||
| Hono | New projects, serverless, edge |
|
||||
| Express | Teams with Express experience |
|
||||
| Fastify | Raw speed matters |
|
||||
| NestJS | Large teams, complex domains |
|
||||
|
||||
### Backend (Rust)
|
||||
|
||||
| Framework | Best for |
|
||||
|-----------|----------|
|
||||
| Axum | New projects, type-safe routing |
|
||||
| Actix-web | Raw performance critical |
|
||||
| Rocket | Rapid development |
|
||||
|
||||
Decision criteria:
|
||||
- Team expertise and learning curve
|
||||
- Performance requirements (most apps don't need Rust speed)
|
||||
- Ecosystem and library availability
|
||||
- Type safety and developer experience
|
||||
- Deployment target (serverless, containers, bare metal)
|
||||
|
||||
### Frontend
|
||||
|
||||
| Stack | Best for |
|
||||
|-------|----------|
|
||||
| React + TanStack Router | Complex state, large ecosystem |
|
||||
| Solid | Performance-critical UIs |
|
||||
| Svelte | Small teams, simple apps |
|
||||
| Next.js | SSR/SSG needs, full-stack React |
|
||||
|
||||
## Infrastructure
|
||||
|
||||
### Serverless (Vercel, Cloudflare Workers, AWS Lambda)
|
||||
|
||||
- **Pros**: Zero ops, auto-scaling, pay-per-use
|
||||
- **Cons**: Cold starts, vendor lock-in, harder debugging
|
||||
- **Best for**: Low-traffic apps, edge functions, prototypes
|
||||
|
||||
### Container orchestration (Kubernetes, ECS)
|
||||
|
||||
- **Pros**: Portability, fine control, proven at scale
|
||||
- **Cons**: Operational complexity, learning curve
|
||||
- **Best for**: Medium-large apps, multi-service systems
|
||||
|
||||
### Platform-as-a-Service (Heroku, Render, Railway)
|
||||
|
||||
- **Pros**: Simple deploys, managed infrastructure
|
||||
- **Cons**: Higher cost, less control, scaling limits
|
||||
- **Best for**: Startups, MVPs, small teams
|
||||
|
||||
### Bare metal / VMs
|
||||
|
||||
- **Pros**: Full control, cost-effective at scale
|
||||
- **Cons**: High operational burden
|
||||
- **Best for**: Special requirements, very large scale
|
||||
Reference in New Issue
Block a user