Learning Roadmap8 kategori · 40 konu

Öğrenmem Gerekenler

SparkClaw'ı sıfırdan inşa ederken altta yatan mühendislik disiplinlerinin tam listesi. Her konu için: keyword'ler (arama), neden lazım, SparkClaw'da nereye dokunuyor, ilk öğrenme kaynağı. Sırası önemli değil — bir modülü inşa ederken o kategoriyi derinleştir.

A. Runtime & Execution B. Tool / MCP Layer C. Multi-Tenant SaaS Altyapısı D. AI Engineering E. Observability F. Frontend & Canvas G. DevOps & Deployment H. Ürün & İş Tarafı

Runtime & Execution

5 konu

Agent network'lerini çalıştıran katman. Burası "çalışıyor mu" sorusunun cevabı.

Durable Execution & Workflow Snapshots

durable executionworkflow snapshotdeterministic replayevent sourcingTemporalInngestMastra workflow persistence

Neden: Agent run'ı dakikalarca sürer + LLM çağrıları hata yapar + tool çağrıları idempotent değil. Worker crash'lerinde run kaybolmamalı, kaldığı yerden devam etmeli. Dify'ın açığı tam burası.
SparkClaw'da: apps/runtime/ — M1b'de runs / run_steps / run_events tabloları + Mastra workflow snapshot persistence.
Kaynak: docs.temporal.io — workflow concepts

Event-Driven Architecture

event buspub/subRedis StreamsNATS JetStreammessage brokerfan-outconsumer groups

Neden: Triggers (webhook, cron, event), agent-to-agent event handoff, real-time canvas update — hepsi event bus üzerinden geçer. docs/11 #3 açık karar.
SparkClaw'da: apps/runtime/ — docs/08-runtime.md event bus bölümü; docker-compose'da Redis placeholder.
Kaynak: redis.io — Streams

Job Queues & Retry Semantics

BullMQInngestexponential backoffdead letter queueidempotency keyretry budget

Neden: Background MCP çağrıları, cron triggers, retry mantığı, "30 dk sonra çalış" tipi delayed jobs.
SparkClaw'da: apps/runtime/ — Mastra workflow runner'ın yanında bağımsız queue.
Kaynak: docs.bullmq.io

SSE & Streaming

Server-Sent EventsEventSourceReadableStreampartial JSON parsingAI SDK streamTexttoken streaming

Neden: Agent yanıtı tek seferde gelmez — token token akar. Canvas'ta "Agent şu an çalışıyor" göstermek için SSE. Mastra zaten native SSE veriyor.
SparkClaw'da: apps/runtime/src/api/v1.ts chat endpoint streaming'e dönüştürülecek; builder tarafında useChat hook'u.
Kaynak: AI SDK — streamText

Saga & Compensating Transactions

saga patterncompensating transactionrollbackdistributed transactions

Neden: Multi-step agent flow'u ortada hata verirse (Slack'e mesaj gitti, Jira issue açılmadı), önceki adımları "geri al" mantığı. Tüm tool'lar idempotent değil.
SparkClaw'da: Network executor — docs/03-agent-network-model.md edge tipleri ile birlikte tasarlanmalı.
Kaynak: microservices.io — Saga pattern

Tool / MCP Layer

5 konu

Platformun farklılaşma silahı. Bu katmandaki her detay rekabetçi avantaj.

MCP Protocol Deep-Dive

Model Context ProtocolJSON-RPCstdio transportHTTP+SSE transportresources vs tools vs promptsMCP OAuth 2025-03-26

Neden: SparkClaw'ın bel kemiği. "Her tool MCP" diyorsan spec'in detayını bilmek şart — özellikle resources (file-like read) vs tools (function call) vs prompts (template) ayrımı.
SparkClaw'da: packages/mcp-registry/, packages/mcp-servers/, apps/runtime/ MCP host.
Kaynak: spec.modelcontextprotocol.io

Sandbox & İzolasyon

isolated-vmV8 isolatesworker_threadsFirecracker microVMgVisorseccompDify dify-sandbox

Neden: User-authored MCP'ler güvenilmez. Code execution sandbox'ı olmadan platform açılmaz. docs/11 #4 açık karar — Dify'ın isolated-vm yönü işaretli.
SparkClaw'da: packages/mcp-authoring/ runtime — user-MCP sandbox.
Kaynak: github.com/laverdet/isolated-vm

OpenAPI → Tool Generation

OpenAPI 3.1JSON Schemafunction callingtool synthesisAPI-to-MCP wrapper

