@3lineas/grooveskills 1.4.0 → 1.6.0

package/skills/caching-rate-limiting/references/cache-rate-limit-examples.md

@@ -0,0 +1,129 @@
+# Implementation Reference: Cache & Rate Limiting Adapters
+
+Production implementations of Redis cache, Cloudflare KV, and sliding-window rate limiters.
+
+---
+
+## 1. Redis Cache Adapter (`ioredis`)
+
+```ts
+// src/infrastructure/adapters/cache/redis-cache.adapter.ts
+import type { Redis } from "ioredis";
+import type { CacheStorePort } from "@/domains/cache/cache-store.port";
+
+export class RedisCacheAdapter implements CacheStorePort {
+  constructor(private redis: Redis) {}
+
+  async get<T>(key: string): Promise<T | null> {
+    const raw = await this.redis.get(key);
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      return null;
+    }
+  }
+
+  async set<T>(key: string, value: T, ttlSeconds: number): Promise<void> {
+    await this.redis.set(key, JSON.stringify(value), "EX", ttlSeconds);
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.redis.del(key);
+  }
+}
+```
+
+---
+
+## 2. Cloudflare Workers KV Cache Adapter
+
+```ts
+// src/infrastructure/adapters/cache/cloudflare-kv.adapter.ts
+import type { CacheStorePort } from "@/domains/cache/cache-store.port";
+
+export class CloudflareKvAdapter implements CacheStorePort {
+  constructor(private kv: KVNamespace) {}
+
+  async get<T>(key: string): Promise<T | null> {
+    return this.kv.get<T>(key, "json");
+  }
+
+  async set<T>(key: string, value: T, ttlSeconds: number): Promise<void> {
+    await this.kv.put(key, JSON.stringify(value), { expirationTtl: Math.max(ttlSeconds, 60) });
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.kv.delete(key);
+  }
+}
+```
+
+---
+
+## 3. Redis Sliding Window Rate Limiter Adapter
+
+```ts
+// src/infrastructure/adapters/rate-limit/redis-rate-limiter.adapter.ts
+import type { Redis } from "ioredis";
+import type { RateLimiterPort, RateLimitResult } from "@/domains/rate-limit/rate-limiter.port";
+
+export class RedisSlidingWindowRateLimiter implements RateLimiterPort {
+  constructor(
+    private redis: Redis,
+    private maxRequests: number = 60,
+    private windowSeconds: number = 60
+  ) {}
+
+  async limit(identifier: string): Promise<RateLimitResult> {
+    const now = Date.now();
+    const windowStart = now - this.windowSeconds * 1000;
+    const key = `ratelimit:${identifier}`;
+
+    const multi = this.redis.multi();
+    multi.zremrangebyscore(key, 0, windowStart);
+    multi.zadd(key, now, `${now}-${Math.random()}`);
+    multi.zcard(key);
+    multi.expire(key, this.windowSeconds);
+
+    const results = await multi.exec();
+    const count = (results?.[2]?.[1] as number) ?? 1;
+
+    const remaining = Math.max(0, this.maxRequests - count);
+    const success = count <= this.maxRequests;
+
+    return { success, limit: this.maxRequests, remaining, resetSeconds: this.windowSeconds };
+  }
+}
+```
+
+---
+
+## 4. In-Memory Testing Cache Adapter
+
+```ts
+// src/infrastructure/adapters/cache/memory-cache.adapter.ts
+import type { CacheStorePort } from "@/domains/cache/cache-store.port";
+
+export class MemoryCacheAdapter implements CacheStorePort {
+  private store = new Map<string, { value: unknown; expiresAt: number }>();
+
+  async get<T>(key: string): Promise<T | null> {
+    const item = this.store.get(key);
+    if (!item) return null;
+    if (Date.now() > item.expiresAt) {
+      this.store.delete(key);
+      return null;
+    }
+    return item.value as T;
+  }
+
+  async set<T>(key: string, value: T, ttlSeconds: number): Promise<void> {
+    this.store.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000 });
+  }
+
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+}
+```

