Architect

---
name: architect
description: Architectural decision advisor for cloud, data, and SaaS distributed systems. Use when the user asks "should we use X or Y", weighs a tradeoff, or needs a decision matrix, scaling analysis, cost-at-scale review, data-tier design, multi-tenancy model, or API/resilience guidance. For full technical blueprints, use enterprise-design.
category: docs
tier: on-demand
slash_command: /architect
model: opus
---

# Architect — Cloud, Data & SaaS Distributed Architecture Advisor

> **Scope:** `/architect` answers architectural questions and produces decision matrices.
> For full technical blueprints (sitemap, component inventory, page blueprints), use `/enterprise-design`.

Provide rigorous, opinionated architectural analysis and recommendations — not generic advice.

## How to use
- `/architect <question or decision>` — get architectural advice on a specific topic
- `/architect review` — full architecture review of the current project
- `/architect scale <feature>` — analyze scaling implications of a feature
- `/architect data <topic>` — deep-dive data architecture analysis
- `/architect cloud <topic>` — cloud infrastructure analysis and recommendations
- `/architect compare <option A> vs <option B>` — structured decision matrix

---

## Step 1 — Load project context

Detect the stack first (canonical block — source: `_lib/reference.md`), then read the instruction file. **Do not assume GCP/Firebase/npm** — branch on what is detected.

```bash
PROJECT_ROOT=$(git rev-parse --show-toplevel); cd "$PROJECT_ROOT"
INSTRUCTION_FILE=$(for f in CLAUDE.md AGENTS.md .cursorrules; do [ -f "$PROJECT_ROOT/$f" ] && echo "$PROJECT_ROOT/$f" && break; done)

# Cloud provider: gcp | aws | azure | vercel | "" (config / IaC / instruction-file grep — no network)
CLOUD=""
if command -v gcloud >/dev/null 2>&1 && gcloud config get-value project >/dev/null 2>&1; then CLOUD=gcp; fi
[ -z "$CLOUD" ] && ls "$PROJECT_ROOT"/.vercel >/dev/null 2>&1 && CLOUD=vercel
[ -z "$CLOUD" ] && grep -rqiE "aws_|amazonaws|cdk\.json|::aws" "$PROJECT_ROOT"/terraform "$PROJECT_ROOT"/infra "$PROJECT_ROOT"/cdk.json 2>/dev/null && CLOUD=aws
[ -z "$CLOUD" ] && grep -rqiE "azurerm|azure-|microsoft\.web" "$PROJECT_ROOT"/terraform "$PROJECT_ROOT"/infra 2>/dev/null && CLOUD=azure
if [ -z "$CLOUD" ] && [ -n "$INSTRUCTION_FILE" ]; then
  grep -qiE "gcloud|Cloud Run|Cloud SQL|Firebase|GCP_PROJECT" "$INSTRUCTION_FILE" && CLOUD=gcp
  [ -z "$CLOUD" ] && grep -qiE "\baws\b|lambda|dynamodb|ecs|fargate" "$INSTRUCTION_FILE" && CLOUD=aws
fi
echo "cloud=${CLOUD:-unknown}"
[ -n "$INSTRUCTION_FILE" ] && head -100 "$INSTRUCTION_FILE" 2>/dev/null
```

Identify (parentheticals are GCP examples with AWS analogs — map to the **detected** `$CLOUD`):
- Compute & deployment model (Cloud Run / ECS-Fargate-Lambda / Vercel functions), regions
- Data storage tiers (Cloud SQL / RDS-Aurora; Memorystore / ElastiCache; BigQuery / Redshift; GCS / S3)
- API and service topology (managed-container services, async workers, webhooks)
- Authentication model (Firebase Auth / Cognito / Auth0, JWT, OAuth)
- Current scale characteristics (users, RPM, data volume — from the instruction file or codebase)
- Known bottlenecks or constraints

If `$CLOUD` is unknown, ask the user which provider they target before giving provider-specific advice.

---

## Step 2 — Cloud Architecture Analysis

Examine the topic through the cloud infrastructure lens.

