> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diyanet.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# BuildingBlocks — Genel Bakış

> 20 yeniden kullanılabilir altyapı paketinin amaç, gruplama ve kayıt haritası.

`src/BuildingBlocks/*` altında 20 bağımsız altyapı paketi bulunur. Her biri tek bir kesişen sorumluluğu (caching, messaging, identity, observability, util) kapsüller; Application/Infrastructure katmanları bu paketleri `AddXxx(...)` uzantılarıyla `Program.cs`'de wire-up eder. Paketler iş kuralı içermez ve `Application`/`Domain` projelerine referans vermez — yeni bir projeye olduğu gibi taşınabilir.

## Tüm paketler

| Paket                                          | Grup          | Amaç                                                                                                                       |
| ---------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `BuildingBlocks.Caching`                       | Caching       | `IHybridRequestCache` — L1 (in-process) + L2 (Redis) birleşik cache, tag-based invalidation, multi-instance broadcast hook |
| `BuildingBlocks.Caching.Redis`                 | Caching       | Redis `IDistributedCache` backend'i, request/database/socket cache implementasyonları, distributed lock                    |
| `BuildingBlocks.Contracts.Events`              | Messaging     | `IntegrationEvent` base + `IIntegrationEventHandler<T>` kontratları (cross-service)                                        |
| `BuildingBlocks.EventBus`                      | Messaging     | Event bus soyutlaması (`IEventBus`), subscription registry, builder pattern                                                |
| `BuildingBlocks.EventBus.MassTransit.RabbitMq` | Messaging     | **Aktif** — MassTransit + RabbitMQ ile integration event dağıtımı, EF Outbox, retry/redelivery                             |
| `BuildingBlocks.EventBus.EventBusRabbitMQ`     | Messaging     | **Legacy** — ham RabbitMQ.Client tabanlı event bus (MassTransit tarafından değiştirildi)                                   |
| `BuildingBlocks.Keycloak`                      | Identity      | Çift-realm Keycloak SSO (Vatandaş + Personel), claims transformation, `ICurrentUserService`                                |
| `BuildingBlocks.Jwt`                           | Identity      | Çok-şemalı JWT auth (Backoffice + OTPChallenge), token üretimi/doğrulama                                                   |
| `BuildingBlocks.OAuth`                         | Identity      | OAuth2 + PKCE soyutlaması (Google, Meta) — `IOAuthClient<TUserInfo>`                                                       |
| `BuildingBlocks.Otp`                           | Identity      | HMAC-SHA256 OTP üretimi, hash'leme, rate-limit ayarları                                                                    |
| `BuildingBlocks.DeviceDetector`                | Identity      | IP çözümleme, cihaz parmak izi, trust/risk değerlendirme                                                                   |
| `BuildingBlocks.Security.BotProtection`        | Identity      | Google reCAPTCHA v3 doğrulama (Polly resilient HTTP)                                                                       |
| `BuildingBlocks.Specification`                 | Util          | Ardalis.Specification tabanlı generic spec pattern + cache entegrasyonu                                                    |
| `BuildingBlocks.Time`                          | Util          | `IClock` saat soyutlaması — `SystemClock` / `FakeClock`                                                                    |
| `BuildingBlocks.FileServer`                    | Util          | Statik dosya sunumu, auth-aware özel file provider                                                                         |
| `BuildingBlocks.Hangfire.MediatR.Extensions`   | Util          | Hangfire + MediatR köprüsü — `IRequest`'leri arka plan job olarak serialize etme                                           |
| `BuildingBlocks.Logging.Serilog`               | Observability | Serilog kurulumu, Seq sink, HTTP request enrichment                                                                        |
| `BuildingBlocks.Monitoring.Prometheus`         | Observability | Prometheus HTTP metrik middleware'i + `/metrics` endpoint                                                                  |
| `BuildingBlocks.Observability`                 | Observability | OpenTelemetry metrics/tracing pipeline, health→gauge köprüsü                                                               |
| `BuildingBlocks.HealthChecks`                  | Observability | K8s-uyumlu health check endpoint'leri (live/ready/startup/external)                                                        |

## Gruplama

```mermaid theme={null}
mindmap
  root((BuildingBlocks))
    Caching
      Caching (L1+L2)
      Caching.Redis (L2 backend)
    Messaging
      Contracts.Events
      EventBus (abstraction)
      EventBus.MassTransit.RabbitMq (aktif)
      EventBus.EventBusRabbitMQ (legacy)
    Identity
      Keycloak
      Jwt
      OAuth
      Otp
      DeviceDetector
      Security.BotProtection
    Util
      Specification
      Time
      FileServer
      Hangfire.MediatR.Extensions
    Observability
      Logging.Serilog
      Monitoring.Prometheus
      Observability
      HealthChecks
```

## Öne çıkanlar

<CardGroup cols={2}>
  <Card title="Caching" icon="bolt" href="/building-blocks/caching">
    Hibrit L1+L2 cache, tag invalidation, multi-instance broadcast.
  </Card>

  <Card title="Event Bus (MassTransit)" icon="paper-plane" href="/building-blocks/event-bus">
    RabbitMQ topic exchange + EF Outbox + retry/DLX.
  </Card>

  <Card title="Keycloak" icon="key" href="/building-blocks/keycloak">
    Çift-realm SSO, claims transformation, çift JwtBearer şeması.
  </Card>

  <Card title="OTP" icon="shield-halved" href="/building-blocks/otp">
    HMAC-SHA256 stateless doğrulama, rate-limit.
  </Card>
</CardGroup>

<Note>
  `BuildingBlocks.EventBus.EventBusRabbitMQ` **legacy**'dir ve yeni geliştirmede kullanılmaz. Aktif integration event altyapısı `BuildingBlocks.EventBus.MassTransit.RabbitMq`'tır (EF Outbox + delayed redelivery destekli). Yeni event publish/subscribe için her zaman MassTransit paketini kullanın.
</Note>

## Ortak desenler

Tüm paketler aynı sözleşmelere uyar:

* **Options pattern** — her paket `IConfiguration` → `IOptions<T>` binding'i yapar (`services.Configure<TOptions>(...)`).
* **`AddXxx(...)` uzantısı** — DI kaydı `IServiceCollection` döner, fluent chaining'e izin verir.
* **Kayıt sırası önemli** — özellikle cache: `AddRedisCache` (L2) ÖNCE, sonra `AddCache`, sonra `AddHybridCache`. Aksi halde L1-only çalışır.

## İlgili

<CardGroup cols={2}>
  <Card title="Caching mimarisi" icon="layer-group" href="/caching/overview">
    L1/L2 stratejisi, invalidation ve multi-instance detayları.
  </Card>

  <Card title="Event akışı" icon="diagram-project" href="/events/overview">
    Domain event → integration event → Outbox → RabbitMQ.
  </Card>
</CardGroup>