package/skills/clean-architecture-ddd/SKILL.md

@@ -101,3 +101,4 @@ export async function chargeSubscriptionAction(
 - **`best-practices`**: Universal clean code rules and guard clauses.
 - **`error-handling-logging`**: Structured `AppError` and `ActionResponse`.
 - **`valibot-validation`**: Domain input/output validation.
+- **`external-service-adapters`**: Standardized domain ports, vendor SDK wrappers, and adapters for third-party services.

package/skills/controller-orchestration-queues/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: controller-orchestration-queues
+description: Strict orchestration standards for Controllers, atomic Actions, database Transactions, and background Queue Adapters (Cloudflare Queues, BullMQ, AWS SQS, In-Memory). Mandates that Actions do only ONE atomic thing, while Controllers sequence multiple actions, manage transactions, or dispatch async jobs. Enforces Queue Workers as slim controllers. TRIGGER when orchestrating multi-step workflows, handling DB transactions across actions, dispatching background tasks, or designing queue consumers.
+---
+
+# Controller Action Orchestration, Transactions & Queue Adapters
+
+Architectural standard establishing strict separation of concerns between **Atomic Actions** and **Orchestration Controllers / Queue Workers**.
+
+---
+
+## 1. The Core Architectural Law
+
+1. **Actions Do Exactly ONE Atomic Thing**:
+   - Pure single responsibility. Example: `createOrderAction`, `chargeCardAction`, `sendOrderEmailAction`.
+   - Actions NEVER orchestrate other sibling actions or dispatch unrelated background jobs directly.
+2. **Controllers are Orchestrators**:
+   - HTTP route handlers and RPC controllers validate inputs, sequence actions, wrap transactional DB boundaries (`withTransaction`), and dispatch background jobs via `QueuePort`.
+3. **Queue Workers are Slim Controllers**:
+   - A queue worker message handler behaves like an HTTP controller: parses payload and delegates to atomic actions.
+
+---
+
+## 2. Directory Layout
+
+```text
+src/
+├── actions/
+│   ├── orders/
+│   │   ├── create-order.action.ts          # Atomic insert order (<70 lines)
+│   │   └── update-order-status.action.ts   # Atomic update status (<60 lines)
+│   └── billing/
+│       └── charge-card.action.ts           # Atomic payment charge (<70 lines)
+├── controllers/
+│   └── orders/
+│       └── checkout.controller.ts         # Orchestrates actions + Queue (<90 lines)
+├── domains/
+│   └── queue/
+│       ├── queue.port.ts                   # Domain interface for dispatching (<40 lines)
+│       └── queue-message.types.ts          # Strongly typed queue messages (<50 lines)
+└── infrastructure/
+    ├── adapters/
+    │   └── queue/
+    │       ├── cloudflare-queues.adapter.ts # Cloudflare Queues adapter (<80 lines)
+    │       ├── bullmq-queues.adapter.ts     # Redis / BullMQ adapter (<80 lines)
+    │       ├── sqs-queues.adapter.ts        # AWS SQS adapter (<80 lines)
+    │       └── memory-queues.adapter.ts     # In-memory testing queue (<60 lines)
+    └── workers/
+        └── order-events.worker.ts          # Slim worker invoking actions (<80 lines)
+```
+
+---
+
+## 3. Domain Queue Contract (`src/domains/queue/queue.port.ts`)
+
+```ts
+export interface QueueJob<TData = unknown> {
+  id?: string;
+  name: string;
+  data: TData;
+  delaySeconds?: number;
+}
+
+export interface QueuePort {
+  dispatch<T>(job: QueueJob<T>): Promise<{ jobId: string }>;
+  dispatchBatch<T>(jobs: QueueJob<T>[]): Promise<{ count: number }>;
+}
+```
+
+---
+
+## 4. Orchestration Controller Pattern
+
+```ts
+// src/controllers/orders/checkout.controller.ts
+import type { Context } from "hono";
+import type { QueuePort } from "@/domains/queue/queue.port";
+import { createOrderAction } from "@/actions/orders/create-order.action";
+import { chargeCardAction } from "@/actions/billing/charge-card.action";
+import { db, withTransaction } from "@/infrastructure/db/connection";
+
+export async function checkoutController(c: Context, queue: QueuePort) {
+  const payload = c.get("validatedJson");
+  const actor = c.get("actor");
+
+  // Step 1: Charge card (external side-effect, kept outside DB transaction)
+  const charge = await chargeCardAction(payload.paymentMethodId, payload.amount);
+
+  // Step 2: Atomic DB Transaction for local entity creation
+  const order = await withTransaction(db, async (tx) => {
+    return createOrderAction(tx, { actorId: actor.id, amount: payload.amount, chargeId: charge.id });
+  });
+
+  // Step 3: Dispatch async post-processing via Queue
+  await queue.dispatch({
+    name: "orders.post-checkout",
+    data: { orderId: order.id, customerEmail: actor.email },
+  });
+
+  return c.json({ orderId: order.id, status: "confirmed" }, 201);
+}
+```
+
+---
+
+## 5. Detailed Adapters & Workers Reference
+
+For real implementations of Cloudflare Queues, BullMQ, AWS SQS, and In-Memory Queue adapters, consult:
+- `references/controller-queue-examples.md`

package/skills/controller-orchestration-queues/references/controller-queue-examples.md

@@ -0,0 +1,115 @@
+# Implementation Reference: Controller Orchestration & Queue Adapters
+
+Real-world queue adapters (Cloudflare Queues, BullMQ, AWS SQS, In-Memory) and Slim Worker controllers.
+
+---
+
+## 1. Cloudflare Queues Adapter
+
+```ts
+// src/infrastructure/adapters/queue/cloudflare-queues.adapter.ts
+import type { QueuePort, QueueJob } from "@/domains/queue/queue.port";
+import { AppError } from "@/errors/app-error";
+
+export class CloudflareQueueAdapter implements QueuePort {
+  constructor(private queue: Queue) {}
+
+  async dispatch<T>(job: QueueJob<T>): Promise<{ jobId: string }> {
+    try {
+      await this.queue.send(job, { delaySeconds: job.delaySeconds });
+      return { jobId: job.id ?? crypto.randomUUID() };
+    } catch (err) {
+      throw new AppError({ message: "Error al encolar mensaje en Cloudflare Queues.", statusCode: 502, cause: err });
+    }
+  }
+
+  async dispatchBatch<T>(jobs: QueueJob<T>[]): Promise<{ count: number }> {
+    await this.queue.sendBatch(jobs.map((j) => ({ body: j, delaySeconds: j.delaySeconds })));
+    return { count: jobs.length };
+  }
+}
+```
+
+---
+
+## 2. BullMQ (Redis) Adapter
+
+```ts
+// src/infrastructure/adapters/queue/bullmq-queues.adapter.ts
+import { Queue as BullQueue } from "bullmq";
+import type { QueuePort, QueueJob } from "@/domains/queue/queue.port";
+import { AppError } from "@/errors/app-error";
+
+export class BullMQAdapter implements QueuePort {
+  constructor(private bullQueue: BullQueue) {}
+
+  async dispatch<T>(job: QueueJob<T>): Promise<{ jobId: string }> {
+    try {
+      const bJob = await this.bullQueue.add(job.name, job.data, {
+        jobId: job.id,
+        delay: job.delaySeconds ? job.delaySeconds * 1000 : undefined,
+      });
+      return { jobId: String(bJob.id) };
+    } catch (err) {
+      throw new AppError({ message: "Error al enviar trabajo a BullMQ.", statusCode: 502, cause: err });
+    }
+  }
+
+  async dispatchBatch<T>(jobs: QueueJob<T>[]): Promise<{ count: number }> {
+    await this.bullQueue.addBulk(
+      jobs.map((j) => ({
+        name: j.name,
+        data: j.data,
+        opts: { jobId: j.id, delay: j.delaySeconds ? j.delaySeconds * 1000 : undefined },
+      }))
+    );
+    return { count: jobs.length };
+  }
+}
+```
+
+---
+
+## 3. In-Memory Queue Adapter (Testing Fake)
+
+```ts
+// src/infrastructure/adapters/queue/memory-queues.adapter.ts
+import type { QueuePort, QueueJob } from "@/domains/queue/queue.port";
+
+export class MemoryQueueAdapter implements QueuePort {
+  public jobs: QueueJob[] = [];
+
+  async dispatch<T>(job: QueueJob<T>): Promise<{ jobId: string }> {
+    const id = job.id ?? `job_${this.jobs.length + 1}`;
+    this.jobs.push({ ...job, id });
+    return { jobId: id };
+  }
+
+  async dispatchBatch<T>(jobs: QueueJob<T>[]): Promise<{ count: number }> {
+    for (const job of jobs) {
+      await this.dispatch(job);
+    }
+    return { count: jobs.length };
+  }
+}
+```
+
+---
+
+## 4. Slim Queue Worker Controller Pattern
+
+```ts
+// src/infrastructure/workers/order-events.worker.ts
+import { sendOrderEmailAction } from "@/actions/email/send-order-email.action";
+import { syncCrmAction } from "@/actions/crm/sync-crm.action";
+import { logger } from "@/infrastructure/logger/app-logger";
+
+export async function handleOrderQueueMessage(messageBody: { name: string; data: { orderId: string; customerEmail: string } }) {
+  logger.info("Procesando evento de orden", { jobName: messageBody.name, orderId: messageBody.data.orderId });
+
+  if (messageBody.name === "orders.post-checkout") {
+    await sendOrderEmailAction(messageBody.data.customerEmail, messageBody.data.orderId);
+    await syncCrmAction(messageBody.data.orderId);
+  }
+}
+```

package/skills/env-feature-flags/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: env-feature-flags
+description: Architectural standards for fail-fast environment validation with Valibot and decoupled Feature Flags wrappers with swappable adapters (PostHog, LaunchDarkly, Unleash, In-Memory). Guarantees that applications crash at boot time on invalid config and allows toggling features without coupling code to vendor SDKs. TRIGGER when reading environment variables, structuring process.env, configuring feature flags, or running A/B experiments.
+---
+
+# Fail-Fast Environment Validation & Feature Flags Adapters
+
+Opinionated architectural standard combining **Fail-Fast Environment Schema Validation** (using Valibot) and **Feature Flags Adapters** (PostHog, LaunchDarkly, In-Memory).
+
+---
+
+## 1. Architectural Invariants
+
+1. **Fail-Fast at Startup**:
+   - Environment variables must be validated on application boot. If a required secret or URL is missing or malformed, the process exits immediately with a clean diagnostic message.
+   - Raw `process.env` is NEVER accessed directly inside business actions or controllers. All code imports the strongly typed `env` singleton.
+2. **Feature Flags as a Domain Port**:
+   - Business actions evaluate feature availability through `FeatureFlagPort`.
+   - Vendor SDKs (PostHog, LaunchDarkly, Unleash) remain isolated inside infrastructure adapters.
+
+---
+
+## 2. Directory Layout
+
+```text
+src/
+├── config/
+│   └── env.ts                              # Fail-fast Valibot environment parser (<70 lines)
+├── domains/
+│   └── feature-flags/
+│       ├── feature-flag.port.ts            # Domain interface for flags (<40 lines)
+│       └── flag-keys.ts                    # Strongly typed flag registry (<30 lines)
+└── infrastructure/
+    └── adapters/
+        └── feature-flags/
+            ├── posthog-flags.adapter.ts    # PostHog implementation (<70 lines)
+            ├── launchdarkly-flags.adapter.ts # LaunchDarkly implementation (<70 lines)
+            └── memory-flags.adapter.ts     # In-memory testing flags fake (<50 lines)
+```
+
+---
+
+## 3. Fail-Fast Environment Config (`src/config/env.ts`)
+
+```ts
+import * as v from "valibot";
+
+const EnvSchema = v.object({
+  NODE_ENV: v.fallback(v.picklist(["development", "production", "test"]), "development"),
+  PORT: v.fallback(v.pipe(v.string(), v.transform(Number)), 3000),
+  DATABASE_URL: v.pipe(v.string(), v.url("DATABASE_URL debe ser una URL válida.")),
+  API_SECRET_KEY: v.pipe(v.string(), v.minLength(32, "API_SECRET_KEY requiere al menos 32 caracteres.")),
+});
+
+function loadEnv() {
+  const result = v.safeParse(EnvSchema, process.env);
+  if (!result.success) {
+    console.error("❌ Error fatal en variables de entorno:");
+    for (const issue of result.issues) {
+      console.error(`  - ${issue.path?.[0]?.key}: ${issue.message}`);
+    }
+    process.exit(1);
+  }
+  return result.output;
+}
+
+export const env = loadEnv();
+```
+
+---
+
+## 4. Feature Flag Port (`src/domains/feature-flags/feature-flag.port.ts`)
+
+```ts
+export type FeatureFlagKey = "new-checkout-flow" | "ai-copilot" | "export-pdf";
+
+export interface FeatureFlagEvaluationContext {
+  distinctId: string;
+  organizationId?: string;
+  properties?: Record<string, unknown>;
+}
+
+export interface FeatureFlagPort {
+  isEnabled(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<boolean>;
+  getVariant<T = string>(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<T | null>;
+}
+```
+
+---
+
+## 5. Detailed Adapters Reference
+
+For real implementations of PostHog, LaunchDarkly, and In-Memory Feature Flag adapters, see:
+- `references/env-feature-flags-examples.md`

package/skills/env-feature-flags/references/env-feature-flags-examples.md

@@ -0,0 +1,93 @@
+# Implementation Reference: Env & Feature Flag Adapters
+
+Production implementations of PostHog, LaunchDarkly, and In-Memory testing feature flag adapters.
+
+---
+
+## 1. PostHog Feature Flags Adapter (`posthog-node`)
+
+```ts
+// src/infrastructure/adapters/feature-flags/posthog-flags.adapter.ts
+import { PostHog } from "posthog-node";
+import type { FeatureFlagPort, FeatureFlagKey, FeatureFlagEvaluationContext } from "@/domains/feature-flags/feature-flag.port";
+
+export class PostHogFeatureFlagAdapter implements FeatureFlagPort {
+  constructor(private client: PostHog) {}
+
+  async isEnabled(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<boolean> {
+    const distinctId = context?.distinctId ?? "anonymous";
+    const res = await this.client.isFeatureEnabled(key, distinctId, {
+      personProperties: context?.properties,
+    });
+    return Boolean(res);
+  }
+
+  async getVariant<T = string>(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<T | null> {
+    const distinctId = context?.distinctId ?? "anonymous";
+    const variant = await this.client.getFeatureFlag(key, distinctId, {
+      personProperties: context?.properties,
+    });
+    return (variant as T) ?? null;
+  }
+}
+```
+
+---
+
+## 2. LaunchDarkly Feature Flags Adapter (`@launchdarkly/node-server-sdk`)
+
+```ts
+// src/infrastructure/adapters/feature-flags/launchdarkly-flags.adapter.ts
+import type { LDClient } from "@launchdarkly/node-server-sdk";
+import type { FeatureFlagPort, FeatureFlagKey, FeatureFlagEvaluationContext } from "@/domains/feature-flags/feature-flag.port";
+
+export class LaunchDarklyFeatureFlagAdapter implements FeatureFlagPort {
+  constructor(private client: LDClient) {}
+
+  async isEnabled(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<boolean> {
+    const user = {
+      key: context?.distinctId ?? "anonymous",
+      custom: { organizationId: context?.organizationId, ...context?.properties },
+    };
+    return this.client.variation(key, user, false);
+  }
+
+  async getVariant<T = string>(key: FeatureFlagKey, context?: FeatureFlagEvaluationContext): Promise<T | null> {
+    const user = {
+      key: context?.distinctId ?? "anonymous",
+      custom: { organizationId: context?.organizationId, ...context?.properties },
+    };
+    return this.client.variation(key, user, null);
+  }
+}
+```
+
+---
+
+## 3. In-Memory Testing Flags Adapter
+
+```ts
+// src/infrastructure/adapters/feature-flags/memory-flags.adapter.ts
+import type { FeatureFlagPort, FeatureFlagKey } from "@/domains/feature-flags/feature-flag.port";
+
+export class MemoryFeatureFlagAdapter implements FeatureFlagPort {
+  private flags = new Map<string, boolean>();
+  private variants = new Map<string, unknown>();
+
+  setFlag(key: FeatureFlagKey, enabled: boolean): void {
+    this.flags.set(key, enabled);
+  }
+
+  setVariant(key: FeatureFlagKey, variant: unknown): void {
+    this.variants.set(key, variant);
+  }
+
+  async isEnabled(key: FeatureFlagKey): Promise<boolean> {
+    return this.flags.get(key) ?? false;
+  }
+
+  async getVariant<T = string>(key: FeatureFlagKey): Promise<T | null> {
+    return (this.variants.get(key) as T) ?? null;
+  }
+}
+```

package/skills/external-service-adapters/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: external-service-adapters
+description: Standardized wrapper & adapter architecture for external third-party services (payment gateways, transactional email, SMS, storage, AI providers). Enforces pure domain ports, isolated vendor SDK wrappers, unified input/output contracts, and interchangeable adapters. TRIGGER when integrating or refactoring any external API, payment provider (Stripe, MercadoPago), email service (Resend, SES, SMTP, Cloudflare), webhook, or cloud provider.
+---
+
+# External Service Adapters & Wrappers
+
+Architectural pattern for standardizing third-party integrations (payments, emails, SMS, cloud storage, AI models) using the **Adapter Pattern** and **SDK Wrappers** to prevent vendor lock-in and keep business actions decoupled.
+
+---
+
+## 1. Architectural Distinction: Wrapper vs. Adapter
+
+| Component | Responsibility | Location | Dependencies |
+| :--- | :--- | :--- | :--- |
+| **Domain Port (Interface)** | Defines the contract needed by our business domain (pure domain types). | `src/domains/<domain>/` | Zero external SDKs |
+| **Vendor Wrapper (Client)** | Encapsulates vendor SDK initialization, raw authentication, and direct API calls. | `src/infrastructure/<vendor>/` | Vendor SDK / HTTP client |
+| **Service Adapter** | Implements the Domain Port by calling the Vendor Wrapper and translating inputs/outputs. | `src/infrastructure/adapters/` | Port + Vendor Wrapper |
+| **Business Action** | Executes use case logic depending ONLY on the Domain Port. | `src/actions/<domain>/` | Domain Port only |
+
+---
+
+## 2. The 4 Non-Negotiable Rules
+
+1. **Actions Depend on Ports, Never Vendors**:
+   - Business actions must type-hint the domain port interface (`EmailSender`, `PaymentGateway`), never `Stripe`, `Resend`, or `aws-sdk`.
+2. **Standardized Domain Contracts**:
+   - Input payloads and return values must use application domain types (e.g., `SendEmailInput`, `SendEmailResult`, `PaymentChargeResult`).
+   - Third-party SDK response shapes must never leak into actions or domain modules.
+3. **Isolate SDK Quirks in Wrappers**:
+   - HTTP errors, retries, header formatting, and API keys stay inside the vendor wrapper.
+   - Exceptions are converted into standardized application errors (`AppError`) or `ActionResponse` failures.
+4. **Interchangeability via Factory or Dependency Injection**:
+   - Swapping from `Resend` to `AWS SES` or `SMTP` requires only injecting a different adapter without altering a single line of business logic.
+
+---
+
+## 3. Directory Layout
+
+```text
+src/
+├── actions/
+│   └── billing/
+│       └── process-payment.action.ts       # Consumes PaymentGateway port (<80 lines)
+├── domains/
+│   ├── billing/
+│   │   ├── payment-gateway.port.ts         # Domain interface contract (<40 lines)
+│   │   └── billing.types.ts                # ChargeInput, ChargeResult (<50 lines)
+│   └── email/
+│       ├── email-sender.port.ts            # Domain interface contract (<40 lines)
+│       └── email.types.ts                  # SendEmailInput, SendEmailResult (<50 lines)
+└── infrastructure/
+    ├── adapters/
+    │   ├── email/
+    │   │   ├── resend-email.adapter.ts     # Implements EmailSender (<80 lines)
+    │   │   ├── ses-email.adapter.ts        # Implements EmailSender (<80 lines)
+    │   │   └── smtp-email.adapter.ts       # Implements EmailSender (<80 lines)
+    │   └── payment/
+    │       ├── stripe-payment.adapter.ts   # Implements PaymentGateway (<90 lines)
+    │       └── mercadopago-payment.adapter.ts # Implements PaymentGateway (<90 lines)
+    └── wrappers/
+        ├── aws/
+        │   └── ses-client.wrapper.ts       # Raw AWS SES client wrapper (<70 lines)
+        ├── resend/
+        │   └── resend-client.wrapper.ts    # Raw Resend SDK wrapper (<60 lines)
+        └── stripe/
+            └── stripe-client.wrapper.ts    # Raw Stripe SDK wrapper (<60 lines)
+```
+
+---
+
+## 4. Implementation Blueprint (Email Example)
+
+### Step 1: Pure Domain Port (`src/domains/email/email-sender.port.ts`)
+```ts
+export interface SendEmailPayload {
+  to: string | string[];
+  subject: string;
+  htmlContent: string;
+  from?: string;
+  replyTo?: string;
+}
+
+export interface SendEmailOutput {
+  id: string;
+  delivered: boolean;
+  timestamp: Date;
+}
+
+export interface EmailSenderPort {
+  sendEmail(payload: SendEmailPayload): Promise<SendEmailOutput>;
+}
+```
+
+### Step 2: Vendor Wrapper (`src/infrastructure/wrappers/resend/resend.wrapper.ts`)
+```ts
+import { Resend } from "resend";
+
+export class ResendWrapper {
+  private readonly client: Resend;
+
+  constructor(apiKey: string) {
+    this.client = new Resend(apiKey);
+  }
+
+  async send(params: { from: string; to: string[]; subject: string; html: string }) {
+    return this.client.emails.send(params);
+  }
+}
+```
+
+### Step 3: Domain Adapter (`src/infrastructure/adapters/email/resend-email.adapter.ts`)
+```ts
+import type { EmailSenderPort, SendEmailPayload, SendEmailOutput } from "@/domains/email/email-sender.port";
+import type { ResendWrapper } from "@/infrastructure/wrappers/resend/resend.wrapper";
+import { AppError } from "@/errors/app-error";
+
+export class ResendEmailAdapter implements EmailSenderPort {
+  constructor(
+    private readonly wrapper: ResendWrapper,
+    private readonly defaultFrom: string
+  ) {}
+
+  async sendEmail(payload: SendEmailPayload): Promise<SendEmailOutput> {
+    const recipients = Array.isArray(payload.to) ? payload.to : [payload.to];
+    const { data, error } = await this.wrapper.send({
+      from: payload.from ?? this.defaultFrom,
+      to: recipients,
+      subject: payload.subject,
+      html: payload.htmlContent,
+    });
+
+    if (error || !data) {
+      throw new AppError({
+        message: `Error al enviar correo vía Resend: ${error?.message ?? "desconocido"}`,
+        statusCode: 502,
+      });
+    }
+
+    return { id: data.id, delivered: true, timestamp: new Date() };
+  }
+}
+```
+
+---
+
+## 5. Reference Guides
+- Detailed concrete implementations for **Email** (SMTP, Resend, AWS SES, Cloudflare Email) and **Payment Gateways** (Stripe, MercadoPago) can be found in `references/email-and-payment-examples.md`.