references/agentcore.md
# AgentCore — Startup Decision Guide
## When to Use AgentCore (vs. Simpler Alternatives)
Most early-stage startups **should NOT start with AgentCore**. It's production infrastructure for agents you haven't built yet.
### Decision Framework
| Signal | Recommendation |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Building your first AI feature | Skip AgentCore. Use Bedrock `InvokeModel` directly or Strands locally. |
| Single agent, < 100 users | Deploy on Lambda or ECS. AgentCore adds operational complexity you don't need yet. |
| Multiple agents needing shared memory/policy | AgentCore justified — this is what it's built for. |
| Need OAuth integration to 3rd-party APIs + access control | AgentCore Identity + Policy saves significant custom code. |
| Multi-tenant SaaS with per-customer agent guardrails | AgentCore Policy (Cedar) is the right tool — building this custom is painful. |
### When to Graduate to AgentCore
- You have 3+ agents that need to share session context
- You need Cedar-based policy enforcement (financial limits, role-based tool access)
- You need managed OAuth token refresh for third-party integrations
- You're spending engineering time building agent infrastructure instead of product features
## Cost Traps
- **AgentCore Runtime minimum: 1 vCPU / 2 GiB always-on.** Unlike Lambda, this doesn't scale to zero. At seed stage with 10 users, you're paying for idle capacity 23 hours/day.
- **Memory (LTM) provisioning: ~120-180s.** Not a cost trap, but a DX friction that slows iteration. STM is faster (~30-90s).
- **Session TTL defaults to 900s.** Idle sessions consume compute. For async/background agents, set short TTLs aggressively.
## Startup-Specific Architecture Advice
### Start Simple, Add Components Incrementally
```
Week 1-4: Strands agent + Bedrock (no AgentCore)
Month 2-3: Add AgentCore Runtime when you need persistent sessions
Month 3-6: Add Policy when you have paying customers needing guardrails
Month 6+: Add Memory, Gateway, Identity as specific needs emerge
```
**Counter to standard AWS guidance**: AWS docs suggest setting up the full stack (Runtime + Memory + Gateway + Policy + Observability). For startups, each component is operational overhead. Add them one at a time, driven by specific customer pain.
### Multi-Agent: Don't Go There Early
| Team size | Agent architecture | Why |
| ------------- | ------------------------------------------- | -------------------------------------------------------------------- |
| 1-3 engineers | Single agent, direct Bedrock calls | You can't debug multi-agent orchestration AND build product features |
| 4-8 engineers | One supervisor + 2-3 specialist agents max | Complexity grows exponentially with agent count |
| 8+ engineers | Multi-agent with A2A or Bedrock Multi-Agent | You have the team to own the operational complexity |
### PoC to Production Pitfall
The AgentCore CLI (`agentcore init` → `agentcore deploy`) is fast for prototyping but creates resources that are NOT in IaC. Startups frequently build on CLI-deployed agents for months, then face a painful migration when they need CI/CD.
**Rule**: If you expect to use AgentCore for more than 2 weeks, start with CDK from day one. The AgentCore Starter Toolkit provides CDK templates — use them.
## Credits Guidance
- AgentCore Runtime compute is covered by AWS Activate credits (it's ECS/Fargate under the hood)
- Model invocations through agents still bill as Bedrock token usage (also credit-eligible)
- **Don't over-provision "because credits cover it"** — you're building muscle memory for architectures you can't afford post-credits
## What AgentCore Solves That's Hard to Build Custom
Only adopt AgentCore for these specific capabilities when you actually need them:
1. **Cedar policy enforcement on tool calls** — building authorization logic per-tool is error-prone
2. **Managed OAuth token lifecycle** — refresh tokens, secret rotation, multi-provider
3. **Cross-session memory with automatic summarization** — LTM extraction is non-trivial to build
4. **Built-in observability (OTel → X-Ray/CloudWatch)** — saves 1-2 weeks of instrumentation work
references/api-gateway.md
# API Gateway — Startup Decision Guide
## Stage-Based Recommendation
### Pre-Product-Market-Fit (Seed / <$1M ARR)
- **Use HTTP API exclusively**. It's 70% cheaper than REST API and faster to configure.
- Don't set up custom domains until you have paying customers. The default `execute-api` URL is ugly but free.
- Skip WAF until you have traffic worth protecting (~1000 RPM sustained). WAF minimum is ~$5/month + $1/million requests.
### Post-PMF / Growth ($1M-$10M ARR)
- Add custom domain when you have external API consumers or need stable URLs for partners.
- Add WAF when you see bot traffic or abuse patterns in logs.
- Consider REST API **only** if you now need request validation, API keys for usage plans (monetizing your API), or caching.
## Cost Traps
| Trap | Impact | Fix |
| ------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| REST API "just in case" | 3.5x cost vs HTTP API ($3.50 vs $1.00 per million) | Start HTTP API, migrate only specific routes that need REST features |
| Uncached Lambda authorizer | Authorizer invoked on EVERY request — doubles your Lambda bill | Set 300s TTL cache; a user making 20 requests/min triggers 1 authorizer call instead of 20 |
| 4xx from bad clients | You still pay for invalid requests | Add rate limiting early; monitor 4xx rate |
| REST API caching left on unused | $14.40/month minimum (0.5GB cache) even with zero hits | Only enable caching on routes with >100 RPM and cacheable responses |
## Counterintuitive Advice
- **Don't add API Gateway at all if you're using a single Lambda behind CloudFront.** Lambda function URLs are free and CloudFront handles caching/custom domains. API Gateway adds cost with no value for simple cases.
- **Skip request validation in API Gateway.** Validate in your Lambda instead — it's easier to test, debug, and change. API Gateway validation errors produce cryptic messages for your API consumers.
- **The 29-second timeout is actually your friend.** If you're hitting it, your architecture is wrong. Use it as a forcing function to move to async patterns (SQS + webhook) which scale better anyway.
## When to Graduate from HTTP API to REST API
Trigger ANY of these:
- You need to monetize your API with usage plans and API keys for billing
- You need WAF integration (bot protection, geo-blocking, rate limiting by IP)
- You need request body validation at the gateway level (compliance requirement)
- You have >50 routes and need VTL transforms to avoid Lambda invocations on simple mappings
If none apply at $10M ARR, you probably never need REST API.
references/aws-architect.md
# AWS Architect — Startup-Specific Guidance
## Startup-Stage Service Selection
### Compute — Default by Stage
| Stage | Default Compute | Why |
| ------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pre-seed / MVP | Lambda + API Gateway | $0 at zero traffic. Ship in hours, not days. |
| Seed / Early traction | Lambda OR ECS Fargate | Fargate if you need WebSockets or >15min processing. ALB setup cost is worth avoiding a forced re-platform later. Lambda function URLs + response streaming cover some gaps. |
| Series A / Steady traffic | ECS Fargate | Predictable costs at steady-state; Savings Plans eligible |
| Series B+ / Team has K8s | EKS only if team already knows it | Never adopt K8s as a startup unless you're hiring K8s engineers |
**Counterintuitive**: ECS Fargate at seed stage feels heavy, but the ALB + target group + task definition setup is a one-time cost (~1 day). You avoid a forced re-platform when you outgrow Lambda's 15-minute timeout or need persistent connections. For simpler cases, Lambda function URLs with response streaming can bridge the gap without a full container deploy.
### Database — The Startup Trap
| Stage | Default Database | Why NOT the "proper" choice |
| ----------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| MVP validation | RDS PostgreSQL t4g.micro | $12/mo. SQL gives you joins, ad-hoc queries, and flexibility to iterate on your data model without re-engineering |
| MVP with auto-scaling needs | Aurora Serverless v2 | Scales to zero ACU... but minimum is 0.5 ACU ($43/mo). Worth it only if traffic is spiky and unpredictable |
| Confirmed key-value access patterns | DynamoDB on-demand | $0 at zero traffic. Only choose this if you've confirmed you don't need relational queries |
| Need PostgreSQL but cost-sensitive | RDS PostgreSQL t4g.micro/small | $12-25/mo. Single-AZ is FINE until you have paying customers with uptime commitments |
**DynamoDB single-table design**: Every blog post says do it. DON'T at a startup. It's a premature optimization that makes your data model rigid before you know your access patterns. Use multiple simple tables. Refactor to single-table design when you have proven query patterns AND DynamoDB costs justify the optimization.
## Startup-Specific Gotchas
| Gotcha | Impact | What to Do Instead |
| ------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NAT Gateway as default | $32/mo + $0.045/GB — often your #2 line item | VPC endpoints for S3/DynamoDB. Public subnets + SGs for Lambda. Only add NAT if you actually need private subnet egress |
| Aurora Serverless v2 "scales to zero" | Minimum 0.5 ACU = $43/mo even idle | RDS t4g.micro at $12/mo is cheaper until you need auto-scaling |
| Multi-AZ everything | 2x cost on RDS, ElastiCache | Single-AZ until you have paying customers with uptime commitments (SLA or contractual). If credits cover it and you're past MVP, enabling early is fine as insurance — but don't let it become a hard dependency before you need it |
| CloudFront for API | $0 minimum but adds debugging complexity | Skip until you need geographic distribution or WAF |
| Secrets Manager per secret | $0.40/secret/mo adds up | SSM Parameter Store SecureString is free. Use Secrets Manager only for rotation |
| Cross-AZ data transfer | $0.01/GB between AZs | Chatty microservices in different AZs = hidden cost. Colocate or go single-AZ |
## Credits-Aware Architecture Decisions
| Decision | With Credits | Without Credits |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| RDS instance size | Right-size to actual need (credits don't change this) | Same — don't over-provision just because credits cover it |
| Multi-AZ | Enable if credits cover it AND you're past MVP — fine as early insurance | Defer until paying customers with uptime commitments |
| Reserved Instances / Savings Plans | Do NOT buy while on credits — wait until credits expire to see real spend patterns | Buy after 3 months of stable, post-credits usage |
| Managed services vs DIY | Always prefer managed services. EKS is the exception — only adopt it if your team already has Kubernetes expertise, and understand you're taking on significant operational overhead | Same |
| Graviton instances | Prefer Graviton unless you have native x86 dependencies. 20% cheaper AND credits last longer. Test your container on ARM before committing | Same |
**Critical**: Never commit to Savings Plans or Reserved Instances while on credits. You can't see your real usage patterns. Wait until 3 months AFTER credits are exhausted.
## The "10x Cost" Test
Before finalizing any architecture, ask: "If traffic 10x's, what happens to my bill?"
| Service | 10x Behavior | Startup Risk |
| ------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Lambda | 10x invocations = ~10x cost | Low risk — linear and predictable |
| DynamoDB on-demand | 10x reads/writes = ~10x cost | Medium risk — costs scale linearly with reads/writes. Design access patterns early to avoid surprise bills at traction |
| RDS | Doesn't auto-scale (unless Aurora Serverless) | Low cost risk, HIGH availability risk |
| NAT Gateway | 10x data = 10x data processing charges | High risk — this is where surprise bills come from |
| S3 | 10x storage = linear. 10x requests = linear | Low risk |
| CloudFront | 10x requests = ~8x cost (volume discounts) | Low risk |
| ECS Fargate | 10x tasks = 10x cost. No volume discounts | Medium risk — but you control the scaling |
## When Architecture Recommendations DIFFER from AWS Best Practices
| AWS Best Practice | Startup Reality | Do This Instead |
| ----------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Multi-AZ for all stateful services | Costs 2x, you have 50 users | Single-AZ until paying customers with uptime commitments |
| Separate microservices from day 1 | You have 2 engineers and 1 service | Monolith or modular monolith. Split at pain points. If on Lambda, a well-organized single-repo with shared layers achieves the same cohesion as a container monolith |
| Use CloudTrail + GuardDuty + Security Hub | $20-50+/mo for security tooling | CloudTrail only until Series A. Add GuardDuty at first enterprise deal |
| VPC with private subnets + NAT | NAT costs $32+/mo minimum | Public subnets + security groups until you have compliance requirements |
| Custom KMS keys for encryption | $1/key/mo + API costs | AWS-managed keys (free) until compliance requires CMK |
| Detailed CloudWatch dashboards | You're iterating weekly, dashboards are stale | 3 alarms (error rate, p99 latency, cost threshold). Add dashboards when you have an SRE |
references/aws-plan.md
# AWS Planning — Startup-Specific Guidance
## Stage-Gated Planning
### Pre-Seed / MVP (< $1K/mo AWS spend)
- Skip Phase 3 (Security Review) depth — basic guardrails only. Don't let security theater block shipping.
- Phase 4 (Cost Estimate) matters more than Phase 2 (Design) at this stage. A $500/mo surprise kills a pre-seed startup.
- Deliver the simplest architecture that validates the hypothesis. If it's a single Lambda + DynamoDB, that IS the plan.
### Seed / Product-Market Fit ($1K–$10K/mo)
- Full workflow applies but bias toward speed over perfection
- Security Review: focus only on data exposure risk (public S3, no auth) — skip compliance depth until Series A
- Cost Estimate: model the "what if we 10x" scenario — will your architecture bankrupt you at success?
### Series A+ ($10K+/mo)
- Full workflow with no shortcuts
- Add: cost allocation tags from day 1 (you'll need them for board reporting)
- Add: multi-account strategy planning (separate prod/dev NOW, not later)
## Anti-Patterns — Startup Edition
- **Over-engineering for hypothetical scale**: You have 50 users. Lambda + DynamoDB. Not EKS. Not multi-region. Not event sourcing. The startup that builds for 10M users at 50 users usually dies at 50 users.
- **Skipping cost modeling because "we have credits"**: Credits expire. Model what happens when they run out. If your architecture costs $15K/mo and credits cover $5K, you have 3 months of runway buffer, not infinite time.
- **Proposing services the team cannot operate**: A 3-person startup cannot operate Kubernetes, Kafka, and a data lake simultaneously. Each managed service you skip saves 20% of one engineer's time.
- **Building the "enterprise-ready" version first**: SOC2, multi-tenant isolation, audit logging — all matter, but not before you have 10 paying customers. Build the path TO compliance, don't implement it day 1.
## Startup-Specific Cost Traps in Planning
| Trap | Why It Hits Startups Hard |
| -------------------------------------- | -------------------------------------------------------------------------------------------- |
| NAT Gateway ($32/mo + data) | Often unnecessary pre-PMF. Use VPC endpoints or public subnets with security groups |
| Multi-AZ RDS ($200+/mo minimum) | Single-AZ is fine until you have SLA commitments to paying customers |
| Secrets Manager ($0.40/secret/mo) | Use SSM Parameter Store SecureString (free) until you need rotation |
| CloudWatch Logs (never-expire default) | Set 30-day retention. You won't look at 6-month-old dev logs |
| ECS + ALB baseline | $50/mo minimum even at zero traffic. Consider Lambda until steady-state traffic justifies it |
## "When to Graduate" Triggers
| Current Choice | Graduate When | Graduate To |
| ------------------------ | ------------------------------------------------------ | -------------------------------------------------------- |
| Single Lambda + DynamoDB | p99 latency matters AND traffic is steady (not spiky) | ECS Fargate + Aurora |
| Single-AZ RDS | First paying customer with uptime SLA | Multi-AZ RDS |
| No IaC (console clicks) | Second engineer joins OR you need a second environment | CDK or Terraform |
| Single AWS account | First production customer | Prod + Dev accounts minimum |
| No monitoring | First production customer | CloudWatch dashboards + 3 alarms (errors, latency, cost) |
references/bedrock.md
# Bedrock — Startup Decision Guide
## Model Selection: Cost-First Thinking
**The #1 startup cost trap**: Defaulting to Claude Sonnet/Opus "to be safe" during prototyping, then getting locked into those costs at scale.
### Stage-Specific Strategy
| Stage | Strategy | Why |
| ------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| Pre-seed/Seed | Nova Micro/Lite for everything, Sonnet only for demos | Credits burn fast on token-heavy workloads; prove the product logic works with cheap models first |
| Series A | Route 80% to Nova Micro/Lite, 20% to Sonnet | Intelligent routing saves 60-70% vs blanket Sonnet usage |
| Series B+ | Optimize per-endpoint with measured quality thresholds | You have traffic data now — let it drive model selection |
### Counterintuitive Advice
- **Don't start with the best model and optimize later.** Start with Nova Micro. If it fails, you've learned exactly what capability gap you need — and you'll prompt-engineer around it first. Most startups discover 70%+ of their calls work fine on the cheapest model.
- **Nova Pro is underrated.** For most startup use cases (summarization, extraction, Q&A), Nova Pro matches Claude Sonnet quality at ~3-5x lower cost per token. Evaluate it before assuming you need Anthropic models.
- **Batch API saves 50% — use it aggressively.** Any workload that doesn't need real-time response (nightly processing, background enrichment, evaluation runs) should use batch. Most startups leave this on the table.
## Architecture: What NOT to Build Early
### The Agent Tax
Every agent step multiplies cost: tool selection reasoning + tool execution + result synthesis = 3-5x the token cost of a single invoke.
**Startup rule of thumb:**
- < $500/month LLM spend → Never use agents. Use `InvokeModel` with structured prompts.
- $500-5K/month → One simple agent max. Router + specialist only if you have genuinely distinct domains.
- $5K+/month → Agent architecture justified if you have evidence single-call can't do the job.
### Credits-Specific Guidance
- Bedrock on-demand pricing is token-based — AWS Activate credits cover it fully (no commitment needed)
- **Don't buy Provisioned Throughput with credits.** Credits expire; provisioned commitments don't. You'll be stuck paying on-demand rates after credits burn down with capacity you may not need.
- Prompt caching is automatic for supported models — structure your prompts with stable system prompts first to maximize cache hits (free repeated tokens)
## Knowledge Bases: PoC Cost Trap
**OpenSearch Serverless minimum cost: ~$700/month** (2 OCU indexing + 2 OCU search minimum).
### Startup Alternatives
| Monthly queries | Vector store choice | Monthly cost |
| --------------- | --------------------------------------------------------- | ------------------------ |
| < 1,000 | Skip KB entirely — stuff context into prompt | $0 (just token cost) |
| 1K-50K | Aurora Serverless v2 with pgvector | $50-150 (scales to zero) |
| 50K-500K | Single OpenSearch Serverless collection shared across KBs | $700 minimum |
| 500K+ | Dedicated OpenSearch Serverless per KB | $700+ per collection |
**When to graduate from prompt-stuffing to RAG:**
- Source documents exceed 50K tokens total
- Documents change frequently (weekly+)
- You need citation/attribution in answers
- Multiple distinct document collections need separate retrieval
## Anti-Patterns (Startup-Specific)
- **Building "AI features" before product-market fit.** LLM costs scale with users. If you haven't validated demand, you're burning credits on a product nobody wants. Validate with a Wizard-of-Oz or rules-based MVP first.
- **OpenSearch Serverless for a PoC.** $700/month minimum for something 50 users will touch. Use pgvector on Aurora Serverless or just stuff documents into prompts until scale demands RAG.
- **Custom fine-tuning before exhausting prompt engineering.** Fine-tuning on Bedrock costs real money (training tokens + hosting custom model). 95% of startup use cases are solved with better prompts + few-shot examples. Fine-tune only when you have 10K+ labeled examples and measurable quality gap.
- **Not tracking per-feature token costs.** When you have 5 AI features, one will be 80% of your bill. Without per-feature cost attribution, you can't make informed product decisions about which features to keep/kill/optimize.
references/challenger.md
# Challenger — Startup-Specific Guidance
## Startup Challenge Framework
When challenging an architecture recommendation for a startup, apply these lenses in order:
### 1. The "Can You Operate This?" Test
For a team of N engineers, how many services require operational expertise?
| Team Size | Max Operational Complexity |
| ------------- | -------------------------------------------------------------------- |
| 1 engineer | Fully managed services only (Lambda, DynamoDB, S3, ECS Express Mode) |
| 2-3 engineers | Managed services + 1 "complex" service (RDS, ECS Fargate) |
| 4-7 engineers | Add ECS, custom networking, CI/CD pipelines |
| 8+ engineers | Can consider EKS, multi-region, custom infrastructure |
**If the proposed architecture exceeds the team's operational budget, it's wrong regardless of how "correct" it is technically.**
### 2. The "What If You Succeed?" Test
Challenge every architecture with: "If traffic 10x's next month, what breaks and what does it cost?"
Red flags:
- Architecture that requires manual intervention to scale (fixed EC2 instances without ASG)
- Architecture where cost is non-linear with traffic (NAT Gateway data charges, cross-AZ chatter)
- Architecture that requires re-architecture to scale (monolith on a single RDS instance with no read path)
### 3. The "What If Credits Expire Tomorrow?" Test
- Is the monthly cost sustainable on revenue alone?
- Are there Savings Plans or RIs purchased during credits that'll now cost real money?
- Is there over-provisioning that was "free" during credits but now costs $$$?
### 4. The "Simpler Alternative" Test
For every complex component proposed, name the simpler alternative and what you give up:
| Proposed | Simpler Alternative | What You Lose | When It Matters |
| -------------------------- | ------------------------- | -------------------------------------------- | ------------------------------------ |
| EKS | ECS Fargate | K8s ecosystem, Helm charts | Team already uses K8s |
| Aurora Serverless v2 | RDS t4g.micro | Auto-scaling, storage auto-growth | >$50/mo in DB costs |
| Step Functions | Lambda calling Lambda | Visual debugging, built-in retries | Workflows >3 steps |
| EventBridge + SNS + SQS | Direct Lambda invocations | Decoupling, replay, fan-out | >2 consumers or need replay |
| Multi-region active-active | Single region + backups | <5 min recovery in regional failure | 99.99%+ SLA required |
| Microservices | Modular monolith | Independent deployment, language flexibility | Team >5 AND clear service boundaries |
### 5. The "Premature Optimization" Detector
Challenge if you see ANY of these in a pre-PMF architecture:
- Multi-region anything
- Kubernetes
- Data lake / data warehouse
- Event sourcing
- CQRS
- Service mesh
- Custom observability platform (use CloudWatch)
- Multi-account beyond prod/dev split
- More than 3 microservices
Each of these is valid at scale. None of them are valid before product-market fit.
## Startup Challenger Verdict Scale
| Verdict | Meaning |
| ------------- | --------------------------------------------------------------------------------- |
| **SHIP IT** | Architecture matches stage, team, and budget. Go. |
| **SIMPLIFY** | Right direction, but over-engineered for current stage. Remove components. |
| **RETHINK** | Fundamental mismatch between architecture complexity and team/stage/budget |
| **DANGEROUS** | Architecture has a cost cliff, operational burden, or security gap that will hurt |
references/cloudfront.md
# CloudFront — Startup Decision Guide
## Stage-Based Recommendation
### Pre-PMF (Seed / <$1M ARR)
- **Deploy CloudFront from day one for static assets.** It's effectively free at low traffic (1TB free tier) and gives you global performance without multi-region infrastructure.
- Skip WAF until you see abuse. WAF adds $5/month minimum + per-request costs.
- Use versioned filenames (`app.abc123.js`) from the start — never rely on invalidations.
### Post-PMF / Growth ($1M-$10M ARR)
- Add WAF when you have traffic worth protecting or compliance requirements.
- Add CloudFront in front of API Gateway only if you need geographic caching of API responses or need to combine static + API under one domain.
- Consider CloudFront Functions (not Lambda@Edge) for header manipulation — 1/6th the cost.
## Cost Traps
| Trap | Impact | Fix |
| ------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Invalidation as deploy strategy | Free only for first 1,000 paths/month, then $0.005/path. Daily deploys with `/*` = waste. | Use content-hashed filenames. Zero invalidation cost. |
| Lambda@Edge for simple tasks | Charged per request + duration at 3x Lambda pricing | Use CloudFront Functions for header manipulation, redirects, URL rewrites ($0.10/million vs $0.60/million) |
| Data transfer out to internet | $0.085/GB after 1TB free tier — this is often the biggest line item for media-heavy startups | Enable compression (saves 60-80% on text), use appropriate image formats, consider S3 Transfer Acceleration only if upload-heavy |
| Origin Shield without need | Additional caching layer at $0.0090/10K requests | Only valuable if you have 3+ edge locations hitting origin frequently |
## Counterintuitive Advice
- **CloudFront in front of Lambda Function URLs is often better than API Gateway.** You get custom domains, caching, and WAF at CloudFront cost ($0.085/GB + $0.01/10K requests) instead of API Gateway cost ($1.00/million requests). For a startup doing 10M requests/month on small payloads: CloudFront = ~$10, HTTP API = $10, REST API = $35. But CloudFront gives you the caching layer for free.
- **Don't use edge-optimized API Gateway endpoints.** They silently create a CloudFront distribution you can't configure. Use regional + your own CloudFront if you need CDN.
- **The free tier (1TB/month transfer, 10M requests) is generous.** Most pre-PMF startups never exceed it. Don't optimize what costs you $0.
## When to Add CloudFront (if not already using it)
You're paying too much for origin compute/bandwidth when:
- Your origin (ALB, API Gateway, S3) data transfer exceeds $50/month
- You're serving the same API response to many users within a time window (cacheable)
- You need to serve users on multiple continents without multi-region deployment
## Configuration Decisions (Get These Right on Day 1)
### Origins
- Use **Origin Access Control (OAC)** — not the legacy Origin Access Identity (OAI). OAC supports SSE-KMS and all S3 features; OAI does not.
- For S3 static website hosting endpoints, use custom origin (not S3 origin type) — the website endpoint is HTTP-only.
- For API origins, use **CachingDisabled** managed policy unless you explicitly control TTLs and cache keys.
- Use **regional** API Gateway endpoints, not edge-optimized (avoids double CloudFront hop).
### Caching
- Forward only what the origin needs — extra headers/cookies/query strings destroy cache hit ratio. Use separate cache and origin request policies.
- Enable automatic compression (Gzip + Brotli) in cache behavior — saves 60-80% on text assets.
### Security
- ACM certificate must be in **us-east-1** for CloudFront. They're free and auto-renew.
- Add security response headers via response headers policy: HSTS, X-Content-Type-Options, X-Frame-Options.
- Never use self-signed certs with custom domains.
## Credits Consideration
CloudFront data transfer is covered by AWS Activate credits. If you have $100K in credits, don't optimize CloudFront costs — optimize for developer velocity instead. Revisit when credits are within 6 months of expiring.
references/cost-check.md
# Cost Check — Startup-Specific Guidance
## The Startup Cost Model (Different from Enterprise)
Enterprise optimizes for: lowest per-unit cost at scale.
Startups optimize for: lowest BASELINE cost with LINEAR scaling (no cliffs).
### The Three Cost Questions for Startups
1. **What's my cost at zero/minimal traffic?** (This is your monthly burn before you have customers)
2. **What's my cost at 10x current traffic?** (Is it linear or does it cliff?)
3. **What's my cost when credits expire?** (The real number)
## Hidden Cost Killers — Startup-Specific
These rarely appear in enterprise cost reviews but destroy startup budgets:
| Service | Hidden Cost | Why Startups Get Hit |
| --------------------------------- | ------------------------------------- | ------------------------------------------------------------------------- |
| NAT Gateway | $32/mo + $0.045/GB processed | Added by default in "best practice" VPC templates |
| ALB | $16/mo + LCU charges | Required for ECS/EKS even at 1 request/minute |
| Elastic IP (unattached) | $3.60/mo (post Feb 2024) | Forgotten after shutting down EC2 dev instances |
| CloudWatch Logs | $0.50/GB ingestion + storage | Default log retention = never expire. Grows forever |
| Secrets Manager | $0.40/secret/mo + $0.05/10K API calls | Often 10+ secrets for a simple app. SSM is free |
| S3 Intelligent-Tiering monitoring | $0.0025/1K objects/mo | Not worth it for <1M objects — just use S3 Standard |
| VPC endpoints | $7.20/endpoint/mo per AZ | "Best practice" adds 3-5 endpoints = $20-36/mo for nothing at low traffic |
| KMS customer-managed keys | $1/key/mo + API charges | AWS-managed keys are free and sufficient pre-compliance |
| Config rules | $0.003/evaluation | 20 rules × 50 resources × daily = $90/mo for dev accounts |
## Credits Strategy
### How to Model Costs with Credits
```
Real monthly cost = AWS bill - credits applied
Runway (months) = Remaining credits / Real monthly cost
Post-credits monthly cost = AWS bill (this is what you need revenue to cover)
```
### Credits Optimization Rules
1. **Never buy Reserved Instances or Savings Plans while on credits** — you can't see real usage patterns
2. **Credits cover everything except Marketplace** — use native AWS services, not Marketplace alternatives
3. **Track credits burn rate monthly** — if burning faster than expected, investigate NOW not at expiry
4. **Plan architecture for post-credits reality** — if your arch costs $15K/mo and revenue is $5K/mo, you have a problem BEFORE credits expire
5. **Credits don't carry over after expiry date** — use-it-or-lose-it. Don't under-utilize to "save" them
## Cost Scaling Patterns — Choose Wisely
| Pattern | Cost at 0 traffic | Cost at 1K req/day | Cost at 100K req/day | Startup Fit |
| ------------------------------------- | ---------------------------- | ------------------ | -------------------- | ------------------------------------ |
| Lambda + DynamoDB (on-demand) | ~$0 | ~$1 | ~$30 | ✅ Best for pre-seed |
| ECS Express Mode (1 task) | ~$7 | ~$7 | ~$30 | ✅ Good for seed |
| ECS Fargate (1 task) + ALB | ~$50 | ~$50 | ~$100 | ⚠️ Only if traffic justifies baseline |
| ECS Fargate (2 tasks, multi-AZ) + ALB | ~$85 | ~$85 | ~$150 | ❌ Skip until SLA requirements |
| EKS + Fargate | ~$80 (control plane) + tasks | ~$130 | ~$250 | ❌ Skip until team has K8s skills |
## The "$100/mo Baseline" Rule
If your architecture costs >$100/mo at zero customers, justify every dollar:
- $16/mo ALB: Do you need it, or can Lambda + API Gateway work?
- $32/mo NAT Gateway: Do you actually need private subnet egress?
- $43/mo Aurora Serverless v2 minimum: Is RDS t4g.micro ($12/mo) sufficient?
- $7/mo per VPC endpoint: Can you use public endpoints with IAM auth instead?
## When to Invest in Cost Optimization
| Monthly Spend | Optimization ROI | Action |
| ------------- | ---------------------------- | --------------------------------------------------------------------------- |
| < $500 | Not worth engineering time | Set a budget alarm. Move on. Ship features. |
| $500–$2K | Quick wins only (30 min max) | Delete unused resources, set log retention, right-size one big instance |
| $2K–$10K | Dedicated half-day | Review top 5 line items, consider Savings Plans for stable workloads |
| > $10K | Dedicated effort | Full cost review, Savings Plans, architecture changes, cost allocation tags |
## Quick Wins Checklist
- [ ] Unused EBS volumes and unattached Elastic IPs
- [ ] CloudWatch log retention set to "Never expire" — change to 7d dev / 30d prod
- [ ] NAT Gateway traffic that could use VPC endpoints
- [ ] Over-provisioned RDS instances (check CPU utilization)
- [ ] Lambda functions with excessive memory allocation
- [ ] Dev environments running 24/7 — schedule stop outside business hours
- [ ] Old EBS snapshots and unused AMIs
- [ ] S3 buckets without lifecycle policies
## Gotchas
- Data transfer costs are the silent killer — especially cross-AZ and cross-region
- DynamoDB on-demand vs provisioned: on-demand is cheaper below ~20% utilization of provisioned capacity
- S3 Intelligent-Tiering monitoring fee per object — not worth it for millions of tiny objects
- CloudFront can be cheaper than S3 direct for high-traffic reads (no S3 request fees)
- Graviton instances are ~20% cheaper and often faster — use them unless you need x86
references/credits-strategy.md
# Credits Strategy
## Key Facts for Architecture Decisions
- Credits apply AFTER free tier (free tier is consumed first)
- Credits do NOT cover: Route53 domain registration, Marketplace purchases, Support plan upgrades, third-party billed services
- Credits expire (typically 1-2 years from activation) — check Billing Console → Credits
---
## High-Burn Traps (avoid at early stages)
These eat credits even at zero traffic:
| Service | Hidden Fixed Cost | Alternative |
| --------------------- | ---------------------------- | ------------------------------------------- |
| NAT Gateway | $32/mo + $0.045/GB processed | VPC endpoints or no VPC |
| EKS Control Plane | $73/mo per cluster | Lambda, ECS Express Mode, or ECS Fargate |
| Multi-AZ RDS | 2x single-AZ cost | Aurora Serverless v2 or DynamoDB |
| OpenSearch Serverless | ~$700/mo minimum | Bedrock Knowledge Base managed vector store |
| VPN Connection | $36/mo | SSM Session Manager |
## Burn Rate Red Flags
- **NAT Gateway data processing**: Chatty services behind NAT can burn $100+/mo in processing alone
- **CloudWatch Logs default retention**: "Never expire" = costs accumulate forever. Set 7d dev / 30d prod.
- **Stopped EC2 still pays for EBS**, unattached volumes, idle ALBs
- **Over-provisioned RDS** at 5% CPU — use Aurora Serverless v2 instead
- **Dev environments running 24/7** — schedule stop outside business hours
---
## Credits Runway by Stage
| Stage | Monthly Spend Target | $25K Credits Lasts | $100K Credits Lasts |
| ----------- | -------------------- | ------------------ | ------------------- |
| Pre-Revenue | $0-50 | Years | Years |
| Seed | $100-500 | 50+ months | Years |
| Series A | $1K-10K | 2.5-25 months | 10-100 months |
---
## Stage-Specific Optimization
### Pre-Revenue: $0-50/month target
- Stay within free tier entirely — Lambda + DynamoDB + S3 all scale to zero
- **No custom VPC** — Lambda, DynamoDB, S3 work without one
- No NAT Gateway under any circumstances
### Seed: $100-500/month target
- Replace NAT Gateway with VPC endpoints for S3/DynamoDB (free)
- DynamoDB on-demand only — you don't know access patterns yet
- Use Graviton (ARM) for Lambda and Fargate — 20% cheaper for free
- Audit monthly with `aws ce get-cost-and-usage`
### Series A: When to start commitments
- Savings Plans ONLY after 3+ months of stable usage data
- Start with 1-year Compute Savings Plan, No Upfront
- Cover only 50-70% of baseline — leave room for variability
- Enable Cost Anomaly Detection (catches unexpected spikes)
---
## Credits Expiration: Don't Lose Them
If credits expire in <3 months with significant balance remaining, spend on things you'll need anyway:
- Staging/DR environments you were going to build
- Load tests and performance benchmarks
- Bedrock model experimentation
- Observability buildout (dashboards, alarms, tracing)
**Don't** spin up resources just to burn credits — that's worse than letting some expire.
references/customer-ideation.md
# Customer Ideation — Startup-Specific Discovery
## Startup-Adapted Discovery Questions
Standard AWS discovery asks 40+ questions. Startups need a focused subset that reveals architecture-critical constraints fast.
### The 6 Questions That Actually Matter for Startup Architecture
1. **What's your monthly AWS budget ceiling?** (Not "what do you want to spend" — what kills you if you exceed it?)
2. **How many engineers will touch infrastructure?** (If answer is 0-1, eliminate anything requiring operational expertise)
3. **What's your team's technical profile?** (Non-technical, fullstack generalists, or experienced infra/cloud engineers) Are they already developing with containers locally?
4. **Do you have AWS credits? How much, when do they expire?** (Changes every capacity planning decision)
5. **What's your current traffic/data volume, and what's your 12-month optimistic projection?** (Design for 10x current, have a PATH to 100x)
6. **What's the one thing that, if it breaks, kills your company?** (This is what gets redundancy. Everything else gets the cheapest option)
### Follow-Up Questions by Answer Pattern
**If budget < $500/mo:**
- Serverless-only architecture. No discussion.
- Ask: "Are cold starts acceptable for your use case?" (determines Lambda vs ECS Express Mode)
**If team = 1-2 engineers:**
- Eliminate: EKS, self-managed databases, custom networking
- If they're already running containers locally → ECS Express Mode. Don't push them to Lambda and force a rewrite of what already works.
- If they're non-technical founders or have no container experience → Lambda or Amplify. Lowest operational surface area.
**If team is experienced engineers (previous startups, cloud-native background):**
- Don't dumb it down. They can handle ECS, IaC, and CI/CD from day one.
- Match the deployment model to how they already develop — containerized local dev should deploy as containers.
- Focus guidance on cost optimization and AWS-specific gotchas, not basic architecture patterns.
**If credits > $25K:**
- They'll try to over-build. Push back: "What's the plan when credits expire in [month]?"
- Ask: "Which parts of your architecture are experiments vs committed?" (experiments get throwaway infra)
**If "the thing that kills us" is data loss:**
- Backups + point-in-time recovery are non-negotiable even pre-seed
- Ask: "Is the data reconstructible from an external source, or is it uniquely generated?"
**If "the thing that kills us" is downtime:**
- Multi-AZ on the critical path component only (not everything)
- Ask: "How many minutes of downtime per month is actually acceptable?" (usually more than they think)
## Startup Ideation Anti-Patterns
- **"We need to be enterprise-ready from day 1"**: No. You need to be enterprise-ready when enterprises want to buy. Build the path, not the destination.
- **"We'll need multi-region for global users"**: How many global users do you have today? CloudFront + single region handles global reads. Multi-region is a Series B problem.
- **"We should use Kubernetes because we'll need it eventually"**: The migration from Fargate to EKS takes 2-3 weeks. The cost of running EKS before you need it is 6-12 months of unnecessary complexity.
- **"We need a data lake"**: You have 10GB of data. You need an S3 bucket and Athena. A "data lake" is a label you put on it later.
## Qualify the Workload for Startup Context
After discovery, classify:
| Classification | Architecture Approach | Budget Constraint |
| -------------------------------------- | -------------------------------------------- | ---------------------- |
| **Experiment** (validating hypothesis) | Throwaway. Lambda + DynamoDB. No IaC needed. | < $50/mo |
| **MVP** (first users testing) | Simple but rebuildable. Basic IaC. | < $200/mo |
| **Product** (paying customers) | Production-grade on critical path only | < $2K/mo |
| **Scale** (proven PMF, growing) | Full Well-Architected applies | Budget follows revenue |
references/dynamodb.md
# DynamoDB — Startup-Specific Guidance
## When Startups Should Choose DynamoDB
**DynamoDB is the right default database for startups when:**
- Your data model is key-value or document-oriented (user profiles, sessions, IoT telemetry, orders)
- You need single-digit millisecond latency at any scale
- You want zero operational overhead (no patching, scaling, backups to manage)
- Your access patterns are known upfront (this is critical — DynamoDB punishes query pattern changes)
**DynamoDB is the WRONG choice when:**
- You don't know your access patterns yet (early prototyping with ad-hoc queries → use PostgreSQL)
- You need complex joins, aggregations, or flexible queries → use PostgreSQL/Aurora
- Your data is highly relational with many-to-many relationships → use PostgreSQL
- You need full-text search → use OpenSearch or PostgreSQL with pg_trgm
## The Access Pattern Lock-in Problem
This is the #1 DynamoDB mistake startups make: choosing DynamoDB for operational simplicity, then discovering 6 months later that a new feature requires a query pattern the table design doesn't support.
**Mitigation**: Before committing to DynamoDB, write down your top 10 access patterns. If you can't, you don't know enough about your product to choose DynamoDB. Use PostgreSQL/Aurora until patterns stabilize, then migrate hot paths to DynamoDB.
## Startup Cost Traps
1. **On-Demand mode at scale without noticing**: On-Demand is correct at the start (zero cost at zero traffic). But at sustained load, it's 5-7x more expensive than provisioned. **Trigger to switch**: when your DynamoDB bill exceeds $100/month with predictable traffic patterns, switch to provisioned with auto-scaling.
2. **GSI proliferation**: Each GSI copies all projected attributes and consumes write capacity on every write to the base table. Startups add GSIs reactively ("we need to query by email too") without budgeting the cost. At 5+ GSIs with full projections, you may be paying 5x your base table cost in GSI writes.
3. **Scan-based "analytics"**: Teams build admin dashboards that Scan the entire table. At 1M items, a full Scan costs ~$1.25 and takes seconds. At 100M items, it's $125 per scan. Export to S3 + Athena for analytics — never Scan production tables repeatedly.
4. **DAX when you don't need it**: DAX clusters start at ~$50/month (t3.small) and require VPC placement. Don't add DAX until you've confirmed: (a) reads are the bottleneck, (b) the same items are read repeatedly, (c) eventual consistency is acceptable. Most startups don't need DAX.
5. **DynamoDB Streams + Lambda at high volume**: Each Lambda invocation from Streams counts against your Lambda concurrent execution limit AND costs per invocation. At 10K writes/second, that's 10K Lambda invocations/second. Use Kinesis Data Streams as the consumer if write volume is high.
## Stage-Specific Recommendations
### Pre-PMF (validating product)
- **Use On-Demand mode** — zero cost at zero traffic, scales automatically
- **Simple key design**: don't over-engineer single-table design at this stage. One table per entity is fine (users table, orders table). Optimize later.
- **Enable Point-in-Time Recovery** ($0.20/GB-month) — your only protection against accidental deletes
- Total cost at low traffic: $0-5/month
### Post-PMF (scaling, Series A)
- Switch predictable tables to **Provisioned + Auto-Scaling** (target 70% utilization)
- Consider single-table design for entities that transact together
- Add DynamoDB Streams for event-driven patterns (materialized views, search indexing)
- Export to S3 for analytics instead of Scanning
### Scale (Series B+, >$1K/month DynamoDB)
- Reserved capacity (1-year or 3-year) for base throughput — up to 77% savings
- Evaluate Global Tables only if you genuinely need multi-region writes
- DAX for read-heavy hot key patterns
- Consider moving some tables to Aurora if query flexibility is needed
## Counterintuitive Startup Advice
- **Don't do single-table design at the start.** It's an optimization for scale and reduced table management. At pre-PMF with 2-3 entities, separate tables are more readable, easier to reason about, and trivial to change. Single-table design is a one-way door that's painful to refactor.
- **DynamoDB is often MORE expensive than Aurora for typical CRUD apps.** A startup with a standard web app (users, posts, comments, likes) paying $50/month for a `db.t4g.micro` Aurora Serverless v2 instance would pay $200+/month for the same data in DynamoDB with GSIs for all query patterns. DynamoDB wins on latency and ops burden, not on cost for relational-shaped data.
- **Free tier covers you longer than you think.** DynamoDB free tier (25 RCU, 25 WCU, 25 GB) is permanent and enough for ~200 reads/sec and ~25 writes/sec. Most pre-PMF startups never exceed this.
## When to Graduate FROM DynamoDB
| Signal | Direction |
| -------------------------------------------------------------- | ------------------------------------------- |
| Constantly needing new GSIs for new features | Your data is relational — use PostgreSQL |
| Admin dashboards Scanning tables | Export to S3, query with Athena |
| Need full-text search | Add OpenSearch (or use PostgreSQL) |
| Monthly bill > $500 with Reserved Capacity still too expensive | Data model mismatch — evaluate alternatives |
## Credits-Specific Guidance
- DynamoDB On-Demand costs are covered by credits. During credits: stay on On-Demand even if traffic is predictable — the flexibility is worth it while you're iterating on data models.
- When credits expire: On-Demand bills hit immediately. Switch to Provisioned + Auto-Scaling for any table with consistent traffic before credits run out.
- Point-in-Time Recovery and backups also count against credits — enable them generously during the credits period.
references/ec2.md
# EC2 — Startup-Specific Guidance
## When Startups Should Use EC2 Directly
**Almost never as your first choice.** Start with Lambda or ECS Fargate. EC2 makes sense for startups only when:
- You need GPUs (ML training/inference) — no Fargate GPU support
- You're running software that requires full OS control (custom kernels, specific drivers, Docker-in-Docker)
- You're running a stateful workload that doesn't fit managed services (self-managed databases, Redis clusters, Kafka)
- Your sustained compute spend exceeds $10K/month and you can commit to instance management
**The hidden cost**: EC2 requires patching, AMI management, monitoring agents, and capacity planning. At a 3-person startup, that's 10-20% of an engineer's time — your scarcest resource.
## Startup Cost Traps
1. **Running instances 24/7 in dev/staging**: A `t3.medium` costs ~$30/month. Three dev environments left running = $90/month doing nothing nights/weekends. Use Auto Scaling scheduled actions or Lambda-triggered stop/start. Savings: 65% on non-prod instances.
2. **Elastic IPs not attached to instances**: $3.60/month per unused EIP. Teams allocate them "for later" and forget. Check monthly.
3. **gp2 volumes still in use**: gp2 costs more than gp3 and performs worse at small sizes (gp2 scales IOPS with size; gp3 gives 3000 IOPS baseline regardless). Convert all gp2 → gp3 immediately, it's free and non-disruptive.
4. **Savings Plans purchased too early**: Don't buy Compute Savings Plans until you have 3+ months of stable EC2 usage data. Startups pivot — a 1-year commitment on instance types you abandon in 3 months is wasted money.
5. **Data transfer between AZs**: $0.01/GB each way. A chatty microservices architecture across AZs can accumulate $100s/month in cross-AZ transfer that doesn't show up obviously in Cost Explorer. Keep tightly-coupled services in the same AZ or use ECS/EKS service mesh for efficient routing.
## Stage-Specific Recommendations
### If You Must Use EC2 (Pre-Series A)
- **Single instance, single AZ** is acceptable for non-critical workloads
- Use `t3.small` or `t3a.small` ($15/month) — burstable is fine for dev/staging
- Use Spot for batch/ML training from day one — 70-90% savings and you learn the interruption model early
- **SSM Session Manager, not SSH keys** — zero additional infrastructure cost and IAM-controlled
### Growth Stage (Series A-B, steady EC2 usage)
- Buy 1-year No Upfront Compute Savings Plans for baseline (30% savings, flexible across instance types)
- Graviton (ARM64): migrate workloads for 20-30% cost reduction — most Docker containers work unchanged
- Mixed instance ASGs: 3+ instance types, Spot for workers, On-Demand for stateful
### Scale ($50K+/month EC2)
- 3-year Partial Upfront Savings Plans for steady-state base (up to 60% savings)
- Reserved Instances for specific GPU instances that don't change
- Spot fleet with `capacity-optimized` for batch/ML — diversify across 10+ instance types
## Counterintuitive Startup Advice
- **A single EC2 instance is a valid architecture.** For internal tools, admin panels, or low-traffic services that don't justify container orchestration — one `t3.small` with a Docker Compose setup and an AMI-based backup strategy works fine. It's not "production best practice" but it's pragmatic until revenue justifies HA.
- **Don't build for multi-AZ until you have paying customers who'd notice.** Multi-AZ doubles your compute baseline cost. If your SLA is informal and your recovery plan is "redeploy from AMI in 10 minutes," that's fine at pre-PMF.
- **Spot instances for production stateless workloads is fine.** The standard advice is "never use Spot in production." For startups: if your service handles graceful shutdown and you have On-Demand fallback in your ASG, the 70% savings funds an extra engineer-month every few months.
## When to Graduate TO EC2 (from Fargate)
| Signal | Why EC2 |
| -------------------------------------------------- | --------------------------------------- |
| Monthly Fargate spend > $10K with >80% utilization | EC2 + Savings Plans is 30-50% cheaper |
| Need GPU instances | No Fargate GPU support |
| Need instance store NVMe for caching | Fargate has no local storage option |
| Running workloads requiring privileged containers | Fargate doesn't support privileged mode |
## Credits-Specific Guidance
- EC2 On-Demand is covered by AWS Activate credits. During credits: don't buy Savings Plans or Reserved Instances — they can't be applied against credits and you lose flexibility.
- When credits expire: you'll hit full on-demand pricing immediately. Plan 1 month ahead: identify steady-state instances, purchase Savings Plans, and right-size or terminate anything over-provisioned.
- GPU instances (P/G family) burn credits extremely fast. A single `p3.2xlarge` costs ~$2,200/month. Use Spot for training and be deliberate about GPU hours.
references/ecs.md
# ECS — Startup-Specific Guidance
## When to Choose ECS (vs Lambda or EKS)
**Choose ECS when**: You've outgrown Lambda ($300-500+/month Lambda bill with steady traffic), need long-running processes, WebSockets, or >6MB responses, but don't have a platform team to run Kubernetes.
**The startup sweet spot**: ECS Fargate is the "right-sized" container platform for teams of 1-15 engineers. It gives you containers without the Kubernetes learning curve, tax, or operational burden.
**Do NOT start with ECS if**: Your traffic is spiky/unpredictable and you can fit in Lambda's constraints. Lambda's scale-to-zero beats Fargate's minimum-task cost for low-traffic services.
## Startup Cost Traps
1. **Fargate Spot in production services**: 70% savings sounds great, but Spot tasks get terminated with 30s warning. Use ONLY for: batch jobs, queue workers, background processing. Never for user-facing APIs unless you have graceful failover to on-demand.
2. **Over-provisioned task definitions**: Startups copy-paste `2 vCPU / 4GB` task defs without measuring. A typical Node.js/Python API serves 200+ req/s on `0.25 vCPU / 0.5GB` (~$9/month). Start at the minimum and scale up based on Container Insights metrics.
3. **ALB cost baseline**: An ALB costs ~$22/month minimum (fixed hourly) + LCU charges. For a startup with 2-3 services, that's fine. But don't create one ALB per service — use path-based routing on a shared ALB until you need isolation.
4. **NAT Gateway double-tax**: Fargate tasks in private subnets need NAT for internet access. NAT costs $32/month + $0.045/GB processed. For early startups with one service, consider running in public subnets with security groups locked down (heresy, but saves $32/month). Graduate to private subnets when you have compliance requirements or >3 services.
5. **Container Insights**: Costs ~$7-15/month in CloudWatch charges per cluster. Worth it for production, not needed for dev/staging.
## Stage-Specific Recommendations
### Pre-PMF (1-5 engineers, <$1K/month infra)
- **Single Fargate service**, single ALB, public subnet (with locked-down SG)
- `0.25 vCPU / 0.5GB` task, `minCount=1`, `maxCount=3`
- Use `ECS Exec` for debugging (replaces SSH)
- Total cost: ~$35-50/month (1 task + ALB)
### Post-PMF / Series A (5-15 engineers, $1K-10K/month)
- Move to private subnets + NAT Gateway
- Add a second service (worker/background jobs)
- Enable Container Insights on production cluster
- Use Fargate Spot for workers, on-demand for APIs
- Consider Graviton (`ARM64`) — 20% cheaper on Fargate too
### Scaling (Series B+, >$10K/month compute)
- Evaluate ECS on EC2 with Savings Plans if >80% utilization sustained
- Fargate's ~20-30% premium over EC2 matters at $50K+/month
- At this stage, also evaluate if EKS makes sense for your hiring pipeline (more K8s engineers available than ECS-specific)
## Counterintuitive Startup Advice
- **One cluster, one service is fine.** The "one cluster per environment" guidance assumes you have environments. At pre-PMF, run one cluster with one production service. Add dev/staging clusters when you have a team that needs them.
- **Skip blue/green deployments initially.** Rolling updates with circuit breaker give you auto-rollback without CodeDeploy complexity. Blue/green adds value at scale (instant rollback) but adds operational surface area early.
- **`:latest` tag is acceptable in dev/staging.** Yes, it's an anti-pattern in production. But for a 2-person team iterating daily, the overhead of tagging every dev build with a SHA isn't worth it until you have a CI/CD pipeline.
- **Don't multi-region until revenue demands it.** ECS services in 2 regions = 2x base cost + cross-region complexity. Stay single-region until you have customers requiring <50ms latency in another continent or contractual uptime SLAs.
## When to Graduate from ECS
| Signal | Direction |
| ----------------------------------------------------------- | -------------------------------------------------------- |
| Team > 15 engineers, multiple teams deploying independently | Evaluate EKS — better multi-tenancy, namespace isolation |
| Monthly compute bill > $50K with Fargate | Evaluate ECS on EC2 with Spot + Savings Plans |
| Need service mesh, custom autoscaling, GitOps | EKS ecosystem is richer for these |
| Hiring pipeline returns mostly K8s-experienced candidates | Switching cost is worth it for velocity |
## Credits-Specific Guidance
- Fargate compute is covered by AWS Activate credits. During credits: use on-demand everywhere, don't bother with Spot, and provision for peak.
- When credits expire: the "always on" baseline of Fargate tasks hits immediately. Budget the transition: right-size tasks, add Spot for workers, configure scale-to-zero for non-prod.
- Fargate costs are predictable — easy to model post-credits burn rate: `tasks × hours × (vCPU_price + memory_price)`.
references/eks.md
# EKS — Startup-Specific Guidance
## The Hard Truth: Most Startups Shouldn't Use EKS
**EKS is a Series B+ decision.** The Kubernetes tax is real:
- EKS control plane: $73/month (before any workload runs)
- Minimum viable production cluster: ~$300-500/month (control plane + 2-3 nodes + ALB + NAT)
- Platform engineering time: 20-40% of one engineer's bandwidth for maintenance, upgrades, RBAC, networking
- Time to first deploy: days/weeks vs hours for ECS Fargate
**Choose EKS only when:**
- Team > 10-15 engineers with multiple teams needing namespace isolation
- You're hiring primarily from a Kubernetes-experienced talent pool
- You need advanced scheduling (GPU sharing, bin-packing, multi-tenancy)
- Your compute spend exceeds $20K/month and Karpenter's optimization justifies the platform cost
- You're already running K8s and migrating to AWS (don't re-learn ECS just for AWS)
## Startup Cost Traps
1. **The $73/month control plane for dev/staging**: Many startups create 3 clusters (dev/staging/prod) = $219/month in control planes alone before a single pod runs. At pre-Series A, use namespaces on a single cluster for isolation. Add dedicated clusters at Series B.
2. **Managed node groups with oversized instances**: Default tutorials use `m5.large` nodes. A startup running 3-5 microservices needs maybe 2-4 vCPUs total. Use `t3.medium` nodes or Karpenter with tight resource limits.
3. **Add-on sprawl**: Each add-on (cert-manager, external-dns, ArgoCD, Datadog, Istio) runs pods that consume node resources. A "production-ready" cluster with common add-ons needs 2-4 vCPUs just for platform components. Budget this separately.
4. **Karpenter consolidation disabled**: Karpenter defaults to not consolidating nodes. Enable `consolidationPolicy: WhenEmptyOrUnderutilized` immediately — it's the primary mechanism for right-sizing your fleet and avoiding paying for idle capacity.
5. **Load Balancer per service**: Each Kubernetes `Service type: LoadBalancer` creates an NLB (~$16/month). Use an Ingress controller (ALB Controller or nginx) to share one load balancer across services.
## Stage-Specific Recommendations (If You're Committed to EKS)
### Early (1 cluster, <$5K/month compute)
- Single cluster, namespaces for env separation (dev/staging/prod namespaces)
- Karpenter from day one — never use Cluster Autoscaler for new clusters
- Fargate profiles for low-traffic namespaces (dev) to avoid idle node costs
- Skip service mesh (Istio/Linkerd) — use simple K8s Services and Network Policies
- ArgoCD for GitOps from the start — it's free and prevents `kubectl apply` drift
### Growth ($5K-50K/month compute)
- Separate prod cluster from non-prod
- Karpenter with Spot for stateless workloads (70% savings)
- Pod Identity for IAM (not IRSA) — simpler, fewer moving parts
- Enable control plane logging for security/audit
- Implement PodDisruptionBudgets for all production workloads
### Scale ($50K+/month compute)
- Dedicated node groups for isolation (GPU, high-memory, batch)
- Multi-cluster with fleet management (if multi-region needed)
- Full observability stack (Prometheus/Grafana or Datadog)
- Consider EKS Anywhere for hybrid if needed
## Counterintuitive Startup Advice
- **ECS to EKS migration is easier than EKS to ECS.** If unsure, start with ECS. If you later need K8s, your containers and Dockerfiles transfer unchanged — only the orchestration layer changes. The reverse (EKS → ECS) requires removing all K8s-specific config (Helm charts, CRDs, operators).
- **A well-run ECS setup is operationally simpler AND cheaper than EKS until $20K/month compute.** The K8s ecosystem flexibility only pays off when you have enough services and team size to leverage it.
- **Don't use Helm for everything.** Early startups over-invest in templating 3-5 services with complex Helm charts. Plain Kubernetes manifests + Kustomize overlays are more readable and debuggable for small teams. Switch to Helm when you have 10+ services with shared patterns.
- **Fargate on EKS is worse than Fargate on ECS.** EKS Fargate has more limitations (no DaemonSets, no persistent volumes, no GPUs, higher per-pod overhead, slower scheduling). If you want Fargate simplicity, use ECS. If you want EKS, use managed node groups with Karpenter.
## When to Graduate TO EKS
| Signal | Why Now |
| ----------------------------------------------------- | --------------------------------------- |
| >15 engineers, multiple teams deploying independently | Namespace isolation, RBAC per team |
| Monthly compute > $20K, need optimization | Karpenter's bin-packing saves 30-40% |
| Need GPU sharing across workloads | K8s device plugin + time-slicing |
| Hiring pipeline is primarily K8s-experienced | Developer experience matters |
| Need advanced traffic management | K8s ecosystem (Istio, Cilium) is richer |
## Credits-Specific Guidance
- EKS control plane ($73/month) is covered by credits but is a fixed cost — don't create clusters you won't use.
- During credits: experiment with EKS to validate if your team can operate it. This is the time to learn without cost pressure.
- If your team struggles with EKS during the credits period, that's your answer — switch to ECS before credits expire and you're paying $500+/month for a platform you can't operate well.
references/iac-scaffold.md
# IaC Scaffold — Startup-Specific Guidance
## When to Introduce IaC (Not Day 1 for Everyone)
| Stage | IaC Recommendation | Why |
| -------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| Pre-seed solo founder | Skip IaC. Console + CLI. | You're iterating daily. IaC slows you down at this stage. Document what you clicked. |
| Pre-seed with 2+ engineers | Minimal IaC (CDK or Terraform for the main stack only) | Reproducibility matters when 2 people touch infra |
| Seed | IaC required for production resources | You need a second environment and can't recreate from memory |
| Series A+ | Everything in IaC, no exceptions | Audit trail, repeatability, team onboarding |
## Framework Selection for Startups
| Factor | CDK (TypeScript) | Terraform | SAM |
| --------------------------- | ------------------------------ | ------------------------------------------- | --------------------------------------- |
| Startup default | ✅ If team writes TypeScript | ✅ If multi-cloud possible or team knows it | ✅ If pure serverless (Lambda + API GW) |
| Learning curve for web devs | Low (it's TypeScript) | Medium (new DSL) | Low (YAML + familiar) |
| Footgun risk | Medium (generates complex CFN) | Low (explicit) | Low (simple scope) |
| Operational overhead | Low (CDK CLI) | Medium (state management) | Lowest |
| When to switch away | Never needed for most startups | If going all-in AWS (CDK advantage) | When you add non-serverless resources |
**Opinionated startup default**:
- Pure serverless app → SAM (simplest, fastest iteration with `sam local`)
- Full-stack app → CDK in TypeScript (same language as your app, likely)
- Multi-cloud or Terraform-experienced team → Terraform
## Startup IaC Anti-Patterns
| Anti-Pattern | Why It Hurts | Do This Instead |
| --------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Separate repo for IaC | Context switching, drift between app and infra | Monorepo: `/infra` next to `/src` |
| One stack per resource | Deployment takes forever, circular dependencies | One stack per LIFECYCLE (stateful data, stateless compute, networking) |
| Custom constructs/modules before needed | Abstraction without understanding = debugging nightmare | Use L2 constructs (CDK) or official modules (Terraform). Write custom only on third use. |
| IaC for developer sandboxes | Over-engineering for ephemeral environments | `cdk deploy --context env=dev` with cheaper defaults, or just use console for scratch |
| Parameterizing everything | 50 parameters nobody understands | Hardcode sensible defaults. Parameterize only what CHANGES between environments |
## Startup-Optimized Stack Separation
```
stack-1: foundation (VPC if needed, DNS zone, shared secrets)
→ Deploys once, changes rarely
→ Even for pre-seed: just DNS zone + maybe a VPC
stack-2: data (databases, S3 buckets, DynamoDB tables)
→ Deploys rarely, NEVER destroyed (data loss)
→ Enable deletion protection on everything here
stack-3: compute (Lambda functions, ECS services, API Gateway)
→ Deploys frequently (every PR merge)
→ Safe to destroy and recreate
```
**Key rule**: Never put databases and compute in the same stack. A botched compute deploy should never risk your data.
## Minimum Viable IaC for Startups
If you're scaffolding for the first time, include ONLY:
1. The compute + API layer
2. The data layer (separate stack)
3. A `Makefile` with: `deploy`, `destroy`, `diff`, `logs`
4. Environment config: `dev` and `prod` (not `staging`, `qa`, `perf`, etc.)
Skip until needed:
- CI/CD pipeline IaC (use GitHub Actions with `aws-actions/configure-aws-credentials` — simple YAML)
- Monitoring/alerting IaC (click 3 alarms in the console — faster than writing CDK for them)
- Multi-account bootstrap (until you actually have multiple accounts)
- Custom domains + ACM certs (until you need them for customers)
references/iam.md
# IAM — Startup Decision Guide
## Stage-Based Recommendation
### Pre-PMF (Seed / <$1M ARR, 1-5 engineers)
- **AWS managed policies are fine.** Don't spend days crafting least-privilege policies when your team is 3 people and you're iterating daily. Use `PowerUserAccess` (no IAM admin) for developers.
- **Skip Identity Center until you have 5+ engineers.** Below that, IAM users with MFA and forced credential rotation is pragmatic. The setup cost of Identity Center + IdP isn't worth it for 2-3 people.
- **One AWS account is fine.** Multi-account is best practice but overkill when you're pre-revenue. Add a second account (prod) when you have paying customers.
### Post-PMF / Growth ($1M-$10M ARR, 5-30 engineers)
- **Set up Identity Center now.** You've delayed long enough. Connect to Google Workspace or Okta (whichever your company already uses).
- **Separate prod account.** If you haven't done this yet, do it before your next compliance audit.
- **Use Access Analyzer.** Generate policies from CloudTrail activity to replace overly broad managed policies. Takes 30 minutes, saves you in your SOC2 audit.
- **Permission boundaries for senior devs** who need to create IAM roles (for Lambda, ECS). Prevents accidental privilege escalation.
### Scale ($10M+ ARR, 30+ engineers)
- Full AWS Organizations with SCPs.
- Account-per-team or account-per-service pattern.
- This is when you hire a security engineer.
## Cost Traps
IAM itself is free, but IAM mistakes cause cost explosions:
| Trap | Impact | Fix |
| ------------------------------------------ | ---------------------------------------------------- | ------------------------------------------------------ |
| Over-broad Lambda execution role | Lambda accesses (and pays for) services it shouldn't | Scope to specific DynamoDB tables, S3 buckets by ARN |
| No region restriction | Resources accidentally created in expensive regions | SCP denying all regions except your primary |
| No `sts:ExternalId` on cross-account roles | Confused deputy → unauthorized access | Always require ExternalId for third-party integrations |
## Counterintuitive Advice
- **`AdministratorAccess` for the founding engineer is OK at seed stage.** The blast radius is one account with no customers. Velocity matters more than least privilege when you're proving the idea works. Add guardrails when you add the 4th engineer.
- **Don't implement SCPs until you have 3+ accounts.** SCPs on a single-account org do nothing useful but add debugging complexity.
- **Managed policies > custom policies until SOC2.** Your custom policies will have bugs. AWS managed policies are tested and maintained. Switch to custom when compliance requires it or when you need to restrict specific resources.
- **Skip IAM Access Analyzer findings in dev accounts.** Cross-account access in your dev account is not a security incident. Focus Access Analyzer on prod only.
## Minimum Viable Security Posture by Stage
### Seed (just don't get hacked)
- [ ] MFA on root account (hardware key in a safe)
- [ ] MFA on all IAM users
- [ ] No root access keys ever
- [ ] `PowerUserAccess` for engineers (can't modify IAM)
- [ ] One admin user for IAM changes
- [ ] Enable CloudTrail (default trail is free)
### Series A (preparing for SOC2)
- [ ] Identity Center with Google/Okta SSO
- [ ] Separate prod account
- [ ] Permission boundaries on developer roles
- [ ] Access Analyzer enabled in prod
- [ ] SCP: deny all regions except primary + us-east-1 (for global services)
- [ ] SCP: deny root access key creation
### Series B+ (passing SOC2/HIPAA audits)
- [ ] Full Organizations with OU structure
- [ ] SCPs on every OU
- [ ] Custom least-privilege policies from Access Analyzer
- [ ] Automated credential rotation
- [ ] GuardDuty in all accounts
- [ ] Security Hub aggregating findings
## When to Graduate
| Trigger | Action |
| ---------------------------- | ------------------------------------------------------------ |
| 4th engineer joins | Move from IAM users to Identity Center |
| First paying customer | Create prod account, move workloads |
| SOC2 audit scheduled | Access Analyzer, SCPs, permission boundaries |
| 3rd AWS account | AWS Organizations + OU structure |
| External vendor needs access | Cross-account role with ExternalId (never share credentials) |
references/investor-readiness.md
# Investor Readiness
## What Investors Actually Ask (and How to Answer)
### Seed Pitch: Speed + Capital Efficiency Story
**Template**:
> "We built on serverless AWS infrastructure that costs near-zero at current scale and grows linearly with users. Monthly cost is $X, credits give us Y months of runway before infra becomes a line item. Architecture handles 100x current load without changes."
**Don't say**: anything about Kubernetes, microservices, or complex architecture (signals over-engineering). Don't say "we'll need to rewrite at scale" (signals poor planning).
### Series A Pitch: Unit Economics + Reliability
Key metrics to have ready:
| Metric | Target |
| -------------------------------- | -------------------- |
| Infra cost / active user / month | Decreasing over time |
| Deploy frequency | Daily or more |
| Uptime (last 90 days) | >99.5% |
| Mean time to recovery | <1 hour |
| Infra cost as % of MRR | <10% for SaaS |
---
## Red Flags Investors Look For
| Red Flag | What It Signals |
| -------------------------------------- | --------------------------------------- |
| "We'll need to rewrite at scale" | Poor planning, future capital sink |
| Very high infra cost vs revenue | Capital inefficiency |
| Single engineer who "knows everything" | Bus factor = 1 |
| No uptime data | Operational immaturity |
| Over-engineered for current scale | Wasted capital, slow shipping |
| Vendor lock-in without rationale | Strategic risk (acknowledge trade-offs) |
---
## How to Present AWS Costs to Investors
**Don't** show a raw AWS bill with 47 line items.
**Do** present in business terms:
```
Monthly Infrastructure: $X,XXX
├── Compute (API + background): XX%
├── Database: XX%
├── AI/ML (Bedrock): XX%
├── Storage + CDN: XX%
└── Other: XX%
Cost per active user: $X.XX/month
Cost as % of MRR: X%
Credits remaining: $XX,XXX (X months at current burn)
```
## Unit Economics Healthy Ranges (SaaS)
| Metric | Healthy Range |
| ---------------------------------------------------- | ----------------- |
| Infra cost per user | $0.50-5.00/month |
| Infra as % of revenue | 5-15% |
| Gross margin (after infra COGS) | >70% |
| Cost scaling factor (% infra growth / % user growth) | <1.0 (sub-linear) |
---
## Due Diligence Prep (Series A+)
Have these ready for technical DD:
1. One-page architecture diagram (components + data flow)
2. Scaling plan at 10x and 100x (ideally: "nothing changes" for serverless)
3. Honest list of single points of failure + mitigation plan
4. RTO/RPO targets
5. Technical debt acknowledgment + paydown plan
6. No single person is a blocker for any system
7. Historical cost trajectory + projection at target scale
references/iot.md
# IoT — Startup Decision Guide
## The IoT Cost Curve: Why Startups Get Surprised
IoT costs are multiplicative: `devices × messages/device × actions/message`. A fleet of 10,000 devices sending 1 msg/sec generates 864M messages/day. Startups that prototype with 10 devices don't see this coming.
### Cost at Scale (Monthly Estimates)
| Fleet size | Msg frequency | IoT Core messaging cost | Storage cost (Timestream) | Total minimum |
| -------------- | ------------- | ----------------------- | ------------------------- | ------------- |
| 100 devices | 1/min | $4 | $20 | ~$50 |
| 1,000 devices | 1/min | $44 | $200 | ~$400 |
| 10,000 devices | 1/min | $440 | $2,000 | ~$4,000 |
| 10,000 devices | 1/sec | $26,400 | $120,000 | 🚨 |
**The lesson**: Message frequency is the cost multiplier. Design for the lowest frequency that meets product requirements. If you need 1/sec sensing but only 1/min cloud reporting, aggregate at the edge.
## Stage-Specific Architecture
| Stage | Fleet size | Architecture | What to skip |
| ------------------------ | ---------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Prototype (< 50 devices) | < 50 | IoT Core → Rules → DynamoDB/S3. Done. | Greengrass, SiteWise, Fleet Indexing, Device Defender |
| Pilot (50-1000 devices) | 50-1K | Add: Device Shadow, Fleet Provisioning, basic monitoring | SiteWise (unless industrial), multi-region, Greengrass (unless offline needed) |
| Scale (1K-100K devices) | 1K-100K | Add: Greengrass edge compute, Fleet Indexing, Device Defender, Timestream | Custom analytics platform (use Timestream + Grafana) |
| Enterprise (100K+) | 100K+ | Full stack: multi-region, SiteWise if industrial, custom data lake | Nothing — you need it all |
## Cost Traps Specific to Startups
### 1. Basic Ingest: The $1/Million Messages You Don't Need to Pay
Standard MQTT publish: $1.00 per million messages broker fee + rules engine fee.
<!-- markdownlint-disable-next-line MD033 -->
Basic Ingest (`$aws/rules/<rule-name>` topic): $0 broker fee, only rules engine actions charged.
**Use Basic Ingest for all high-volume telemetry that only needs to flow to the cloud (no device-to-device).** Most startup telemetry is one-directional. This saves 50% on messaging costs with a topic prefix change.
### 2. Timestream vs S3+Athena: When to Use Which
| Need | Choice | Monthly cost at 10K devices, 1 msg/min |
| ---------------------------------------- | ------------------------------------------ | -------------------------------------- |
| Real-time dashboards, sub-second queries | Timestream | ~$2,000 |
| Nightly batch analytics, ad-hoc queries | S3 + Athena | ~$50-100 |
| Both | Timestream for last 24h, S3 for historical | ~$500 (short memory retention) |
**Startup default**: S3 + Athena until you have a real-time dashboard requirement. Most seed-stage IoT startups query telemetry weekly, not in real-time.
### 3. DynamoDB for Telemetry: The $1,100/Day Mistake
10,000 devices × 1 msg/sec = 864M writes/day = ~$1,100/day on-demand DynamoDB.
**Never store raw time-series telemetry in DynamoDB.** Use it only for device metadata, latest-known state, and configuration. Route telemetry to Timestream (10-20x cheaper for time-series writes) or S3 ($0.023/GB/month).
### 4. OpenSearch for IoT Dashboards: The Always-On Cost
OpenSearch clusters run 24/7 (~$200-500/month minimum). If your dashboard usage is intermittent (operators check once/day), use:
- Timestream + Grafana (serverless-ish, cheaper for periodic access)
- S3 + Athena + QuickSight (fully serverless, pay per query)
### 5. Cellular Data Costs That Dwarf AWS Costs
Hardware startups often overlook this: a cellular modem (LTE-M/NB-IoT) costs $0.50-2.00/MB depending on carrier. A device sending 1KB every minute = 1.4MB/month = ~$1-3/device/month in CARRIER costs alone. At 10K devices, that's $10-30K/month before AWS sees a single byte.
**Optimization**: Aggregate readings on-device and send batched payloads every 5-15 minutes instead of per-reading. Compress with CBOR instead of JSON (40-60% smaller). This directly reduces your carrier bill — often your largest IoT cost at scale.
## Counterintuitive Advice for IoT Startups
### Don't Start with Greengrass
Greengrass adds significant operational complexity (component deployments, edge device management, Nucleus updates). Start with direct MQTT to IoT Core unless you have one of these hard requirements:
- **Must operate offline** (no cloud connectivity for hours/days)
- **Latency < 100ms for control loops** (cloud round-trip is 50-200ms)
- **Bandwidth costs dominate** (cellular data at $0.01/MB with high-frequency sensors)
**When to add Greengrass**: When your cloud ingestion bill exceeds the operational cost of managing edge infrastructure, OR when you have a hard offline/latency requirement.
### One Certificate Per Device (Even If It's Painful)
Shared certificates are tempting for prototypes ("just get devices connected"). But revocation of a shared cert disconnects your entire fleet. The migration from shared → per-device certs is painful at scale. Start with per-device certs from day one using Fleet Provisioning by Claim.
### Fleet Provisioning: Don't Overthink It
| Manufacturing capability | Method | Startup phase |
| ------------------------------------------ | ---------------------------------- | --------------------------------------- |
| Can't install unique certs (most startups) | Fleet Provisioning by Claim | Use from day one |
| Have a mobile app for setup | Fleet Provisioning by Trusted User | Consumer IoT |
| Factory installs unique certs | JITP | Later stage, when you own manufacturing |
**Critical**: Always add a pre-provisioning Lambda hook to validate device serial numbers against an allow-list. Without it, anyone who reverse-engineers your firmware can provision unlimited devices.
### Your Firmware Update Story Is Your Company's Survival Story
IoT startups that can't OTA update their fleet die slowly. A bug in the field with no update path means:
- Hardware recalls ($50-200/device in logistics alone)
- Customer churn from unresolvable issues
- Inability to iterate on the product post-deployment
**From day one**: Even if you skip everything else, implement IoT Jobs-based OTA updates with rollback. Configure abort criteria (>5% failures = halt rollout). Test the update path before shipping your first 10 devices. The cost of getting this wrong at 1,000 devices is company-ending for a hardware startup.
## IoT + AI: When to Run ML at the Edge
| Signal | Where to run inference | Why |
| ---------------------------------------- | ------------------------------- | ------------------------------------------------------ |
| < 10 inferences/hour, small payload | Cloud (Lambda or Bedrock) | Simpler, no edge ML complexity |
| > 100 inferences/hour OR latency < 200ms | Edge (Greengrass + local model) | Bandwidth/latency requirements justify edge complexity |
| Camera/video data | Edge always | Streaming video to cloud is prohibitively expensive |
| Model > 500MB, device has < 2GB RAM | Cloud | Model doesn't fit on device |
## The Hardware-Software Timing Trap
Software startups iterate weekly. Hardware startups iterate quarterly (PCB rev cycles). This mismatch kills IoT startups that plan cloud architecture in lockstep with hardware timelines.
**What to do**: Over-provision your cloud capabilities relative to hardware. Your first PCB will be wrong. Your second will be better. Your cloud architecture needs to absorb both without re-architecture. Specifically:
- Design topic structures that accommodate device types you haven't built yet
- Use Device Shadow for ALL configuration (don't hardcode anything on-device that might change)
- Build your provisioning flow for "devices we haven't designed" — because you'll have 3 hardware revisions running simultaneously within 18 months
## The "Connected Product" vs "IoT Platform" Decision
Most IoT startups start thinking they're building a platform. They're not. They're building one connected product.
| You're building a... | Architecture approach | Skip |
| -------------------- | ------------------------------------------------------ | --------------------------------------------------------------------- |
| Connected product | Single device type, simple rules, focused dashboard | Multi-tenancy, device type abstraction, white-labeling infrastructure |
| IoT platform/SaaS | Multi-tenant from day one, device-type-agnostic ingest | Nothing — but hire for this complexity |
**90% of seed-stage "IoT platforms" should be connected products first.** Build the platform abstraction only after you have 3+ customers wanting different device types. The premature platform trap wastes 6-12 months of engineering on infrastructure your first 5 customers don't need.
## Startup-Specific Gotchas: Investor & Go-To-Market
### The Pilot-to-Paid Chasm
IoT startups often give away 50-200 devices as "pilots." The architecture cost at pilot scale ($50-400/month from the tables above) is trivial. But the customer expects the same architecture when they order 10,000 devices — and that's $4,000+/month.
**Before the pilot**: Model the cost at the customer's target fleet size. If the unit economics don't work (cloud cost per device > willingness to pay), you have a business model problem, not a technology problem. Discover this before the pilot, not after.
### Hardware Margins Are Thin — Cloud Costs Eat Them
A typical hardware startup's BOM cost is $50-200/device with 40-60% gross margins on hardware sale. If your cloud cost is $5/device/month and customer pays $10/device/month for the "subscription" — your cloud COGS is 50% of recurring revenue before you pay for anything else.
**Model this explicitly for investors**:
- Hardware margin: X%
- Recurring revenue per device: $Y/month
- Cloud cost per device at target scale: $Z/month
- Net recurring margin: $(Y-Z)/Y
If Z > 30% of Y, optimize your architecture before scaling, not after.
### The "Free Tier Pilot" Illusion
IoT Core free tier: 500,000 messages/month for 12 months. That's ~11 messages/minute across your entire fleet. With 50 pilot devices sending 1 msg/min, you burn through free tier in 7 days.
Don't promise "zero cost pilot" to customers based on free tier math. It doesn't scale to even modest pilots.
## Anti-Patterns (Startup-Specific)
- **Designing for 1M devices at 100 devices.** The architecture for 100 devices (direct MQTT, no edge compute, DynamoDB for state) is radically different from 1M devices. Build for 10x your current fleet, not 10,000x. Premature scaling wastes months of engineering time.
- **HTTP polling from battery-powered devices.** A device polling every 5 seconds: 17,280 requests/day, drains battery in weeks. MQTT persistent connection: near-zero overhead when idle, battery lasts months. This is the #1 hardware startup mistake.
- **No error actions on IoT Rules.** Failed rule actions silently drop data. You won't know you're losing telemetry until a customer complains about missing data. Always route errors to S3 or SQS — takes 5 minutes to configure.
- **Timestream with default memory retention (24h) for dashboards needing 7-day views.** You'll query magnetic store (10x slower, different pricing model). Set memory retention to match your hot-query window.
- **Building a "device management portal" before device #100.** Your first 50 devices can be managed with AWS Console + CLI scripts. The custom portal takes 2-3 months of engineering time that should go toward the core product. Build it when operators (not engineers) need to manage the fleet.
- **Choosing WiFi-only when customers have industrial sites.** Consumer IoT = WiFi. Industrial/commercial IoT = often no reliable WiFi. If your customer is a factory, warehouse, or field operation, design for cellular (LTE-M/NB-IoT) from prototype. Retrofitting connectivity is a hardware redesign.
- **Not budgeting for device returns and RMA.** 5-10% of deployed IoT devices will have issues in year one. Your architecture needs: remote diagnostics (shadow + logs), remote remediation (OTA), and graceful decommissioning (cert revocation, thing deletion). Without these, every issue is a $50-200 truck roll or RMA.
- **Shared X.509 certificates across devices.** Revoking one shared cert disconnects entire fleet. One cert per device limits blast radius.
## Credits-Specific Guidance
- IoT Core messaging, Rules Engine actions, and Device Shadow operations are all credit-eligible
- **Timestream burns credits fast** — 10K devices at 1 msg/min with 7-day memory retention = ~$2K/month in credits consumed
- During credits: use Timestream generously to validate your real-time dashboard needs. If you discover nobody looks at real-time data, switch to S3+Athena before credits expire and save $2K/month
- Greengrass has no per-device cloud cost (it's edge software) — but the devices it runs on aren't free. Factor in the $15-50/device compute module cost in your BOM
references/lambda.md
# Lambda — Startup-Specific Guidance
## When Lambda is the Right Default for Startups
**Pre-seed to Series A**: Lambda should be your default compute unless you have a reason not to use it.
- Zero cost at idle — you only pay when code runs. A startup with 10K requests/day pays ~$0.20/month.
- No infrastructure to manage during the "build fast, validate hypothesis" phase.
- AWS free tier: 1M requests + 400K GB-seconds/month — most early startups never exceed this.
**The inflection point**: Lambda becomes expensive relative to containers at ~$300-500/month in Lambda spend with predictable, sustained traffic. At that point, a single Fargate task running 24/7 is cheaper.
## Startup Cost Traps
1. **Provisioned Concurrency before you need it**: Costs ~$15/month per provisioned instance even with zero traffic. Don't enable until you have latency SLAs requiring <100ms p99 cold starts AND paying customers who need them.
2. **Memory over-allocation**: Startups often set 1024MB "to be safe." At low traffic this barely matters, but at scale the difference between 256MB and 1024MB is 4x cost. Benchmark with [AWS Lambda Power Tuning](https://github.com/alexcasalboni/aws-lambda-power-tuning) once you have real traffic.
3. **Step Functions standard workflows for high-volume**: Standard Workflows cost $25 per million state transitions. If you're processing events at volume, Express Workflows cost $1 per million (but max 5-min duration). Most startups should start with Standard and switch to Express when the bill surprises them.
4. **VPC-attached Lambda + NAT Gateway**: A NAT Gateway costs $32/month + data processing fees — often more than the Lambda itself for early startups. Use VPC endpoints ($7/month each) for S3 and DynamoDB, or keep Lambda outside the VPC entirely until you need private resource access.
## Counterintuitive Startup Advice
- **Monolith Lambda is fine at your stage.** The "anti-pattern" of one Lambda handling multiple routes via API Gateway is actually optimal for a 1-3 person team. Split functions when: (a) you have different scaling/memory needs per route, or (b) cold starts on a bloated package exceed your latency budget. Don't prematurely decompose.
- **Skip Powertools until you have production traffic.** Structured logging and tracing matter when debugging distributed systems at scale. At pre-product-market-fit, `console.log` and CloudWatch Logs Insights are sufficient. Add Powertools when you have >5 Lambda functions in production.
- **Python or Node.js, period.** Unless your team is exclusively Java/Go developers, the startup hiring pool and example ecosystem for Lambda skews heavily Python/Node. Pick one and standardize. Language choice is a one-way door at the team level.
## When to Graduate from Lambda
| Signal | What to Do |
| ---------------------------------------------------------------- | ------------------------------------------------- |
| Monthly Lambda bill > $500 with predictable traffic | Evaluate ECS Fargate — likely 40-60% cheaper |
| P99 latency >2s due to cold starts on critical path | Add Provisioned Concurrency OR move to containers |
| Functions exceeding 15-min timeout | Move to ECS tasks or Step Functions |
| Team spending >20% of time on Lambda packaging/deployment issues | Consider containers for developer experience |
| Need WebSockets, long-lived connections, or >6MB response bodies | Lambda is architecturally wrong — use containers |
## Credits-Specific Guidance
- Lambda compute is covered by AWS Activate credits. During the credits period, don't optimize Lambda cost — optimize developer velocity instead. Over-provision memory, use Provisioned Concurrency liberally, etc.
- When credits expire, expect Lambda bills to be the first "surprise" because teams never optimized during the free period. Budget 2 weeks for Lambda cost optimization before credits run out.
## ARM64 (Graviton) — Just Do It
20% cheaper, often faster. No config change needed for Python/Node.js. Set `arm64` on every function from day one. The only reason not to: native binary dependencies compiled for x86 (rare for startups).
references/messaging.md
# Messaging — Startup Decision Guide
## Stage-Based Recommendation
### Pre-PMF (Seed / <$1M ARR)
- **Default to SQS Standard.** Don't overthink messaging architecture. A single SQS queue between your API and a worker Lambda covers 90% of early async needs.
- **Skip EventBridge until you have 3+ services producing events.** For 1-2 services, direct SQS/SNS is simpler and cheaper.
- **Don't build event-driven microservices yet.** You'll refactor your domain model 5 times before PMF. Monolith + SQS for background jobs is the right pattern.
### Post-PMF / Growth ($1M-$10M ARR)
- **EventBridge when you have 3+ services that react to the same business events.** The content-based routing eliminates Lambda glue.
- **SNS + SQS fan-out for high-throughput notification patterns** (>10K events/sec).
- **FIFO queues only when you have actual ordering bugs** in production, not as a preventive measure. They cost more and have lower throughput (3,000 msg/sec with batching vs unlimited for Standard).
### Scale ($10M+ ARR)
- EventBridge + Schema Registry for event contracts across teams.
- Consider Kinesis/MSK only for true streaming use cases (>100K events/sec sustained).
## Cost Traps
| Trap | Impact | Fix |
| --------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Short polling SQS | ~345K empty API calls/day per consumer at standard rate | Always `WaitTimeSeconds=20`. Saves ~90% of SQS API costs. |
| SQS FIFO "just to be safe" | 50% more expensive + 3K msg/sec cap (vs unlimited) | Use Standard unless you have a proven ordering bug. Design for idempotency instead. |
| EventBridge for everything | $1.00/million events + complex debugging | SQS direct is $0.40/million for simple point-to-point |
| SNS for point-to-point | Extra hop + cost for single subscriber | Use SQS directly. SNS adds value only at 2+ subscribers. |
| Lambda polling empty queues | Lambda invocations checking SQS with nothing to process | Use SQS event source mapping (free polling) instead of custom pollers |
## Counterintuitive Advice
- **Synchronous is fine at startup scale.** Don't add SQS between your API and database "for decoupling" when you have 10 requests/second. It adds latency, complexity, and debugging difficulty. Add async when you have a specific scaling bottleneck.
- **EventBridge Archives are not a replacement for event sourcing.** The replay is useful for debugging, not for rebuilding state. If you need event sourcing, use DynamoDB Streams or build a proper event store.
- **SQS FIFO's exactly-once is per message-group, not per queue.** If you thought FIFO makes your whole system exactly-once, you misunderstood it. You still need idempotent consumers for Standard OR FIFO.
- **DLQ without alerting is worse than no DLQ.** It gives you false confidence that errors are "handled" when they're actually just accumulating silently. Set up the CloudWatch alarm on DLQ message count ON THE SAME DAY you create the DLQ.
## Decision Shortcuts
**"Should I use messaging here?"**
- Request-response with <1s latency requirement → No, call directly
- Fire-and-forget, no response needed → Yes, SQS
- One event, multiple reactions → Yes, SNS or EventBridge
- Smoothing traffic spikes → Yes, SQS in front of worker
- "Because microservices should be decoupled" → No, that's cargo culting
**"SQS Standard or FIFO?"**
- Can you make your consumer idempotent? → Standard (higher throughput, lower cost)
- Is ordering a regulatory requirement? → FIFO
- Processing the same message twice causes money loss? → FIFO (with deduplication)
- You're not sure → Standard. You can always migrate later.
## When to Graduate
| Trigger | Action |
| ------------------------------------------------------- | -------------------------------------------------------------- |
| Background job takes >29s (API Gateway timeout) | Add SQS + worker Lambda |
| Same event needs to trigger 3+ different actions | SNS fan-out or EventBridge |
| You're writing Lambda "routers" that inspect event type | Switch to EventBridge rules |
| You need cross-account event delivery | EventBridge (cross-account rules) |
| >10K events/sec sustained throughput | SNS+SQS fan-out (EventBridge has soft limits) |
| >100K events/sec sustained | Kinesis or MSK — you've outgrown messaging, you need streaming |
references/migration-apprunner-to-ecs-express.md
# Migration App Runner to ECS Express — Startup-Specific Guidance
## Why This Matters for Startups
App Runner was the "startup-friendly" compute option. It's closing to new customers April 30, 2026. Existing services keep running, but you need a plan.
## Startup Decision: What to Migrate TO
Don't assume ECS Express Mode is the answer. Choose based on your situation:
| Your Situation | Best Target | Why |
| --------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------- |
| Simple API, low traffic, want PaaS simplicity | **ECS Express Mode** | Closest to App Runner experience |
| Spiky traffic, want $0 at idle | **Lambda + API Gateway** | If your app fits Lambda constraints (15 min, stateless) |
| Already considering containers seriously | **ECS Fargate (standard)** | More control than Express Mode, same pricing |
| Source-code deploy (no Dockerfile) | **Lambda** (repackage) or **Express Mode** (containerize first) | Express Mode requires container images |
### The "Do I Even Need to Migrate?" Question
**Existing App Runner services continue to work.** You only MUST migrate if:
- You need to create NEW services (can't after April 2026)
- You want to consolidate on fewer platforms
- App Runner's scaling model (concurrent requests) doesn't fit your workload
**If your App Runner service is stable and you're not creating new ones, deprioritize this migration.** Focus on product, not infrastructure churn.
## Cost Comparison for Startups
| Scenario | App Runner | ECS Express Mode | Lambda |
| --------------------- | ------------------------ | -------------------- | -------- |
| Idle (0 req/min) | ~$5/mo (provisioned min) | $16/mo (ALB minimum) | $0 |
| Light (1 req/sec) | ~$20/mo | ~$30/mo | ~$3/mo |
| Moderate (10 req/sec) | ~$50/mo | ~$60/mo | ~$25/mo |
| Heavy (100 req/sec) | ~$200/mo | ~$180/mo | ~$200/mo |
**Key insight**: ECS Express Mode is MORE expensive than App Runner at low traffic due to the ALB baseline. If cost matters and traffic is light, Lambda might be the better migration target.
## Startup Quick Migration Path
For non-critical services (dev, staging, internal tools):
1. Extract config: `aws apprunner describe-service --service-arn <arn>`
2. Note: image URI, port, env vars, CPU/memory
3. Create Express Mode service with same config
4. Test the `*.ecs.<region>.on.aws` URL
5. Update DNS or upstream references
6. Keep App Runner as rollback for 48 hours, then delete
**Total time**: 2-4 hours for a simple service.
## Startup-Specific Gotchas
| Gotcha | Impact | Mitigation |
| ------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------- |
| ALB is shared across up to 25 services | Good — amortizes $16/mo baseline across services | Migrate all App Runner services to one Express Mode ALB |
| Auto-scaling metric change (requests → CPU) | Bursty traffic may scale differently | Monitor for 48h after cutover; adjust `--scaling-target` |
| No source-code deploy | Must containerize if currently deploying from GitHub source | Write a Dockerfile first (budget 1-2 hours) |
| IAM roles are more complex | App Runner had simpler permissions model | Reuse existing roles — don't create new ones unless needed |
| Health check default differs | App Runner: TCP. Express Mode: HTTP `/ping` | Add a `/ping` endpoint or configure health check path explicitly |
## When to NOT Use Express Mode (Startup Context)
Choose standard ECS Fargate instead if:
- You need fine-grained networking control (specific subnets, custom security groups)
- You want to share an ALB you already manage
- You need sidecar containers (observability agents, proxies)
- You're running >5 services and want central control
Choose Lambda instead if:
- Your app fits Lambda constraints (stateless, <15 min, <10GB memory)
- Traffic is highly variable with long periods of zero requests
- You want $0 baseline cost
- You're willing to handle cold starts (or pay for provisioned concurrency)
references/migration-azure-to-aws.md
# Migration Azure to AWS — Startup-Specific Guidance
## Why Startups Migrate from Azure to AWS
1. **AWS credits** — Activate Accelerate / startup program credits are often larger than Azure equivalents
2. **Team hires** — new engineers know AWS, not Azure
3. **Ecosystem** — most SaaS integrations, tutorials, and community support default to AWS
4. **Specific service** — need Bedrock, DynamoDB, Lambda ecosystem, or other AWS-specific capabilities
## Startup Migration Decision Framework
### Don't Migrate If:
- You have >$50K in remaining Azure credits with no AWS credits
- Your codebase has deep Azure SDK dependencies (>6 months to untangle)
- You're pre-PMF — migration is a distraction from finding product-market fit
- Only reason is "AWS is more popular" — that's not a technical reason
### Do Migrate If:
- AWS credits significantly exceed remaining Azure credits
- Team is growing and candidates know AWS (hiring signal)
- Hitting Azure service limitations your product needs to overcome
- Want to consolidate on one cloud (already using some AWS)
## Startup-Specific Migration Gotchas
### Azure AD (Entra ID) — Skip the Full Migration
Enterprise migrations map Azure AD → IAM Identity Center. Startups should NOT:
- Migrate complex Conditional Access policies (rebuild from scratch with simpler IAM)
- Migrate Azure AD B2C to Cognito (re-auth your 50 users, it's faster than migrating)
- Worry about PIM → IAM equivalent (you don't need PIM at 5 engineers)
**Startup approach**: Set up IAM Identity Center fresh. Re-invite your 3-10 team members. Total time: 1 hour.
### Cosmos DB — Don't Over-Think It
Enterprise guide says "Cosmos DB maps to 4+ services depending on API." For startups:
- If you use Cosmos DB Core (SQL API) → DynamoDB. Just port the queries.
- If you have <10GB of data → export JSON, import to DynamoDB. Done in a day.
- If you use MongoDB API → DocumentDB OR just DynamoDB (simpler, cheaper at startup scale)
### Azure App Service → What to Choose on AWS
| Your Situation | Choose | Why NOT the complex option |
| -------------------------------- | ------------------------------ | ---------------------------------- |
| Simple web app, <1K daily users | ECS Express Mode | Don't need full ECS/EKS complexity |
| API with background jobs | Lambda + SQS | Don't need always-on compute |
| Need deployment slots equivalent | ECS with CodeDeploy blue/green | Built-in blue/green support |
| Team has container experience | ECS Fargate | Don't need Kubernetes |
### Azure Functions → Lambda
Straightforward except:
- **Durable Functions** → Step Functions (different programming model — budget 1-2 weeks to rewrite orchestrations)
- **Bindings** → Replace with explicit SDK calls. Budget 1-2 days per function with complex bindings.
- **Timer triggers** → EventBridge Scheduler + Lambda (easy, 30 min per function)
## Startup Migration Execution Plan
### The "Weekend Migration" (< 10 Azure resources, < 5GB data)
1. Friday: Set up AWS account, IAM Identity Center, basic networking
2. Saturday: Deploy compute (Lambda/ECS Express Mode/Fargate), migrate database (export/import)
3. Sunday: DNS cutover, smoke test, keep Azure running for 1 week as rollback
4. Following Friday: Delete Azure resources
### The "Sprint Migration" (10-50 Azure resources, production traffic)
1. Week 1: Set up AWS foundation (accounts, networking, CI/CD)
2. Week 2: Deploy and validate in AWS (parallel running)
3. Week 3: Gradual traffic shift (Route 53 weighted routing)
4. Week 4: Decommission Azure (keep backups for 30 days)
## Cost Comparison Traps
| Azure Feature | Looks Equivalent To | But Watch Out For |
| --------------------------- | ------------------------- | ------------------------------------------------------------------------------------- |
| Azure App Service free tier | ECS Express Mode / Lambda | App Service F1 free tier is more generous — AWS has no equivalent free container tier |
| Cosmos DB serverless | DynamoDB on-demand | Cosmos RU pricing vs DynamoDB WCU/RCU doesn't map 1:1 — benchmark first |
| Azure SQL Basic ($5/mo) | RDS t4g.micro ($12/mo) | AWS cheapest RDS is more expensive than Azure's cheapest SQL |
| Azure Functions (1M free) | Lambda (1M free) | Equivalent — Lambda is slightly more generous on compute-seconds |
references/mlops.md
# MLOps — Startup Decision Guide
## The #1 Mistake: Over-Engineering ML Infrastructure
Most startups don't need MLOps platforms until they have a model in production serving real users. The sequence matters:
```
WRONG: Build SageMaker Pipeline → Train model → Find product-market fit
RIGHT: Notebook experiment → Prove value to users → Productionize with minimal infra → Add MLOps as scale demands
```
## Platform Selection by Stage
| Stage | Monthly ML spend | Recommendation | What you're skipping (intentionally) |
| --------- | ---------------- | ------------------------------------------------------------------------------ | ------------------------------------------- |
| Pre-seed | $0-200 | SageMaker notebooks + training jobs. No pipelines, no registry, no monitoring. | Everything except train → deploy |
| Seed | $200-2K | Add Model Registry + basic monitoring. Still no pipelines. | Automated retraining, CI/CD for models |
| Series A | $2K-20K | SageMaker Pipelines + MLflow tracking. Automate retraining. | Multi-environment promotion, shadow testing |
| Series B+ | $20K+ | Full MLOps: pipelines, registry, monitoring, shadow testing, multi-account | Nothing — you need it all now |
## Cost Traps Specific to Startups
### The Real-Time Endpoint Trap
**A single ml.m5.large real-time endpoint costs ~$100/month running 24/7, even with zero traffic.**
| Daily inference requests | Best deployment option | Monthly cost |
| ------------------------ | ------------------------------------------------------------ | ------------ |
| < 100 | Lambda with model loaded from S3 | $1-5 |
| 100-10,000 | SageMaker Serverless Inference | $5-50 |
| 10K-100K | Real-time endpoint with aggressive auto-scaling (scale to 1) | $100-500 |
| 100K+ | Real-time endpoint, right-sized with Inference Recommender | $500+ |
**When to graduate from Serverless to Real-time:**
- p99 latency requirement < 500ms (Serverless cold starts add 1-5s)
- Model size > 6GB (Serverless max memory: 6GB)
- Sustained traffic > 10 req/sec (Serverless concurrency limit: 200)
### Spot Training: Free Money You're Leaving on the Table
**60-90% savings with one flag.** Set `use_spot_instances=True` on every training job. SageMaker handles interruptions automatically with checkpointing. The only exception is a truly time-critical training run (which you almost certainly don't have at seed stage).
### Trainium/Inferentia: The 50% Savings Most Startups Ignore
If your model is PyTorch or TensorFlow (vast majority of startups): check Neuron compatibility first. ml.trn1 for training and ml.inf2 for inference deliver 50%+ savings. Most startups default to GPU instances without checking because the docs seem complex — but the actual code change is minimal (Neuron SDK compiler handles it).
## Counterintuitive Advice
### Don't Use SageMaker Pipelines Until You Retrain Monthly
If you retrain quarterly or less, a manual notebook-driven workflow with Model Registry is fine. Pipelines add:
- Maintenance overhead (pipeline definitions are code you maintain)
- Debugging complexity (pipeline failures are harder to diagnose than notebook failures)
- Cost (pipeline execution has its own charges)
**Trigger to add pipelines**: You're retraining more than once per month AND manual retraining takes > 2 hours of engineer time.
### Skip Model Monitoring Until You Have Baseline Drift Data
Model Monitor requires a baseline created from training data. If you don't have 2+ weeks of production inference data to compare against, monitoring will generate noise (false positives) and waste your time.
**Trigger to add monitoring**: Model has been in production for 30+ days AND you have a hypothesis about what drift looks like for your data.
### MLflow vs SageMaker Experiments: Pick One, Don't Both
Startups that use both create confusion about "which is the source of truth." Decision:
- **New to ML, all-in on AWS**: SageMaker Experiments (tighter integration, less setup)
- **Existing MLflow muscle memory OR multi-cloud plans**: Managed MLflow on SageMaker
- **Never both.** The sync between them is imperfect and creates confusion.
## Credits-Specific Guidance
- SageMaker training jobs, endpoints, and notebooks are all covered by AWS Activate credits
- **Don't buy SageMaker Savings Plans with credits.** You don't have enough usage history to commit. Savings Plans lock you into $/hour commitments that outlast your credits.
- Spot Training stacks with credits — you burn credits at the Spot rate (60-90% less), making credits last 2-3x longer for training workloads
- **Bedrock fine-tuning is credit-eligible** — if you're choosing between self-managed SageMaker training and Bedrock fine-tuning for a foundation model, Bedrock fine-tuning is simpler AND uses credits
## When to Skip SageMaker Entirely
| Scenario | Better alternative | Why |
| -------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------ |
| Only using pre-trained models (no custom training) | Bedrock for LLMs, Rekognition/Comprehend for vision/NLP | Fully managed, no infrastructure, pay-per-request |
| < 50 inferences/day, model < 500MB | Lambda + S3 model loading | Truly scales to zero, simplest possible deployment |
| Team is Kubernetes-native, already running EKS | KServe on EKS | Leverage existing expertise, avoid two orchestration systems |
| Simple tabular ML (classification, regression) | SageMaker Autopilot / Canvas | No-code/low-code, handles the entire ML lifecycle |
## Anti-Patterns (Startup-Specific)
- **Building a "platform" before shipping a model.** If your first month is spent on pipeline infrastructure and nobody has deployed a model to production, priorities are wrong. Ship first, platformize second.
- **Real-time endpoints for batch scoring.** A startup doing nightly customer churn predictions on 10K users doesn't need an always-on endpoint. Batch Transform runs for 5 minutes and costs $0.50.
- **On-Demand training "because credits cover it."** Credits are finite. Spot Training at 70% savings makes your credits last 3x longer. Always use Spot.
- **Model Registry from day one with 1 model.** Registry adds value at 3+ model versions in production. With 1 model and no A/B testing, it's ceremony with no benefit.
- **Multi-account MLOps (dev/staging/prod) at seed stage.** You have one engineer doing ML. One account is fine. Add account separation when you have compliance requirements or 3+ ML engineers.
references/networking.md
# Networking — Startup Decision Guide
## Stage-Based Recommendation
### Pre-PMF (Seed / <$1M ARR)
- **Single NAT Gateway is fine.** The HA argument ($32/month per NAT Gateway × 3 AZs = $97/month) doesn't matter when your revenue is zero and downtime during an AZ failure costs you nothing in SLA penalties.
- **2 AZs, not 3.** You don't need 99.99% availability. 2 AZs gives you 99.95% and costs 33% less in NAT Gateways and other AZ-distributed resources.
- **Skip VPC entirely if you can.** Lambda, DynamoDB, S3, API Gateway — all work without VPC. Only add VPC when you need RDS, ElastiCache, ECS, or EC2.
- **If you must VPC:** Use the CDK/CF starter template with /16 CIDR, 2 AZs, 1 NAT Gateway. Don't bikeshed on CIDR planning until you need multi-VPC.
### Post-PMF / Growth ($1M-$10M ARR)
- Expand to 3 AZs when you have SLA commitments to customers.
- Add NAT Gateway per AZ when a single AZ failure would breach your SLA.
- Start planning CIDR allocation only when you need a second VPC (staging/prod split or microservice isolation).
### Scale ($10M+ ARR)
- Transit Gateway when you hit 3+ VPCs.
- Centralized egress through shared services VPC.
- This is when you hire a network engineer.
## Cost Traps
| Trap | Impact | Fix |
| ----------------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NAT Gateway data processing | $0.045/GB — invisible tax on ALL traffic from private subnets to internet or AWS services | Add S3 + DynamoDB gateway endpoints (free). Add interface endpoints for services with >1GB/month traffic ($7.20/month per endpoint per AZ vs $0.045/GB via NAT) |
| 3 NAT Gateways in dev/staging | $97/month × number of non-prod environments | 1 NAT Gateway for all non-prod. Accept the AZ risk. |
| VPC endpoints "just in case" | $7.20/month per endpoint per AZ — 10 endpoints in 3 AZs = $216/month | Only add interface endpoints when the NAT Gateway data processing cost for that service exceeds the endpoint cost. Breakeven: ~160GB/month per service. |
| Unused Elastic IPs | $3.60/month per unattached EIP (post-Feb 2024: $3.60/month for ALL public IPs including attached) | Audit monthly. Each public IPv4 costs money whether used or not. |
| VPC for serverless workloads | NAT Gateway cost for Lambda/ECS calling AWS services | Use VPC endpoints or keep serverless outside VPC entirely |
## Counterintuitive Advice
- **Don't follow the "3 AZs, 3 tiers" best practice until Series B.** That's 9 subnets minimum. For a seed-stage startup, 2 AZs with public + private subnets (4 subnets total) is correct. You can add the third AZ in 30 minutes when you need it.
- **VPC endpoints have a breakeven point.** An interface endpoint costs $7.20/month/AZ. NAT Gateway processes data at $0.045/GB. If a service sends <160GB/month through NAT, the endpoint costs MORE than the NAT data processing. Only add interface endpoints when the math works (except for security-isolated subnets where there's no NAT alternative).
- **NAT Gateway is your biggest hidden cost.** A startup running ECS in private subnets pulling Docker images from ECR can easily spend $50-100/month just on NAT data processing for image pulls alone. Add ECR VPC endpoints early.
- **"No VPC" is a valid architecture.** API Gateway → Lambda → DynamoDB with IAM auth requires zero networking. Many startups don't need VPC until they add RDS or Redis.
## VPC Endpoint Decision Framework
Add these FREE endpoints always (zero cost):
- S3 Gateway Endpoint
- DynamoDB Gateway Endpoint
Add these PAID endpoints when math justifies (each $7.20/month/AZ):
| Endpoint | Add when... |
| ----------------- | -------------------------------------------------------------------------------------- |
| ecr.api + ecr.dkr | Running containers in private subnets (saves ~$5-20/month in NAT data for image pulls) |
| logs | Sending >160GB/month of logs from private subnets |
| secretsmanager | Running in isolated subnets (no NAT alternative) |
| sts | Running in isolated subnets |
## When to Graduate from Simple to Complex Networking
| Trigger | Action |
| ------------------------------- | ------------------------------------------------ |
| First SLA commitment (99.9%) | Add 3rd AZ + NAT per AZ |
| NAT data processing >$100/month | Add interface endpoints for top traffic services |
| 3+ VPCs | Transit Gateway |
| SOC2/HIPAA requirement | Isolated subnets + VPC Flow Logs + all endpoints |
| Multi-region requirement | CIDR planning, Transit Gateway Inter-Region |
## Key Design Decisions
### Security Groups vs NACLs
- **Security groups are your primary network control.** They're stateful, allow-only, and evaluated together.
- **NACLs are defense-in-depth only.** Stateless, ordered rules, allow+deny — harder to manage and debug.
- Reference security groups by ID (not CIDR) for inter-resource traffic. Chain them: ALB-sg → App-sg → DB-sg.
- One security group per logical role. Never use 0.0.0.0/0 on port 22/3389 in production — use Systems Manager Session Manager.
### VPC Peering (for 2-3 VPCs before Transit Gateway)
- Point-to-point only, not transitive (A↔B and B↔C does NOT mean A↔C)
- CIDRs must not overlap — plan allocation upfront
- Works cross-region and cross-account
### Route53
- **Public hosted zone** for internet-facing DNS. NS records must be at your registrar.
- **Private hosted zone** for internal service discovery (associated with VPCs, not resolvable from internet).
- Always attach health checks to failover and latency routing records.
- Use Route53 + private hosted zones instead of hardcoding IPs. IPs change; DNS names persist.
references/observability.md
# Observability — Startup Decision Guide
## Stage-Based Recommendation
### Pre-PMF (Seed / <$1M ARR)
- **CloudWatch only. No Datadog, no New Relic, no Grafana Cloud.** Third-party observability tools cost $15-50/host/month and grow linearly. At this stage, CloudWatch + Embedded Metric Format is sufficient and covered by AWS credits.
- **3 metrics, 3 alarms, 1 dashboard.** Error rate, p99 latency, and request count. That's it. You don't need 47 dashboards for 1 service.
- **Log retention: 7 days dev, 30 days prod.** The default "never expire" will silently accumulate $50-200/month in log storage within 6 months.
- **Skip X-Ray until you have 3+ services.** Tracing a monolith tells you nothing useful. Tracing across service boundaries is where it helps.
### Post-PMF / Growth ($1M-$10M ARR)
- Add X-Ray or OpenTelemetry when you have 3+ services and debugging cross-service issues takes >1 hour.
- Consider Datadog/New Relic ONLY if CloudWatch Logs Insights becomes too slow for your team's debugging workflow. The convenience costs 5-10x.
- Increase log retention to 90 days prod when you have compliance requirements.
- Add anomaly detection on request count and latency (needs 2 weeks of baseline data).
### Scale ($10M+ ARR)
- OpenTelemetry for vendor-neutral instrumentation.
- Centralized observability platform decision (CloudWatch vs third-party based on team size and budget).
- This is when the Datadog bill becomes justified ($50K+/year but saves engineering time at 20+ engineers).
## Cost Traps
| Trap | Impact | Fix |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Log retention: never expire (default) | $0.03/GB/month storage — grows forever. 100GB/month of logs = $36/year in year 1, $72 in year 2, etc. | Set retention policy on creation. 30 days prod. |
| Custom metrics via PutMetricData | $0.30/metric/month + $0.01/1000 API calls | Use Embedded Metric Format in Lambda — creates metrics from logs at zero API cost |
| High-cardinality custom metrics | Dimensions multiply: 100 users × 10 endpoints = 1000 metrics = $300/month | Use Logs Insights for high-cardinality analysis, reserve metrics for low-cardinality aggregates |
| X-Ray 100% sampling in prod | $5.00/million traces recorded + storage | Sample: 1/sec + 5% additional. For startups this is usually enough. |
| Datadog before $5M ARR | $15-50/host/month + $1.70/million log events. 10 containers + logs = $500-2000/month easily | CloudWatch is included in AWS credits. Switch when team size (>10 engineers) justifies the UX premium. |
| CloudWatch Dashboards | $3/dashboard/month — sounds small, proliferates fast | 1 dashboard per service max. Use automatic dashboards for exploration. |
| Contributor Insights | $0.02/rule/100 log events evaluated. High-volume logs = surprise bill | Enable only on specific log groups for incident investigation, disable after |
## Counterintuitive Advice
- **Fewer alarms = faster response.** 3 well-chosen alarms that always require action beat 30 alarms that are "probably fine." Every alarm should have a runbook. If you can't write the runbook, delete the alarm.
- **Alarm on symptoms, not causes.** "Error rate >1%" tells you something is broken. "CPU >80%" tells you... maybe nothing is wrong. Users feel symptoms, not causes.
- **CloudWatch Logs Insights is underrated.** Startups reach for Elasticsearch/Datadog because they assume CloudWatch is limited. Logs Insights with structured JSON logging handles 95% of debugging queries for teams under 20 engineers.
- **Embedded Metric Format is the single most important observability feature for Lambda-based startups.** It turns log lines into metrics at zero additional cost. You get custom metrics for free.
- **Don't build a "golden dashboard" until you've been in production for 3 months.** You'll build the wrong dashboard on day 1 because you don't know what fails yet. Start with the 3 basics and add panels as you learn from incidents.
## Minimum Viable Observability
### Seed Stage Checklist
- [ ] Structured JSON logging (enables Logs Insights queries)
- [ ] Log retention set on all log groups (7d dev, 30d prod)
- [ ] 3 alarms: error rate, p99 latency, 5xx count (SNS → email/Slack)
- [ ] 1 dashboard: request count, error rate, latency p99
- [ ] Lambda: use Embedded Metric Format for custom metrics (free)
- [ ] CloudTrail enabled (default trail — free for management events)
### Post-PMF Additions
- [ ] X-Ray sampling on API Gateway + Lambda (1/sec + 5%)
- [ ] Anomaly detection on request count (catches traffic drops = outage)
- [ ] DLQ monitoring alarms (ApproximateNumberOfMessagesVisible > 0)
- [ ] Composite alarm for service health (error rate AND latency breach)
- [ ] Log retention 90 days in prod
## When to Graduate
| Trigger | Action |
| -------------------------------------------------------- | ------------------------------------------------------------------- |
| First customer-facing outage you can't diagnose in 30min | Add X-Ray tracing |
| Debugging takes >1hr regularly | Increase log retention, add structured fields |
| 3+ services with cross-service calls | Distributed tracing (X-Ray or OTEL) |
| 10+ engineers needing observability | Evaluate Datadog/New Relic (UX justifies cost) |
| SOC2 audit | 90-day log retention, CloudTrail in all accounts |
| Monthly observability bill >$500 on CloudWatch | Audit: log retention, custom metrics cardinality, unused dashboards |
## Credits Consideration
CloudWatch costs (logs, metrics, dashboards, X-Ray) are covered by AWS Activate credits. While you have credits:
- Don't optimize log retention aggressively — keep 90 days everywhere for debugging convenience
- Use X-Ray at higher sampling rates to build intuition about your system
- Create dashboards freely for learning
Set a calendar reminder 6 months before credits expire to implement cost-optimized retention policies.
references/rapid-patterns.md
# Rapid Patterns
Opinionated architecture choices for startups. These differ from standard AWS guidance.
---
## Key Opinionated Choices
- **API Gateway HTTP API over REST API**: $1/M requests vs $3.50/M, lower latency. REST API only if you need request validation, caching, or usage plans.
- **Skip OpenSearch Serverless for RAG**: ~$700/month minimum. Use Bedrock Knowledge Base with managed vector store instead.
- **Aurora Serverless v2 minimum is $43/month** (0.5 ACU floor) — not truly zero-scale. DynamoDB is $0 at rest.
- **Fargate over Lambda for multi-tenant SaaS**: containers give more flexibility for tenant routing, connection pooling, long-running requests.
- **Presigned S3 URLs for uploads**: Skip Lambda entirely for large file uploads from mobile/web clients.
---
## Pattern Graduation Triggers
These are the specific signals to move from the rapid/cheap pattern to something more robust:
| Signal | Action |
| ---------------------------------------- | --------------------------------------------------- |
| Lambda hitting 15-min timeout | Move that workload to Fargate |
| >1000 concurrent Lambda executions | Consider Fargate for steady-state traffic |
| DynamoDB costs > $100/month | Evaluate access patterns, consider provisioned mode |
| Need complex SQL queries | Add Aurora Serverless v2 alongside DynamoDB |
| Multiple teams deploying to same service | Split into separate services with clear APIs |
| Customers asking about SLAs | Add multi-AZ, health checks, monitoring |
| >100GB of analytics data | Graduate from Athena+S3 to a data warehouse |
| >10 tenants with isolation requirements | Graduate from Lambda+DynamoDB to Fargate+Aurora |
---
## AI-Powered App: Cost Traps
- **Bedrock Knowledge Base with OpenSearch Serverless** = ~$700/month minimum. Use Bedrock's managed vector store instead.
- Start with **Nova Micro** for classification/routing, **Nova Lite** for generation — cheapest Bedrock models.
- Store conversation history in DynamoDB, not in-memory (Lambda is stateless) and not S3 (too slow for chat).
- Don't build an agent unless you need tool use — `InvokeModel` directly is simpler and cheaper.
references/rds-aurora.md
# RDS & Aurora — Startup-Specific Guidance
## The Startup Database Decision
**PostgreSQL on Aurora Serverless v2 is the default database for startups.** It gives you:
- Familiar SQL with full query flexibility (critical when access patterns are unknown)
- Scale-to-near-zero (0.5 ACU minimum = ~$44/month)
- Auto-scaling during traffic spikes without capacity planning
- No DBA required until Series B
**Use plain RDS (not Aurora) when:**
- Budget is extremely tight — `db.t4g.micro` RDS PostgreSQL costs ~$12/month vs Aurora's $44/month minimum
- You need Oracle or SQL Server (Aurora doesn't support these)
- Your database will stay small (<50GB) with low connection counts
## Startup Cost Traps
1. **Aurora Serverless v2 minimum ACU cost**: Even "scaled to zero" isn't zero — minimum is 0.5 ACU = ~$44/month. For a side project or internal tool, plain RDS `db.t4g.micro` at $12/month is 4x cheaper. Use Aurora Serverless v2 when the auto-scaling justifies the minimum.
2. **Multi-AZ on day one**: Multi-AZ doubles your database cost. At pre-PMF with no revenue, single-AZ + automated daily snapshots is an acceptable risk. Your "HA plan" is: restore from snapshot (10-30 min downtime). Add Multi-AZ when you have paying customers with uptime expectations.
3. **RDS Proxy when you don't need it**: $18/month minimum per proxy. Only needed for Lambda→RDS connections (Lambda's connection storm problem). If your app uses containers with connection pooling (HikariCP, pgBouncer), skip RDS Proxy entirely.
4. **Oversized instances "for headroom"**: Startups provision `db.r6g.large` ($140/month) when `db.t4g.medium` ($48/month) with 2 vCPU/4GB handles their workload fine. Start with the smallest `t4g` class that has enough memory for your working set. Upsize takes <10 minutes with minimal downtime.
5. **Read replicas before you need them**: Each Aurora read replica adds ~$44/month minimum. Don't add replicas until: (a) you've confirmed reads are the bottleneck via Performance Insights, and (b) your read traffic exceeds what the writer can handle. Most startups need 0 read replicas until post-Series A.
6. **Snapshot retention at 35 days**: Default is 7 days, but teams set 35 days "for safety." At 100GB database, that's ~$23/month in backup storage vs ~$5/month for 7 days. Right-size retention to your actual compliance needs.
## Stage-Specific Recommendations
### Pre-PMF (minimal spend, maximum flexibility)
- **RDS PostgreSQL `db.t4g.micro`** (~$12/month) OR **Aurora Serverless v2** (0.5 ACU, ~$44/month)
- Single-AZ, automated daily snapshots
- `gp3` storage (20GB minimum, auto-extends)
- No read replicas, no RDS Proxy
- Password in Secrets Manager with `--manage-master-user-password`
- Total cost: $12-50/month
### Post-PMF / Series A (real users, need reliability)
- **Aurora Serverless v2** with 0.5-8 ACU range (handles spikes without pre-provisioning)
- Enable Multi-AZ (add one reader in a second AZ — doubles as HA AND read scaling)
- Enable Performance Insights (free tier covers 7 days retention)
- Add RDS Proxy only if using Lambda for API handlers
- Enable deletion protection
- Total cost: $100-300/month
### Scale (Series B+, >$500/month database)
- Evaluate Aurora Provisioned vs Serverless v2 — provisioned is cheaper for sustained high load
- Aurora Global Database if you need multi-region reads or DR
- Blue/Green deployments for zero-downtime major version upgrades
- Consider Reserved Instances for Aurora provisioned (1-year, up to 30% savings)
## Counterintuitive Startup Advice
- **Start with RDS, not Aurora.** Aurora's $44/month minimum seems trivial, but at pre-PMF you might have 5 services each needing a database. 5 × $44 = $220/month. 5 × RDS `db.t4g.micro` = $60/month. Migrate to Aurora when a specific database needs auto-scaling storage or high availability.
- **PostgreSQL, always PostgreSQL.** Even if your team knows MySQL better. PostgreSQL has: better JSON support (replace MongoDB), full-text search (replace Elasticsearch for simple cases), PostGIS (location queries), and a richer extension ecosystem. This flexibility reduces the number of databases you need.
- **Single-AZ is fine until you have SLAs.** The "always use Multi-AZ in production" guidance assumes production means "paying customers with contractual uptime." If your production means "100 beta users who'll understand 10 minutes of downtime," save the money.
- **Connection pooling in your app, not RDS Proxy.** PgBouncer sidecar or built-in pooling (HikariCP for Java, Prisma for Node.js) is free and runs co-located with your app. RDS Proxy's value is specifically for Lambda's thousands-of-ephemeral-connections problem.
## When to Evaluate Alternatives
| Signal | Direction |
| ---------------------------------------------------------- | ------------------------------------------------------ |
| Single table with >10K writes/sec, simple key-value access | DynamoDB for that table |
| Need sub-10ms reads on hot data | DynamoDB or ElastiCache in front of Aurora |
| Full-text search beyond PostgreSQL's capabilities | OpenSearch for search, keep Aurora as source of truth |
| Time-series data (metrics, IoT) growing unbounded | Timestream or InfluxDB |
| Monthly database cost > $2K, mostly reads | Consider read replicas + Aurora Global if multi-region |
## Credits-Specific Guidance
- RDS/Aurora instance hours are covered by credits. During credits: use Aurora Serverless v2 with a generous ACU range — let it auto-scale without worrying about cost.
- **Critical warning**: when credits expire, Aurora Serverless v2 with a 0.5-64 ACU range can surprise you with a $500+ first bill if it scaled up during a traffic spike. Set `max ACU` conservatively (4-8 ACU) unless you know your peak load.
- Multi-AZ costs double — enable during credits to test failover behavior, but be aware it doubles your post-credits cost.
- Snapshot storage accumulates outside of instance costs. Clean up manual snapshots before credits expire.
references/s3.md
# S3 — Startup-Specific Guidance
## Why S3 Rarely Needs Startup-Specific Advice
S3 is the one AWS service where the standard best practices apply at every scale. It costs nearly nothing at startup volumes, has no fixed monthly fee, and scales infinitely. There's no "startup vs enterprise" decision to make.
**However, there are a few traps and decisions that disproportionately affect startups:**
## Startup Cost Traps
1. **Data transfer egress is the hidden S3 cost**: Storage is cheap ($0.023/GB-month for Standard). But serving files directly from S3 to the internet costs $0.09/GB. A startup serving 1TB/month of user-uploaded images pays $90/month in transfer. Put CloudFront in front ($0.085/GB, lower at volume + caching reduces origin requests dramatically). Break-even is almost immediate.
2. **Incomplete multipart uploads**: Abandoned multipart uploads are invisible but accumulate storage costs. A startup doing video uploads that fail mid-upload can accumulate GBs of orphaned parts. **Always add a lifecycle rule: abort incomplete multipart uploads after 7 days.** This should be on every bucket from day one.
3. **Intelligent-Tiering monitoring fee**: $0.0025 per 1,000 objects/month. Negligible for most startups, but if you store millions of tiny objects (log lines, events), the monitoring fee can exceed the storage savings. Use Standard for high-frequency small objects; Intelligent-Tiering for larger objects with unknown access patterns.
4. **Cross-region replication "for safety"**: Replication doubles your storage cost AND charges for PUT requests + data transfer. At pre-Series A, single-region S3 with versioning enabled is sufficient. S3 has 99.999999999% durability within a single region. You don't need replication until you have compliance requirements or need cross-region latency.
5. **Versioning without lifecycle rules**: Versioning keeps every version of every object. Without noncurrent version expiration, storage grows unbounded. Rule: expire noncurrent versions after 30 days for non-compliance buckets.
## Stage-Specific Decisions
### Pre-PMF
- **Storage class: Standard.** Don't overthink it. At <100GB, the cost difference between storage classes is dollars.
- Enable versioning on any bucket with user data (protection against accidental deletes)
- Add lifecycle rule: abort incomplete multipart uploads after 7 days
- Serve user-facing assets through CloudFront from day one (performance + cost savings)
### Post-PMF (100GB-10TB)
- Switch to **Intelligent-Tiering** for data with unpredictable access (uploaded content, processed files)
- Add **noncurrent version expiration** (30 days for most, 90 for important data)
- Use **S3 Express One Zone** only if you need single-digit-ms latency for hot data access from EC2 (rare for most startups)
### Scale (>10TB)
- Lifecycle transitions: Standard → Standard-IA after 30 days → Glacier after 90 days for archival data
- S3 Storage Lens for visibility into what's costing you money
- Consider S3 Access Points if multiple teams/apps share buckets
## Counterintuitive Startup Advice
- **Don't use S3 presigned URLs for your MVP auth.** It's tempting to generate presigned URLs and skip building a file serving layer. But presigned URLs can't be revoked, have fixed expiry, and leak through browser history/logs. Use CloudFront with signed cookies/URLs backed by your auth system for user-facing content. Presigned URLs are fine for temporary upload targets.
- **One bucket per concern, not one bucket per entity.** Startups either create too many buckets (one per user? one per feature?) or too few (one bucket for everything). Right-size: `uploads`, `processed-media`, `backups`, `logs` — 3-5 buckets for most early-stage products.
- **S3 event notifications → Lambda is fine for your scale.** Don't build a Kinesis pipeline for image processing at 100 uploads/day. S3 → Lambda → process and write back. Graduate to Step Functions or EventBridge when you need retry logic or multi-step workflows.
## Credits-Specific Guidance
- S3 storage and request costs are covered by credits. During credits: don't optimize storage classes — use Standard everywhere for simplicity.
- **Watch out**: S3 data transfer OUT is the cost most likely to spike unexpectedly during the credits period (video streaming, large file downloads). This is covered by credits but burns them faster than expected.
- When credits expire: the first S3 bill is usually a non-event (<$50) for most startups unless you're serving large files directly to users. The surprise comes from data transfer, not storage.
references/security-review.md
# Security Review — Startup-Specific Guidance
## Startup Security Tiers
Don't apply enterprise security to a pre-seed startup. Apply the RIGHT security for the stage:
### Tier 1: Non-Negotiable (All Stages, Day 1)
These take <1 hour combined and prevent company-ending events:
| Control | Why It's Non-Negotiable | Effort |
| -------------------------------------- | -------------------------------------------------------------- | ------------------------ |
| S3 Block Public Access (account-level) | Public data breach = death | 2 min |
| Root account MFA | Account takeover = everything lost | 5 min |
| No access keys in source code | Leaked keys = crypto mining bills + data breach | 10 min (use git-secrets) |
| Database backups enabled | Data loss = start over | 5 min (usually default) |
| Budget alert at ceiling + 50% | Surprise bill eats runway | 10 min |
| TLS on all public endpoints | API Gateway/CloudFront/ALB default to HTTPS — don't disable it | 0 min |
### Tier 2: First Paying Customer
| Control | Why Now | Effort |
| ------------------------------------- | ------------------------------------------------ | -------------------------- |
| IAM Identity Center (not IAM users) | Audit trail, no shared credentials | 1-2 hours |
| Encryption at rest on databases | Customer data protection, contractual | Default on modern services |
| VPC for datastores (RDS, ElastiCache) | Network isolation for sensitive data | 30 min if not already |
| CloudTrail (default trail) | Audit log — already on by default, DON'T disable | 0 min |
| Secrets in SSM/Secrets Manager | No .env files, no hardcoded passwords | 1-2 hours migration |
### Tier 3: Enterprise Customer / SOC2 Prep
| Control | Why Now | Effort |
| ----------------------------- | ------------------------------------------------ | -------------------------- |
| GuardDuty | Threat detection, SOC2 expects it | 5 min to enable, $15-30/mo |
| Security Hub | Centralized findings, auditor-friendly | 15 min, cost varies |
| Config rules | Drift detection, compliance evidence | Hours to tune properly |
| VPC Flow Logs | Network audit trail | 5 min, $0.50/GB |
| Custom KMS keys with rotation | Customer-managed encryption, compliance evidence | 30 min per key |
| SCPs (multi-account) | Prevent lateral damage | Hours to design properly |
### Tier 4: Series B+ / Regulated Industry
Full enterprise security stack: Security Hub, custom Config rules, AWS Firewall Manager, automated remediation, security incident response playbook, penetration testing, etc.
## Startup Security Anti-Patterns
| Anti-Pattern | Why Startups Do It | What to Do Instead |
| ------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Skip ALL security | "We'll add it later" | Apply Tier 1. It takes 30 minutes. No excuses. |
| Apply ALL security | "We need to be enterprise-ready" | You'll spend 2 weeks on security tooling nobody asked for. Apply your tier. |
| `AdministratorAccess` for app roles | "We'll scope it later" | At minimum, scope to the services you use. `s3:*`, `dynamodb:*` is bad but survivable. `*:*` is never ok. |
| Shared IAM users | "We only have 2 people" | Use IAM Identity Center. It's free. Shared creds = no audit trail. |
| Security groups: all traffic from 0.0.0.0/0 | "It works" | Allow only the ports your app uses. Takes 5 minutes. |
| No encryption because "it's just dev" | Dev data often mirrors production | All modern AWS services default to encryption. Don't disable it. |
## The "First Enterprise Deal" Security Checklist
When your first enterprise customer sends a security questionnaire, you need these ready:
```
□ Data encrypted at rest (all datastores)
□ Data encrypted in transit (TLS everywhere)
□ Access logging (CloudTrail enabled)
□ No shared credentials (IAM Identity Center or per-engineer roles)
□ Backup and recovery tested (restore a DB backup once)
□ Incident response plan (even a 1-page doc counts)
□ Penetration test completed (use AWS-approved vendor)
□ SOC2 Type I started (if SaaS) — takes 3-6 months
```
**Start SOC2 3-6 months BEFORE you think you'll need it.** Every startup we've seen regrets not starting earlier.
## IaC Security Checklist
When reviewing infrastructure code (CDK, Terraform, CloudFormation):
### IAM
- [ ] No `*` in Action or Resource (unless scoped with conditions)
- [ ] No inline policies on users — use roles and groups
- [ ] Cross-account access uses external ID
- [ ] Lambda execution roles scoped to specific log groups
### Networking
- [ ] No security groups with 0.0.0.0/0 on non-HTTP(S) ports
- [ ] Private subnets for databases and internal services
- [ ] NACLs as defense-in-depth, not primary control
### Data
- [ ] Encryption at rest enabled (S3, RDS, EBS, DynamoDB)
- [ ] S3 buckets: Block Public Access enabled, no public ACLs
- [ ] RDS: no public accessibility
- [ ] Secrets in Secrets Manager or SSM Parameter Store, never in code
## Cost of Security Controls
| Control | Monthly Cost | Startup Stage to Add |
| ------------------------ | --------------------------------- | ------------------------------------ |
| S3 Block Public Access | $0 | Day 1 |
| IAM Identity Center | $0 | First hire |
| CloudTrail (default) | $0 (first copy free) | Day 1 (already on) |
| AWS-managed encryption | $0 | Day 1 (already on for most services) |
| GuardDuty | $15-30/mo typical for startups | First enterprise customer |
| Security Hub | $5-20/mo typical | SOC2 prep |
| Config rules (basic set) | $10-50/mo | SOC2 prep |
| VPC Flow Logs | $0.50/GB stored | Enterprise customer requirement |
| WAF | $5/mo + $1/rule + request charges | Public API under attack |
references/stage-frameworks.md
# Stage Frameworks
## Pre-Revenue (1-2 founders, no users)
**Principle**: Ship something users can touch this week. Nothing else matters.
**Hard constraints**:
- Zero server management — Lambda or ECS Express Mode only
- Match compute to how the team develops locally: if they're already containerized, deploy containers. If not, Lambda is simpler.
- No custom VPC (Lambda, DynamoDB, S3 don't need one)
- No Multi-AZ (you have zero users)
- IaC is optional — Console or `cdk deploy` from laptop is fine
- CI/CD = `git push` → auto-deploy. Nothing more.
- Cost target: $0-50/month
**Explicitly banned** (money pits at this stage):
- EKS ($73/mo for nothing), NAT Gateway ($32/mo for nothing)
- Multi-AZ RDS, ElastiCache, AWS Config
- Custom CloudWatch metrics ($0.30/metric/month adds up)
- Service mesh, multi-region, dedicated CI/CD pipeline
**You don't need this yet**: observability beyond basic alarms, load testing, DR plan, staging environment.
---
## Seed (2-5 people, <1K users, $500K-$2M raised)
**Principle**: Every dollar on infra is a dollar not spent on product. Prove PMF first.
**Key constraints**:
- On-demand pricing only — don't commit to provisioned anything
- One pipeline, one environment (prod). Staging is optional luxury.
- Single AWS account is still fine (use tags)
- No Savings Plans — you don't know your baseline yet
- Cost target: $100-500/month, credits should cover 12-18 months
**Now add** (but keep simple):
- SQS for async work (decouple heavy processing from API)
- EventBridge for internal event routing
- IaC (CDK or Terraform) — one stack, not microstack per service
- CloudWatch alarms on: 5xx rate, latency p99, DynamoDB throttles
**Still avoid**: EKS, Redshift, Step Functions Standard ($0.025/1K transitions), multiple AWS accounts, Security Hub.
**Trigger to graduate**: >1K active users, raising Series A, team >5, first incident that costs you users.
---
## Series A (5-15 engineers, 1K-100K users, $5M-$20M raised)
**Principle**: Harden what works. Add reliability and observability — don't re-architect.
**Key changes**:
- Multi-AZ for all production workloads
- Separate AWS accounts (prod vs non-prod)
- No console changes to production — everything in IaC
- On-call rotation (minimum 4 people for sustainability)
- Weekly 5-minute cost review
- Cost target: $1K-10K/month
**Now appropriate**:
- Savings Plans after 3+ months stable data (1-year Compute SP, No Upfront, cover 50-70% baseline)
- ECS with EC2 for steady-state workloads where Fargate cost exceeds EC2 + SP
- RDS Proxy for Lambda → RDS connection pooling
- WAF if handling sensitive data or seeing abuse
- SOC2 prep (GuardDuty + Security Hub + Config)
- Blue/green or canary deploys
**Trigger to graduate**: 100K+ users, >15 engineers, need dedicated platform team, multi-region requirements.
---
## Series B+ (15+ engineers, 100K+ users, dedicated platform team)
At this stage, standard AWS best practices apply. Startup-specific filtering dissolves.
**What persists from startup thinking**:
- Speed still matters — platform team enables, doesn't gate
- Track cost per customer (investors care about unit economics)
- Still prefer managed services — your moat is product, not your K8s cluster
- Credits may still apply through Series B — check expiration dates
---
## Stage Transition Checklist
### Pre-Revenue → Seed
- [ ] Real users (not just friends testing)
- [ ] Hit a real limitation of pre-revenue architecture (not just "feels hacky")
- [ ] Credits/funding for 12+ months of infra
### Seed → Series A
- [ ] PMF evidence (retention, revenue, growth rate)
- [ ] At least one user-impacting incident
- [ ] Can afford $1K+/month in infra without stress
- [ ] Team growing and needs shared standards
### Series A → Series B+
- [ ] Need dedicated platform/SRE team (not just one person part-time)
- [ ] Multi-region is a real requirement, not nice-to-have
- [ ] Compliance demands formal controls
references/step-functions.md
# Step Functions — Startup Decision Guide
## Stage-Based Recommendation
### Pre-PMF (Seed / <$1M ARR)
- **Don't use Step Functions for simple workflows.** If your flow is "Lambda A → Lambda B → Lambda C" with basic error handling, just chain them in code. Step Functions adds ASL complexity and $0.025/1000 transitions overhead.
- **Use Step Functions when:** You have human approval steps, waiting (hours/days for callbacks), complex branching, or need visual debugging of multi-step processes.
- **Express workflows for high-volume data processing** where you'd otherwise write a Lambda orchestrator.
### Post-PMF / Growth ($1M-$10M ARR)
- Step Functions becomes valuable when you have business-critical workflows that need auditability (payment processing, order fulfillment, onboarding flows).
- Replace homegrown state machines (status columns in databases, Lambda chains with SQS in between) with Step Functions when debugging them takes more than 30 minutes.
## Cost Traps
| Trap | Impact | Fix |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Standard for high-volume short tasks | At 100K executions/day × 10 transitions = 1M transitions = $25/day = $750/month | Switch to Express ($1.00/million requests + duration — typically 90% cheaper at scale) |
| Pass states "for clarity" | Each Pass counts as a billed transition in Standard | Eliminate unnecessary Pass states; combine logic |
| Lambda wrapper for AWS SDK calls | Pay Lambda invocation ($0.20/million) + transition ($25/million) instead of just transition | Use direct SDK integrations (200+ supported services) |
| Standard workflows for cron jobs | Paying per-transition for scheduled tasks with no need for execution history | Use EventBridge Scheduler → Lambda directly |
| Not setting TimeoutSeconds on callbacks | Execution stays open for up to 1 YEAR — you pay nothing per-se but accumulate orphaned executions that hit concurrency limits | Always set TimeoutSeconds on `.waitForTaskToken` |
## Counterintuitive Advice
- **A Lambda function with try/catch is often better than Step Functions for 2-3 step workflows.** The overhead of learning ASL, managing IAM for Step Functions, and the state machine definition doesn't pay off until you have branching, parallel execution, or wait states.
- **Express workflows are underused by startups.** If you're writing a Lambda that orchestrates 3 other Lambdas and you're spending time on error handling — Express workflow does this natively at lower cost for short (<5 min) flows.
- **Distributed Map is free at low volume and massively valuable.** Processing 10K items in parallel with automatic batching and error handling — building this yourself in Lambda takes weeks.
- **Don't use Workflow Studio in production pipelines.** Great for prototyping, but export to ASL JSON and version control it. Console-only workflows are undocumented infrastructure.
## Decision Framework: Should You Use Step Functions?
**Yes, clearly worth it:**
- Workflow has wait states (human approval, callback patterns, timers)
- 5 steps with complex branching/parallel execution
- You need visual execution history for debugging/auditing
- Saga pattern with compensating transactions
- Processing large datasets (Distributed Map)
**Probably not worth it:**
- Linear A→B→C with basic retry (just use Lambda with try/catch)
- Simple cron job (use EventBridge Scheduler → Lambda)
- Request/response within API latency budget (Step Functions adds 50-200ms overhead)
- You have 1-2 engineers and nobody knows ASL (learning curve vs shipping speed)
**Express vs Standard decision:**
- <5 min duration AND >1000 executions/day → Express
- Need execution history in console → Standard
- Long-running (>5 min) → Standard (no choice)
- Cost-sensitive high-volume → Express (calculate breakeven: ~50 transitions/execution = equal cost)
## When to Graduate
| Trigger | Action |
| --------------------------------------------------- | ------------------------------------------- |
| Debugging Lambda chains takes >30min | Wrap in Step Functions for visual debugging |
| You built a status column state machine in DynamoDB | Replace with Step Functions |
| Processing >10K items in batch jobs | Use Distributed Map |
| Compliance requires workflow audit trail | Standard workflows (full execution history) |
| >100K executions/day on Standard | Evaluate Express for cost savings |
references/strands-agent.md
# Strands Agents — Startup Decision Guide
## When to Use Strands (vs. Alternatives)
| Situation | Recommendation | Why |
| -------------------------------------------- | -------------------- | --------------------------------------------------------------------------- |
| Building first AI agent on AWS | **Strands** | Thinnest abstraction, least vendor lock-in, direct Bedrock integration |
| Already invested in LangChain/LangGraph | Stay on LangChain | Migration cost isn't worth it unless you're hitting LangChain-specific pain |
| Need managed multi-agent orchestration | Bedrock Agents | If you don't want to manage containers and agent routing yourself |
| Simple single-call LLM feature (no tool use) | Direct `InvokeModel` | Strands adds overhead you don't need for prompt-in/text-out |
## TypeScript vs Python: Startup Perspective
**Default to TypeScript for startups** unless your team is Python-native:
- Most startup backends are Node/TypeScript already — one language = one deployment pipeline
- Type safety catches tool schema bugs at compile time (agent tool bugs are expensive to debug in production)
- Strands TS has first-class support and bundles Zod for tool validation
**Pick Python only if**: Your team is Python-first, you need Python-specific ML libraries in tools, or you need Strands Evals (Python-only).
## Cost Architecture: The Tool Count Rule
**Each additional tool costs you money on every single invocation** because the model must reason about which tool to use. The cost isn't just token count — it's reasoning quality degradation.
| Tool count | Impact | Guidance |
| ---------- | --------------------------------------------------------- | ------------------------------------------ |
| 1-3 | Minimal overhead, fast reasoning | Ideal for seed-stage agents |
| 4-7 | Noticeable cost increase, occasional wrong tool selection | Acceptable if tools are clearly distinct |
| 8-12 | Significant cost, frequent mis-routing | Split into multiple agents or add a router |
| 13+ | Unreliable, expensive | Refactor immediately |
**Startup rule**: If your PoC agent has > 5 tools and you have < $2K/month LLM budget, you're over-engineering. Split into two focused agents or remove tools.
## Memory: Don't Add It Until You Need It
Memory modes ranked by startup relevance:
1. **NO_MEMORY (start here)**: Stateless tool-calling. Cheapest. Works for 80% of startup agent use cases (internal tools, one-shot tasks, API orchestration).
2. **STM_ONLY (add when)**: Users complain about repeating themselves within a session. Multi-turn conversations that reference earlier context.
3. **STM_AND_LTM (add when)**: You have paying users who want personalization across sessions AND you've validated they actually return frequently enough for LTM to matter.
**Cost of premature LTM**: Memory extraction runs additional model calls per session. At 1000 sessions/day, that's meaningful token spend for personalization most early users won't notice.
## Deployment: The Container Gotcha (TypeScript)
TypeScript agents REQUIRE containerized deployment (`--deployment-type container`). This means:
- ECR image build in your CI/CD pipeline
- Container image maintenance (base image updates, dependency patches)
- Slightly higher cold-start than Python agents
**If you're deploying to Lambda for cost reasons (scale-to-zero)**: Use Python Strands agents — they work with Lambda's native runtime. TypeScript agents need Lambda container image support (slower cold starts, 10GB image limit).
## Evaluation: Ship Evals from Day One (But Cheaply)
**Counterintuitive**: Most startups skip evals entirely OR over-invest in a massive eval suite. The right answer:
**Minimum viable eval suite (3 evaluators, ~$5/day at 100 test cases):**
1. `GoalSuccessRateEvaluator` — Did the agent achieve the user's intent?
2. `ToolSelectionAccuracyEvaluator` — Is it using the right tools?
3. `FaithfulnessEvaluator` — Is it hallucinating? (Critical for customer-facing agents)
**Add more evaluators only when**: You have a specific quality issue you can't diagnose with these three.
**Cost trap**: Evals invoke LLM-as-Judge. 9 evaluators × 500 test cases × daily = significant token spend. Start with 3 evaluators × 50 golden test cases × on-PR-only.
## Gotchas That Waste Startup Time
- **Default model is Claude Sonnet** — expensive for iteration. Override to Nova Micro/Lite during development: saves 10-20x on development costs.
- **VPC config is immutable** — if you deploy with VPC settings and realize you don't need them, you must create an entirely new agent config. Start WITHOUT VPC unless you know you need private resource access.
- **`agentcore destroy` deletes everything** — including memory resources with user data. Always `--dry-run` first. No undo.
- **Memory provisioning takes 2-3 minutes** — friction during rapid iteration. Use NO_MEMORY for development, add memory only in staging/prod configs.
- **OTel is on by default in AgentCore** — traces go to CloudWatch/X-Ray (which costs money). Disable with `--disable-otel` during early development if you're not looking at traces yet.
references/team-scaling.md
# Team Scaling
## Ops Capacity Limits by Team Size
### Solo Founder (1 person)
- **Zero ops tolerance**. If it requires SSH, patching, monitoring, or on-call — you can't use it.
- If it breaks at 3am, it waits until morning.
- One AWS account. No staging environment.
- Cannot operate anything with "cluster" in the name or anything requiring capacity planning.
### Small Team (2-5 engineers)
- ~20% of one engineer's time on infra (not a dedicated role)
- Alerts go to Slack, not PagerDuty — not enough people for on-call
- Can now operate: ECS Fargate, Aurora Serverless v2, basic IaC
- Cannot operate: EKS, multi-account, Transit Gateway, SOC2 program
### Growth Team (5-15 engineers)
- Infrastructure lead at 50% time (not full-time dedicated)
- On-call rotation possible (minimum 4 people for sustainable rotation)
- Can now operate: ECS with EC2, ElastiCache, multi-account, VPC with subnets, Security Hub
- Cannot operate: EKS (unless deep K8s experience exists), multi-region active-active, service mesh
### Platform Team (15+ engineers)
- 2-4 dedicated platform/SRE engineers justified
- Generic AWS service references apply without team-size filtering
- Platform team enables product teams — doesn't gate them
---
## When to Hire for Infrastructure
| Signal | Hire | Typical Stage |
| --------------------------------------- | ------------------------------------------------ | -------------- |
| Deploys breaking, nobody knows why | First infra-aware engineer (not full-time infra) | Seed |
| On-call burning out product engineers | Infra lead (50/50 split) | Early Series A |
| Teams blocked waiting for infra changes | First dedicated platform engineer | Mid Series A |
| AWS bill > $50K/month | FinOps-focused engineer | Series B |
### Counterintuitive Advice
**Don't hire a "DevOps engineer" at seed stage:**
- Not enough infra to justify full-time role
- They will over-engineer because that's their job
- You'll end up with Kubernetes for a 3-service app
- Instead: hire product engineers comfortable with AWS + use managed services
**Don't wait until Series B for infra thinking:**
- Years of accumulated tech debt by then
- Nobody understands the system holistically
- Hiring becomes harder (intimidating codebase)
- Right time for dedicated infra person: when incidents start costing users or revenue
---
## Managed Services Cost Justification
**Rule of thumb**: At startup salaries ($150-250K/year = $75-125/hour), a managed service costing $500/month is cheaper than 7 hours of engineering time per month.
| Self-Managed | Managed | Monthly Ops Hours Saved |
| ------------------------- | ---------------- | ----------------------- |
| PostgreSQL on EC2 | Aurora/RDS | 10-20 hours |
| Kubernetes (self-managed) | EKS with Fargate | 20-40 hours |
| Jenkins on EC2 | GitHub Actions | 10-15 hours |
| Prometheus/Grafana | CloudWatch | 10-20 hours |
| Keycloak | Cognito | 5-10 hours |
The smaller your team, the more managed services function as headcount replacement.
references/well-architected.md
# Well-Architected — Startup Lens
## The Startup Well-Architected Trade-off
AWS Well-Architected assumes you optimize all 6 pillars simultaneously. Startups can't. Here's the priority order by stage:
### Pre-Seed Priority Stack
1. **Cost Optimization** — you die if you run out of money
2. **Security** — but ONLY: no public data exposure, no hardcoded creds, basic IAM
3. **Performance** — just "fast enough" for the user experience
4. ~~Operational Excellence~~ — you ARE the operations team
5. ~~Reliability~~ — single-AZ is fine, manual recovery is fine
6. ~~Sustainability~~ — irrelevant at this stage
### Seed Priority Stack
1. **Security** — first customer data means you can't leak it
2. **Cost Optimization** — credits are running out or gone
3. **Reliability** — first SLA commitments need basic redundancy
4. **Performance** — user expectations rise with a real product
5. **Operational Excellence** — basic CI/CD, basic monitoring
6. ~~Sustainability~~ — still not the priority
### Series A+ Priority Stack
All 6 pillars matter. Use the standard Well-Architected framework. But still weight Cost and Security highest — board reporting requires cost visibility, and enterprise customers require security posture.
## Startup-Specific "High Risk" Redefinitions
Standard WA rates these as HRI (High Risk Issue). For pre-seed startups, they're actually acceptable:
| Standard HRI | Startup Reality | Acceptable Until |
| -------------------- | ------------------------------------------------------ | ----------------------------------------------------------- |
| Single-AZ database | Fine — manual restore from backup if AZ fails | First paying customer with SLA |
| No multi-region DR | Fine — total regional failure is extremely rare | >$100K ARR or compliance requires it |
| Manual deployments | Fine — you're deploying 10x/day, a simple script works | Team >3 engineers |
| No runbooks | Fine — you wrote the code, you know how to fix it | Team >5 or on-call rotation starts |
| No chaos engineering | Absurd at this stage | Team >10 and production stability is a customer requirement |
## Startup-Specific ACTUAL High Risk Issues (any stage)
These are genuinely dangerous regardless of stage:
| Issue | Why It Kills Startups | Fix Time |
| ----------------------------------- | ------------------------------------------ | ---------------------------- |
| Public S3 bucket with customer data | Data breach = company-ending event | 5 minutes |
| IAM user access keys in git | Same | 30 minutes (rotate + remove) |
| No backups of primary database | Corruption/deletion = game over | 15 minutes to enable |
| Root account without MFA | Account takeover = everything lost | 5 minutes |
| No cost alerts | $10K surprise bill eats 2 months of runway | 10 minutes |
## Minimum Viable Well-Architected (Pre-Seed Checklist)
Instead of 50+ WA review questions, pre-seed startups need exactly these:
```
□ S3 Block Public Access enabled (account-level)
□ No IAM users with console passwords or access keys (use SSO or IAM Identity Center)
□ RDS/DynamoDB backups enabled (default retention is fine)
□ Root account has MFA
□ AWS Budget alert set at expected + 50%
□ CloudTrail default trail enabled (it is by default — don't disable it)
□ All secrets in SSM Parameter Store or Secrets Manager (never in code/env files committed to git)
```
That's it. Seven items. Everything else can wait.
## "When to Do a Full WA Review" Triggers
- Preparing for SOC2 audit
- First enterprise customer with security questionnaire
- Monthly spend > $10K (optimization has real ROI)
- Series A due diligence
- Post-incident (something broke in production affecting customers)
- Annual cadence once you're past Series A
SKILL.md
---
name: architect-for-startups
description: >-
Startup-tailored AWS architecture advice that adjusts recommendations to the company's stage (pre-revenue through Series B+), team size, runway, and available credits. Use when a founder wants guidance or a recommendation rather than code changes: which services to choose, how to plan or review an architecture, how to stretch credits and control cost, or how to prepare architecture for a fundraise or technical diligence. For an interactive discovery flow that scaffolds and writes the architecture into the codebase, use start-building-for-startups. For AI-agent runtime selection or agentic architecture recommendations specifically, use agent-advisor. Do not use for: writing or scaffolding code, factual AWS Activate / programs / credits lookups (see knowledge-base-for-startups), a single copy-paste prompt (see prompt-library-for-startups), or migration intent such as GCP-to-AWS or Heroku-to-AWS (see the migration skills: `gcp-to-aws`, `heroku-to-aws`, `llm-to-bedrock`).
---
# Architect for Startups
You are a startup-focused AWS solutions architect. You understand that startups operate under fundamentally different constraints than established companies: limited runway, tiny teams, extreme time pressure, and the need to prove product-market fit before optimizing infrastructure.
Your job is to give stage-appropriate AWS guidance — not the "ideal" architecture, but the right architecture for where this startup is today.
## Step 1: Establish Startup Context
Before giving any architecture advice, determine these four things. Infer from conversation context when possible; ask directly when you can't. See [references/customer-ideation.md](references/customer-ideation.md) for the full discovery framework.
**The 6 questions that reveal architecture-critical constraints fast:**
1. What's your monthly AWS budget ceiling? (What kills you if exceeded?)
2. How many engineers will touch infrastructure? (0-1 = managed services only)
3. What's your team's technical profile? (Non-technical, fullstack generalists, or experienced infra/cloud engineers) Are they already developing with containers locally?
4. Do you have AWS credits? How much, when do they expire?
5. Current traffic/data volume + 12-month optimistic projection?
6. What's the one thing that, if it breaks, kills your company? (This gets redundancy; everything else gets the cheapest option)
If you can infer answers from context or memory, don't ask. If you're missing 2+ of these, ask before recommending.
### Stage Detection
| Stage | Signals | Core Constraint |
| ---------------------- | ------------------------------------------------------ | ------------------------------------- |
| **Pre-revenue / Idea** | No users, building MVP, 1-2 founders | Speed. Ship something this week. |
| **Seed** | First users (<1K), proving PMF, 2-5 people | Cost. Stay alive on credits. |
| **Series A** | Product works, scaling (1K-100K users), 5-15 engineers | Reliability without over-engineering. |
| **Series B+** | Proven scale, 15+ engineers, revenue | Standard best practices apply. |
### Context Checklist
- **Stage**: Which of the four above?
- **Team**: How many engineers? AWS experience level (1-5)?
- **Runway/Credits**: Monthly budget? AWS Activate credits balance? Months of runway?
- **Timeline**: When does this need to be live? (Days, weeks, months?)
- **Users**: Current count and 12-month projection?
If the user is at Series B+ with 15+ engineers, the startup-specific framing adds less value — lean more heavily on the service-specific references directly.
## Step 2: Apply Stage-Appropriate Constraints
Once you know the stage, apply the [Stage Framework](references/stage-frameworks.md).
## Step 3: Route to Service Guidance
You MUST read these service-specific references whenever their technology type is applicable.
These reference will ensure you're architecting through a startup's lens and using the best possible startup-specific
guidance.
### Compute
- [Serverless functions (default for pre-revenue and seed)](references/lambda.md)
- [Container orchestration (Series A+)](references/ecs.md)
- [Virtual machines (rarely needed before Series B)](references/ec2.md)
- [Kubernetes (Series B+ only, requires dedicated platform team)](references/eks.md)
### Data
- [NoSQL (when access patterns are clear)](references/dynamodb.md) —
- [Relational databases (when you need SQL)](references/rds-aurora.md)
- [Object storage](references/s3.md)
### Networking & Delivery
- [API management](references/api-gateway.md)
- [CDN and edge delivery](references/cloudfront.md)
- [VPC architecture (keep simple until Series A)](references/networking.md)
### Security & Identity
- [Access control](references/iam.md)
- [Security auditing](references/security-review.md)
### Messaging & Orchestration
- [SQS, SNS, EventBridge](references/messaging.md)
- [Workflow orchestration](references/step-functions.md)
### Observability
- [Monitoring, logging, tracing](references/observability.md)
### AI/ML
- [Foundation models and AI agents](references/bedrock.md)
- [Agent runtime platform](references/agentcore.md)
- [ML pipelines and model serving](references/mlops.md)
- [Strands SDK agent scaffolding](references/strands-agent.md)
### Cost
- [Cost analysis and optimization](references/cost-check.md)
### Architecture & Planning
- [End-to-end architecture planning](references/aws-plan.md)
- [Well-Architected design](references/aws-architect.md)
### Scaffolding
- [IaC project generation](references/iac-scaffold.md)
### Migration
- [Azure to AWS](references/migration-azure-to-aws.md)
- [App Runner to ECS](references/migration-apprunner-to-ecs-express.md)
### IoT
- [IoT device connectivity and fleet management](references/iot.md)
## Step 4: Startup-Specific Overlays
Always layer these startup-specific concerns on top of the service guidance:
### Credits & Cost
See [Credits Strategy](references/credits-strategy.md). For detailed Activate program information, reference the `knowledge-base-for-startups` skill.
### Speed to Ship
See [Rapid Patterns](references/rapid-patterns.md).
- Pre-revenue and seed: recommend the fastest path to working software
- Favor pre-built solutions (AWS Solutions Library, Amplify, ECS Express Mode) over custom builds
- Explicitly call out "you can add this later" for non-essential complexity
### Team Capacity (HARD GATE)
See [Team Scaling](references/team-scaling.md). **This is a constraint, not a suggestion.**
Before recommending ANY architecture, check it against the team capacity limits.
### Investor Readiness
See [Investor Readiness](references/investor-readiness.md).
Trigger this overlay when ANY of these signals appear in the conversation:
- User mentions fundraising, pitch, investors, board, or due diligence
- User asks about scaling narrative or growth projections
- User asks about cost per user, unit economics, or gross margins
- Architecture discussion involves cost framing relative to revenue
## Step 5: Challenge Your Own Recommendation
**Before delivering any architecture recommendation, run it through the challenger framework** from [Challenger](references/challenger.md). This is not optional.
## Step 6: Security Baseline Check
See [Well Architected](references/well-architected.md) and [Security Review](references/security-review.md).
## Anti-Patterns for Startups
- **Premature optimization**: Building for 1M users when you have 10. Ship first, scale later.
- **Kubernetes before you need it**: EKS requires a platform team. Use Lambda or Fargate until you outgrow them.
- **Multi-region before product-market fit**: You don't need 99.99% availability for a product nobody uses yet.
- **Custom everything**: If AWS has a managed service for it, use it. Your engineers should write product code, not infrastructure code.
- **Ignoring credits expiration**: Activate credits expire. Plan your spending to use them before they do.
- **Over-investing in CI/CD before you have users**: A GitHub Actions workflow that deploys on push is enough until Series A.
- **Copying enterprise architecture**: You are not Netflix. Their architecture solves problems you don't have.
## Output Format
When advising startups, always include:
1. **Stage acknowledgment**: "At your stage (seed), here's what matters..."
2. **Recommendation**: The specific architecture/service choice
3. **Why at this stage**: Why this is right _now_ (not just technically correct)
4. **What you're skipping (and when to add it)**: Explicitly name what you're deferring and the trigger to revisit
5. **Cost impact**: Monthly cost estimate tied to credits/runway
6. **Time to ship**: How long to get this working