Neden: "X'in API'si var, MCP'si yok" durumunun çözümü. Wrapper otomatik üretiyorsa kullanıcı saniyeler içinde yeni servis ekler. packages/mcp-authoring tam buna.
SparkClaw'da: packages/mcp-authoring/src/wrapper.ts (yazılacak).
Kaynak: swagger.io — OpenAPI spec

A2A Protocol

Agent-to-Agent protocolA2A specGoogle A2AAgentCardinter-agent communication

Neden: MCP "tool" katmanını standartlaştırıyor; A2A "agent-to-agent" katmanını. Network paradigmindeki peer-to-peer handoff'lar için spec olabilir.
SparkClaw'da: docs/03-agent-network-model.md — handoff protokolü yazılırken referans.
Kaynak: github.com/google/A2A

JSON Schema & Zod Runtime Validation

JSON SchemaZodajvzod-to-json-schemaschema introspectionruntime type guard

Neden: Capability spec JSON Schema. MCP tool input'u JSON Schema. Agent output projection JSON Schema. Tek dil + iki dünya (TS compile-time + runtime validation).
SparkClaw'da: packages/shared-types/, packages/capability-spec/schema/.
Kaynak: zod.dev

Multi-Tenant SaaS Altyapısı

5 konu

Mastra çözmüyor, biz çözmek zorundayız. docs/05 sorumluluk tablosu net.

OAuth 2.0 + OIDC + PKCE

OAuth 2.0OIDCPKCEauthorization code flowrefresh token rotationscopesstate parameter

Neden: YouTube/X/Slack/Google entegrasyonu OAuth gerektiriyor. Multi-tenant'ta token-per-workspace tutmak zorundayız.
SparkClaw'da: apps/runtime/src/oauth/ (yazılacak), oauth_credentials tablosu.
Kaynak: oauth.net/2

Envelope Encryption & KMS

envelope encryptionKMSAWS KMSGCP KMSAES-256-GCMkey rotationDEK/KEK