> Bullets name **GCP services as concrete examples** — map each to the detected `$CLOUD` equivalent and use that vocabulary:
> Cloud Run → ECS/Fargate, Lambda, App Runner (AWS) · Container Apps, App Service (Azure) · Vercel/Netlify functions ·
> Cloud SQL → RDS/Aurora · Azure SQL · Neon/PlanetScale ·
> Memorystore → ElastiCache · Azure Cache ·
> Pub/Sub → SNS+SQS, EventBridge · Service Bus ·
> Secret Manager → Secrets Manager/SSM · Key Vault.
> If `$CLOUD` is unknown, present the analysis provider-neutrally.

### Compute & Deployment
- Is Cloud Run the right compute model? Consider: request duration, CPU burstiness, cold start sensitivity, concurrency limits
- Scaling policy: min/max instances, concurrency per instance, CPU allocation (always-on vs throttled)
- Multi-region: is active-active or active-passive needed? What's the RTO/RPO?
- CI/CD: deployment pipeline resilience, blue/green vs rolling vs canary

### Networking & Security
- VPC: private connectivity between Cloud Run and Cloud SQL via Private Service Connect?
- Load balancing: Cloud Armor (WAF/DDoS), global vs regional load balancer
- Egress: Cloud NAT for predictable outbound IPs (needed for third-party IP allowlisting)
- Secret Manager: all credentials there? No secrets in env vars or Docker images?
- IAM: least privilege service accounts, Workload Identity Federation (no SA key files)

### Resilience & Observability
- Health checks: liveness vs readiness, startup probes
- Circuit breakers: what happens when Cloud SQL, Redis, or a third-party API is down?
- Retry strategy: exponential backoff with jitter, dead letter queues for Pub/Sub
- Alerting: SLO/SLI definition, error budget, latency p50/p95/p99 targets
- Distributed tracing: OpenTelemetry trace propagation across services

### Cost Architecture
- Cost per request/user at current and projected scale
- Cost cliffs: where does the bill step-change sharply?
- Optimization levers: Cloud Run min instances (cold start vs idle cost), Redis memory tier, Cloud SQL tier

---

## Step 3 — Data Architecture Analysis

Examine the topic through the data lens.

### Storage Tier Design
```
Hot tier:   in-memory cache   — sessions, rate limits, LLM cache, real-time   (Memorystore / ElastiCache / Azure Cache)
Warm tier:  relational DB     — transactional data, user records, audit log   (Cloud SQL / RDS-Aurora / Azure SQL / Neon)
Cold tier:  analytics warehouse — analytics, exports, ML features             (BigQuery / Redshift / Snowflake)
Archive:    object store      — reports, backups, blobs                        (GCS / S3 / Azure Blob)
```

For the topic: which tier(s) are involved? Is data in the right tier? (Parenthetical names are per-provider examples.)

### Schema & Query Design
- Table design: normalization level appropriate for access patterns?
- Indexing: composite indexes for common WHERE + ORDER BY patterns?
- N+1 queries: JOIN vs separate queries vs batching?
- Pagination: cursor-based (stable) vs offset (drifting)? Performance at scale?
- Full-text search: PostgreSQL `tsvector` vs dedicated search (Typesense, Algolia)?

### Consistency & Transactions
- ACID boundaries: what must be in a single transaction?
- Eventual consistency: where is it safe, where is it dangerous?
- Optimistic vs pessimistic locking for concurrent updates?
- Idempotency keys: for payment, email, or Pub/Sub operations?

### Data Pipelines
- Pub/Sub message schema: forward-compatible (add fields, never remove/rename)?
- At-least-once delivery: are consumers idempotent?
- Backpressure: what happens when a consumer falls behind?
- BigQuery: streaming inserts vs batch loads? Partition/cluster strategy?

### Privacy & Compliance
- PII fields: identified, encrypted at field level or DB level?
- Data retention: TTL policies defined and enforced?
- Right to deletion: cascade deletes vs soft deletes with purge job?
- Audit trail: immutable log of all user data modifications?

---

## Step 4 — SaaS / Distributed Systems Analysis

Examine the topic through the distributed systems lens.