Neden: Kullanıcı credential'larını plaintext tutamayız. Envelope encryption = veri için DEK + DEK'i şifrelemek için KEK (KMS'te). Self-host'ta da çalışmalı.
SparkClaw'da: apps/runtime/ secrets manager — docs/02 §Güvenlik.
Kaynak: AWS KMS — envelope encryption

Postgres Row-Level Security

Postgres RLSpoliciesSET app.workspace_idmulti-tenant isolationtenant_id column

Neden: docs/02 §multi-tenancy her tabloda workspace_id diyor. Application-level filtreyi unutmak = cross-tenant leak. RLS DB seviyesinde garantiler.
SparkClaw'da: apps/runtime/src/db/schema.ts — şu an policy'ler yok, M3'te eklenmeli.
Kaynak: postgresql.org — Row Security

Webhook Security

HMAC signaturewebhook verificationreplay protectionidempotency keysigning secrets

Neden: Webhook trigger'ları SparkClaw'a public POST endpoint açıyor. İmza doğrulanmazsa spoofing.
SparkClaw'da: apps/runtime/src/api/ trigger receiver.
Kaynak: stripe.com — webhook signatures

Audit Log

audit logstructured loggingcompliance logimmutable logappend-onlywho-what-when

Neden: SOC 2 + enterprise sales için zorunlu. "Bu credential'a kim erişti, ne zaman?" cevabı.
SparkClaw'da: audit_events tablosu (yazılacak), her sensitive eylem.
Kaynak: auth0.com — logs

AI Engineering

7 konu

Modelin doğru sonuç vermesini sağlayan disiplin. Prompt yazmak değil, sistem inşa etmek.

Context Engineering (Prompt Assembly)

context engineeringprompt assemblylost in the middleprompt orderingcache-friendly prompts

Neden: Stable-prefix + volatile-suffix sıralaması prompt cache'i exploit eder. Sistem prompt + tool defs sabit, volatile veri sonda.
SparkClaw'da: packages/agent-core/src/prompt-assembler.ts (yazılacak).
Kaynak: anthropic.com — Contextual Retrieval

Prompt Caching

Anthropic prompt cachingcache controlephemeral cachecache hit rateTTL 5min

Neden: Aynı system prompt + tool def'leri tekrar tekrar gönderiliyor. Cache ile %4–10× ucuzlama mümkün. Multi-tenant'ta workspace başına cache hit oranı = direkt margin.
SparkClaw'da: apps/runtime/src/agents.ts Mastra Agent config'i + Anthropic SDK cache_control parametresi.
Kaynak: docs.claude.com — prompt caching

Tool Result Projection

context compressiontool result projectionsummary-then-detaildynamic truncation

Neden: 100KB JSON response agent context'ini şişirir. Capability spec'e output_projection alanı ekleme önerimizin temeli.
SparkClaw'da: packages/agent-core/src/projection.ts (yazılacak), packages/capability-spec/.
Kaynak: Lost in the Middle (arxiv)

Evals & Guardrails

LLM evalsLLM-as-judgeregression testguardrailsNVIDIA NeMo GuardrailsMastra Evals

Neden: "Agent doğru mu çalışıyor" sorusunun otomatik cevabı. Unit test yetmez — semantik eval lazım. Co-builder'ın ürettiği flow'lar deterministik değil → eval kritik.
SparkClaw'da: packages/agent-core/src/evals/ (yazılacak), Mastra Evals entegrasyonu.
Kaynak: mastra.ai — Evals

Cost & Token Accounting

token accountingtiktokenusage trackingcost attributionmarkup modelmetered billing

Neden: M1a'da usage_events tablosu var ama henüz pricing matrisi yok. Provider × model × cache hit indirimi + Anthropic batch %50 indirim — hepsi doğru muhasebeleşmeli.
SparkClaw'da: apps/runtime/src/usage.ts (var ama basit) — pricing table genişletilecek.
Kaynak: docs.claude.com — pricing

Memory Patterns

working memorysemantic recallobservational memoryconversation summarythread management

Neden: "Bu kullanıcı vlog seviyor" gibi insight'ları kalıcı tutmak. Mastra Memory bunu veriyor ama policy bizim (ne yazılır, ne yazılmaz).
SparkClaw'da: packages/agent-core/src/memory/.
Kaynak: mastra.ai — Memory

RAG (Hybrid Search & Re-ranking)

RAGchunkingembeddinghybrid searchBM25 + vectorre-rankingCohere Rerankrecursive retrieval

Neden: Sadece custom corpus için (kullanıcının PDF/Notion'u). Live tool > RAG; gerçek custom data geldiğinde lazım.
SparkClaw'da: packages/agent-core/src/rag/ (M3+), pgvector backend.
Kaynak: mastra.ai — RAG

Observability

4 konu

"Çalıştı mı, neden çalışmadı" sorularının cevabı. Burası olmadan kullanıcı debug edemez.

OpenTelemetry & Distributed Tracing

OpenTelemetryOTLPspantrace IDbaggagepropagatorsemantic conventions

Neden: Agent run → MCP call → LLM call zincirinin uçtan uca izini sürmek. Industry standard. Mastra zaten OTel desteği veriyor.
SparkClaw'da: apps/runtime/ — Hono middleware + Mastra traces export.
Kaynak: opentelemetry.io — concepts

LLM-Specific Tracing

LangfusePhoenix ArizeLangSmithMastra TracesLLM observabilityprompt/completion logging

Neden: Generic OTel LLM detaylarını yakalamıyor (prompt content, token breakdown, cache hit, tool call args). LLM-spesifik trace katmanı lazım.
SparkClaw'da: apps/runtime/ trace store; builder'da trace timeline UI.
Kaynak: langfuse.com — docs

Trace Replay & Time-Travel Debugging

trace replaytime-travel debugrun replaydeterministic playback

Neden: "5 dk önce çalışmış run'ı aynısıyla yeniden çalıştır" — bug fix iterasyonu için altın değerinde. Mastra workflow snapshot ile mümkün.
SparkClaw'da: apps/builder/ trace timeline + "Re-run from step X" UX.
Kaynak: docs.temporal.io — replay

Structured Logging

structured loggingJSON logspinolog levelscorrelation IDlog sampling

Neden: console.log ile production debug edilmez. Hono'da pino önerisi standart.
SparkClaw'da: apps/runtime/src/server.ts — şu an console.log var.
Kaynak: getpino.io

Frontend & Canvas

5 konu

Builder UX'in mühendisliği. Rakipler buradan ayrışıyor.

React Flow Advanced Patterns

React Flow custom nodesedge routinghandle typessub-flowsviewport controlMiniMap

Neden: packages/canvas/ zaten React Flow. Custom node tipleri düzgün animate olsun, edge'ler çakışmasın, zoom-to-fit çalışsın.
SparkClaw'da: packages/canvas/src/nodes/.
Kaynak: reactflow.dev — custom nodes

Monaco Editor Integration

Monaco editorlanguage servicesTypeScript workerIntelliSensemulti-modeltheming

Neden: docs/02 §Builder orta pane "code/config Monaco editor". Kullanıcı kendi MCP'sini yazarken TS LSP + capability spec autocomplete olmalı.
SparkClaw'da: apps/builder/components/CodePane.tsx (yazılacak).
Kaynak: Monaco editor

Real-Time Collaboration

CRDTYjsLiveblockspresenceawarenesscollaborative editingconflict-free

Neden: docs/11 #12 açık karar — Figma-style co-editing. Day-1'de değil ama mimariye yer ayır.
SparkClaw'da: packages/canvas/ state management katmanı.
Kaynak: docs.yjs.dev

State Management

ZustandXStateJotaistate machinesfinite statesignals

Neden: docs/11 #6 açık karar. Canvas state simple (Zustand) ama agent execution state karmaşık (XState daha doğru).
SparkClaw'da: apps/builder/, packages/canvas/.
Kaynak: stately.ai — XState

Streaming UI Patterns

React Server ComponentsSuspenseuseChatAI SDK UIpartial renderingoptimistic updates

Neden: Co-builder chat token token akıyor, canvas update'ları streaming, trace timeline real-time. Next.js 15 + AI SDK + React 19 üçlüsü.
SparkClaw'da: apps/builder/components/CoBuilderChat.tsx.
Kaynak: AI SDK UI — chatbot

DevOps & Deployment

5 konu

Production'a çıkmak ve ayakta tutmak.

Docker Multi-Stage Builds (Monorepo)

Docker multi-stagepnpm workspace + Dockerturbo prunebuild cacheBuildKit

Neden: apps/runtime/Dockerfile ve apps/builder/Dockerfile var; monorepo'da workspace bağımlılıkları doğru kopyalanmazsa imaj patlar veya devasa olur.
SparkClaw'da: apps/runtime/Dockerfile, apps/builder/Dockerfile.
Kaynak: turborepo.com — Docker guide

Zero-Downtime Database Migrations

expand-contractonline schema changegh-ostDrizzle migration safetyNOT NULL backfill

Neden: agents tablosu büyüdükten sonra ALTER TABLE … ADD COLUMN NOT NULL lock yapabilir. Migration pattern'i bilinmeli.
SparkClaw'da: apps/runtime/drizzle/.
Kaynak: Braintree — safe operations

Container Orchestration

RailwayFly.ioAWS ECSKubernetesHelmautoscalinghealthcheck

Neden: docs/02 §Deployment cloud-first + self-host opsiyonel. Production deploy seçimi.
SparkClaw'da: Yeni deploy/ veya infra/ paketi.
Kaynak: fly.io — docs

Secret Management

DopplerInfisicalAWS Secrets ManagerHashiCorp Vaultenv var hygiene.env.example

Neden: MASTRA_GATEWAY_TOKEN, FAL_KEY, DATABASE_URL, kullanıcı OAuth secret'ları — production'da .env dosyası yetmez.
SparkClaw'da: apps/runtime/ config layer.
Kaynak: docs.infisical.com

Cold Start & Edge Runtime

cold startedge runtimeVercel EdgeCloudflare WorkersNode.js runtime constraints

Neden: Builder Next.js 15 — Vercel deploy edilirse edge runtime kısıtları var (Mastra Node-only mu, edge-uyumlu mu?). Cold start = ilk istek latency.
SparkClaw'da: apps/builder/next.config.mjs.
Kaynak: Vercel — Edge runtime

Ürün & İş Tarafı

4 konu

Teknik karar değil ama teknik kararı şekillendiren disiplinler.

Usage-Based Billing

metered billingStripe meteredOrbLagousage recordstrue-upprepaid credits

Neden: usage_events tablosu fatura kesmek için. Inference cost + MCP CPU + storage + egress — hepsi farklı metric. Stripe metered subscriptions standart.
SparkClaw'da: M3+ — apps/runtime/src/billing/ (yazılacak).
Kaynak: Stripe — usage-based billing

Marketplace Governance

marketplace trust signalscode reviewvendor verificationnpm provenancesupply chain

Neden: docs/11 #14 açık karar. MCP marketplace açılırsa malicious MCP riski.
SparkClaw'da: packages/mcp-registry/ — verification katmanı.
Kaynak: npm — provenance

Compliance (SOC 2, GDPR)

SOC 2 Type IIGDPR data subject rightsdata residencyright to erasureDPAsub-processors

Neden: Enterprise sales gate. SOC 2 olmadan büyük müşteri açılmaz. GDPR EU müşterileri için zorunlu.
SparkClaw'da: Audit log + encryption + data residency stratejisi (henüz yok).
Kaynak: Vanta — SOC 2 guide

Open-Core Licensing

open-coreAGPLfair-sourceBSLMIT vs Apache 2.0commercial exception

Neden: docs/11 #10 açık karar. n8n fair-source, Dify Apache 2.0 + multi-tenant kısıtı — model seçimi gelir/community trade-off'u.
SparkClaw'da: Tüm package.json license alanları.
Kaynak: fair.io