### Multi-Tenancy Model
| Model | Isolation | Cost | Complexity | When to use |
|---|---|---|---|---|
| Row-level (`WHERE org_id = ?`) | Low | Low | Low | < 10K tenants, low compliance requirements |
| Schema-per-tenant | Medium | Medium | Medium | Compliance requirements, moderate isolation |
| DB-per-tenant | High | High | High | Enterprise, strict data residency, > $1K/month per tenant |

Current model assessment and recommendation for the topic.

### API Design
- REST conventions: resource naming, HTTP verbs, status codes, envelope format
- Versioning strategy: URI (`/v2/`) vs header (`API-Version: 2`)? Breaking vs additive changes?
- Rate limiting: per-user, per-tier, per-endpoint? Token bucket vs sliding window?
- Pagination: cursor vs offset, page size limits, total count trade-off
- Webhooks: retry policy, signature verification, idempotency, event schema versioning

### Async & Event-Driven Patterns
- Command vs event: commands are directed, events are broadcast — use the right one
- Saga pattern for distributed transactions (e.g., signup → create subscription → send email)
- Outbox pattern: write event to DB in same transaction, then publish to Pub/Sub
- Dead letter queue: maximum retries, alerting on DLQ messages

### Resilience Patterns
- Bulkhead: isolate failures (slowness in one dependency should not block unrelated requests)
- Circuit breaker: open after N failures, half-open probe, close on success
- Graceful degradation: what is the fallback when AI agents are slow/down?
- Chaos engineering: have you tested: Cloud SQL restart, Redis flush, Pub/Sub delay?

---

## Step 5 — Recommendations

For each dimension, structure as:

**Current state:** [brief assessment]
**Recommendation:** [specific, opinionated action]
**Rationale:** [why this over alternatives]
**Tradeoffs:** what you gain and what you give up
**Risks:** what can go wrong
**Implementation path:** incremental steps to get there

---

## Step 6 — Decision Matrix (for architectural choices)

When comparing options:

| Criterion | Weight | Option A | Option B | Option C |
|---|---|---|---|---|
| Scalability | 25% | | | |
| Operational complexity | 20% | | | |
| Development speed | 20% | | | |
| Cost at scale | 15% | | | |
| Resilience | 10% | | | |
| Team expertise fit | 10% | | | |
| **Weighted score** | | | | |

**Recommendation:** [winner with clear reasoning]

---

## Step 7 — Architecture Diagram

For significant proposals, produce a text-based topology diagram using the detected `$CLOUD` provider's service names. Example shape (GCP shown — substitute AWS / Azure / Vercel equivalents):

```
┌─────────────────────────────────────────────────────┐
│                    CLOUD TOPOLOGY                   │
├─────────────────────────────────────────────────────┤
│  [Static hosting]  ──→  [API service]               │
│                               │                     │
│              ┌────────────────┼──────────────┐      │
│              ↓                ↓              ↓      │
│  [Relational DB: Primary] [Cache]    [Message bus]  │
│              │                              │       │
│   [DB: Replica]                     [Worker service]│
│                                             │       │
│                                  [Analytics warehouse]│
└─────────────────────────────────────────────────────┘
```

---

## Output format

```
=== Architecture Analysis: <topic> ===

CONTEXT
───────
[brief project context and scope of analysis]

VERDICT
───────
[one-sentence architectural recommendation]

CLOUD ARCHITECTURE
──────────────────
Current: [state]
Recommendation: [action]
Rationale: [why]
Risks: [what to watch for]

DATA ARCHITECTURE
─────────────────
Current: [state]
Recommendation: [action]
Rationale: [why]
Risks: [what to watch for]

SAAS / DISTRIBUTED SYSTEMS
───────────────────────────
Current: [state]
Recommendation: [action]
Rationale: [why]
Risks: [what to watch for]

DECISION MATRIX (if applicable)
────────────────────────────────
[table]

IMPLEMENTATION PATH
───────────────────
Immediate (days):   [step 1]
Short-term (weeks): [step 2]
Long-term (months): [step 3]

OPEN QUESTIONS
──────────────
[any assumptions that need validation before proceeding]
```