feat(media): full Clean Architecture scaffold

Media is now a complete vertical-feature package mirroring auth/blog
structure: entities (models + errors), application (repositories +
use-cases), infrastructure (real Payload-backed + mock siblings),
interface-adapters (per-use-case controllers), DI (symbols + module +
container + bind-production), integrations/api (mediaRouter), factory,
contract suite, and feature integration tests.

Wired into:
- packages/core-api/src/root.ts (added `media: mediaRouter`)
- apps/web-next/src/server/bind-production.ts (calls bindProductionMedia)
- tsconfig.base.json (added @repo/media/api and ./di/bind-production aliases)

56 new tests in @repo/media (13 test files); core-api router test updated
to assert media. procedures. All 26 turbo tasks green.

Refactor log: §2, §4.1, §4.2, §5.1, §6.1
Spec: §6.5

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

packages/media/package.json

@@ -5,7 +5,9 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./cms": "./src/integrations/cms/index.ts"
+    "./cms": "./src/integrations/cms/index.ts",
+    "./api": "./src/integrations/api/index.ts",
+    "./di/bind-production": "./src/di/bind-production.ts"
   },
   "scripts": {
     "build": "tsc --noEmit",
@@ -14,12 +16,18 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "payload": "^3.14.0"
+    "@repo/core-shared": "workspace:*",
+    "@trpc/server": "^11.0.0",
+    "inversify": "^6.2.0",
+    "payload": "^3.14.0",
+    "reflect-metadata": "^0.2.2",
+    "zod": "^3.24.0"
   },
   "devDependencies": {
     "@repo/core-eslint": "workspace:*",
     "@repo/core-testing": "workspace:*",
     "@repo/core-typescript": "workspace:*",
+    "@types/node": "^22.0.0",
     "vitest": "^3.1.0"
   }
 }

packages/media/src/__contracts__/media-repository.contract.ts

@@ -0,0 +1,61 @@
+import { it, expect, beforeEach } from "vitest";
+import { defineContractSuite } from "@repo/core-testing/contract";
+import type { IMediaRepository } from "../application/repositories/media.repository.interface.js";
+import { mediaFactory } from "../__factories__/media.factory.js";
+
+export const mediaRepositoryContract =
+  defineContractSuite<IMediaRepository>(
+    "IMediaRepository",
+    ({ buildSubject }) => {
+      let repo: IMediaRepository;
+
+      beforeEach(async () => {
+        mediaFactory.reset();
+        repo = await buildSubject();
+      });
+
+      // --- getMedia ---
+
+      it("getMedia returns undefined for a missing id", async () => {
+        const result = await repo.getMedia("does-not-exist");
+        expect(result).toBeUndefined();
+      });
+
+      // --- listMedia ---
+
+      it("listMedia returns empty array when no media exists", async () => {
+        const result = await repo.listMedia();
+        expect(result).toHaveLength(0);
+      });
+
+      // --- deleteMedia ---
+
+      it("deleteMedia removes the item so getMedia returns undefined", async () => {
+        const seed = mediaFactory.build({ id: "contract-1" });
+        // @ts-expect-error _store is a test helper on MockMediaRepository
+        if (typeof repo._store === "function") {
+          // @ts-expect-error _store is a test helper
+          await repo._store(seed);
+        }
+        await repo.deleteMedia("contract-1");
+        const result = await repo.getMedia("contract-1");
+        expect(result).toBeUndefined();
+      });
+
+      it("listMedia with limit returns at most limit items", async () => {
+        // Only verifiable on mock; for real impl this checks the interface
+        const result = await repo.listMedia({ limit: 0 });
+        expect(Array.isArray(result)).toBe(true);
+      });
+
+      it("listMedia with offset skips items", async () => {
+        const result = await repo.listMedia({ offset: 100 });
+        expect(Array.isArray(result)).toBe(true);
+      });
+
+      it("getMedia returns undefined for empty string id", async () => {
+        const result = await repo.getMedia("");
+        expect(result).toBeUndefined();
+      });
+    },
+  );

packages/media/src/__factories__/index.ts

@@ -1 +1,2 @@
-export { mediaFactory, type Media } from "./media.factory.js";
+export { mediaFactory } from "./media.factory.js";
+export type { Media } from "../entities/models/media.js";

packages/media/src/__factories__/media.factory.ts

@@ -1,13 +1,5 @@
 import { defineFactory } from "@repo/core-testing/factory";
-
-export interface Media {
-  id: string;
-  alt: string;
-  url: string;
-  filename: string;
-  mimeType: string;
-  filesize: number;
-}
+import type { Media } from "../entities/models/media";
 
 export const mediaFactory = defineFactory<Media>(({ sequence }) => ({
   id: `media-${sequence}`,

packages/media/src/application/repositories/media.repository.interface.ts

@@ -0,0 +1,7 @@
+import type { Media } from "../../entities/models/media";
+
+export interface IMediaRepository {
+  getMedia(id: string): Promise<Media | undefined>;
+  listMedia(opts?: { limit?: number; offset?: number }): Promise<Media[]>;
+  deleteMedia(id: string): Promise<void>;
+}

packages/media/src/application/use-cases/delete-media.use-case.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from "vitest";
+import { deleteMediaUseCase } from "@/application/use-cases/delete-media.use-case";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import { MediaNotFoundError } from "@/entities/errors/media";
+import { mediaFactory } from "@/__factories__/media.factory";
+
+describe("deleteMediaUseCase", () => {
+  it("deletes media when found", async () => {
+    const repo = new MockMediaRepository();
+    const seed = mediaFactory.build({ id: "m-1" });
+    await repo._store(seed);
+
+    const useCase = deleteMediaUseCase(repo);
+    await useCase({ id: "m-1" });
+
+    const result = await repo.getMedia("m-1");
+    expect(result).toBeUndefined();
+  });
+
+  it("throws MediaNotFoundError when id does not exist", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = deleteMediaUseCase(repo);
+
+    await expect(useCase({ id: "missing" })).rejects.toThrow(MediaNotFoundError);
+  });
+});

packages/media/src/application/use-cases/delete-media.use-case.ts

@@ -0,0 +1,14 @@
+import { MediaNotFoundError } from "../../entities/errors/media";
+import type { IMediaRepository } from "../repositories/media.repository.interface";
+
+export type IDeleteMediaUseCase = ReturnType<typeof deleteMediaUseCase>;
+
+export const deleteMediaUseCase =
+  (mediaRepository: IMediaRepository) =>
+  async (input: { id: string }): Promise<void> => {
+    const existing = await mediaRepository.getMedia(input.id);
+    if (!existing) {
+      throw new MediaNotFoundError(`Media with id "${input.id}" not found`);
+    }
+    await mediaRepository.deleteMedia(input.id);
+  };

packages/media/src/application/use-cases/get-media.use-case.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from "vitest";
+import { getMediaUseCase } from "@/application/use-cases/get-media.use-case";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import { MediaNotFoundError } from "@/entities/errors/media";
+import { mediaFactory } from "@/__factories__/media.factory";
+
+describe("getMediaUseCase", () => {
+  it("returns media when found", async () => {
+    const repo = new MockMediaRepository();
+    const seed = mediaFactory.build({ id: "m-1" });
+    await repo._store(seed);
+
+    const useCase = getMediaUseCase(repo);
+    const result = await useCase({ id: "m-1" });
+
+    expect(result.id).toBe("m-1");
+    expect(result.alt).toBe(seed.alt);
+  });
+
+  it("throws MediaNotFoundError when id does not exist", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = getMediaUseCase(repo);
+
+    await expect(useCase({ id: "missing" })).rejects.toThrow(MediaNotFoundError);
+  });
+});

packages/media/src/application/use-cases/get-media.use-case.ts

@@ -0,0 +1,15 @@
+import { MediaNotFoundError } from "../../entities/errors/media";
+import type { Media } from "../../entities/models/media";
+import type { IMediaRepository } from "../repositories/media.repository.interface";
+
+export type IGetMediaUseCase = ReturnType<typeof getMediaUseCase>;
+
+export const getMediaUseCase =
+  (mediaRepository: IMediaRepository) =>
+  async (input: { id: string }): Promise<Media> => {
+    const media = await mediaRepository.getMedia(input.id);
+    if (!media) {
+      throw new MediaNotFoundError(`Media with id "${input.id}" not found`);
+    }
+    return media;
+  };

packages/media/src/application/use-cases/list-media.use-case.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from "vitest";
+import { listMediaUseCase } from "@/application/use-cases/list-media.use-case";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import { mediaFactory } from "@/__factories__/media.factory";
+
+describe("listMediaUseCase", () => {
+  it("returns empty array when no media exists", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = listMediaUseCase(repo);
+    const result = await useCase();
+    expect(result).toHaveLength(0);
+  });
+
+  it("returns all media when store has items", async () => {
+    const repo = new MockMediaRepository();
+    await repo._store(mediaFactory.build());
+    await repo._store(mediaFactory.build());
+
+    const useCase = listMediaUseCase(repo);
+    const result = await useCase();
+    expect(result).toHaveLength(2);
+  });
+
+  it("respects limit and offset options", async () => {
+    const repo = new MockMediaRepository();
+    for (let i = 0; i < 5; i++) {
+      await repo._store(mediaFactory.build());
+    }
+
+    const useCase = listMediaUseCase(repo);
+    const result = await useCase({ limit: 2, offset: 1 });
+    expect(result).toHaveLength(2);
+  });
+});

packages/media/src/application/use-cases/list-media.use-case.ts

@@ -0,0 +1,10 @@
+import type { Media } from "../../entities/models/media";
+import type { IMediaRepository } from "../repositories/media.repository.interface";
+
+export type IListMediaUseCase = ReturnType<typeof listMediaUseCase>;
+
+export const listMediaUseCase =
+  (mediaRepository: IMediaRepository) =>
+  async (opts?: { limit?: number; offset?: number }): Promise<Media[]> => {
+    return mediaRepository.listMedia(opts);
+  };

packages/media/src/di/bind-production.ts

@@ -0,0 +1,13 @@
+import type { SanitizedConfig } from "payload";
+import { mediaContainer } from "./container";
+import { MEDIA_SYMBOLS } from "./symbols";
+import { MediaRepository } from "../infrastructure/repositories/media.repository";
+
+export function bindProductionMedia(config: SanitizedConfig): void {
+  if (mediaContainer.isBound(MEDIA_SYMBOLS.IMediaRepository)) {
+    mediaContainer.unbind(MEDIA_SYMBOLS.IMediaRepository);
+  }
+  mediaContainer
+    .bind(MEDIA_SYMBOLS.IMediaRepository)
+    .toConstantValue(new MediaRepository(config));
+}

packages/media/src/di/container.test.ts

@@ -0,0 +1,52 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mediaContainer } from "@/di/container";
+import { MEDIA_SYMBOLS } from "@/di/symbols";
+import { MediaModule } from "@/di/module";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import type { IMediaRepository } from "@/application/repositories/media.repository.interface";
+
+describe("mediaContainer", () => {
+  beforeEach(() => {
+    mediaContainer.unbindAll();
+    mediaContainer.load(MediaModule);
+  });
+
+  afterEach(() => {
+    mediaContainer.unbindAll();
+  });
+
+  it("resolves IMediaRepository to MockMediaRepository by default binding", () => {
+    const repo = mediaContainer.get<IMediaRepository>(MEDIA_SYMBOLS.IMediaRepository);
+    expect(repo).toBeInstanceOf(MockMediaRepository);
+  });
+
+  it("resolves IGetMediaController as a function", () => {
+    const ctrl = mediaContainer.get(MEDIA_SYMBOLS.IGetMediaController);
+    expect(typeof ctrl).toBe("function");
+  });
+
+  it("resolves IListMediaController as a function", () => {
+    const ctrl = mediaContainer.get(MEDIA_SYMBOLS.IListMediaController);
+    expect(typeof ctrl).toBe("function");
+  });
+
+  it("resolves IDeleteMediaController as a function", () => {
+    const ctrl = mediaContainer.get(MEDIA_SYMBOLS.IDeleteMediaController);
+    expect(typeof ctrl).toBe("function");
+  });
+
+  it("resolves IGetMediaUseCase as a function", () => {
+    const uc = mediaContainer.get(MEDIA_SYMBOLS.IGetMediaUseCase);
+    expect(typeof uc).toBe("function");
+  });
+
+  it("resolves IListMediaUseCase as a function", () => {
+    const uc = mediaContainer.get(MEDIA_SYMBOLS.IListMediaUseCase);
+    expect(typeof uc).toBe("function");
+  });
+
+  it("resolves IDeleteMediaUseCase as a function", () => {
+    const uc = mediaContainer.get(MEDIA_SYMBOLS.IDeleteMediaUseCase);
+    expect(typeof uc).toBe("function");
+  });
+});

packages/media/src/di/container.ts

@@ -0,0 +1,6 @@
+import "reflect-metadata";
+import { Container } from "inversify";
+import { MediaModule } from "./module";
+
+export const mediaContainer = new Container({ defaultScope: "Singleton" });
+mediaContainer.load(MediaModule);

packages/media/src/di/module.ts

@@ -0,0 +1,69 @@
+import { ContainerModule, type interfaces } from "inversify";
+
+import type { IMediaRepository } from "../application/repositories/media.repository.interface";
+import { MockMediaRepository } from "../infrastructure/repositories/media.repository.mock";
+import {
+  getMediaUseCase,
+  type IGetMediaUseCase,
+} from "../application/use-cases/get-media.use-case";
+import {
+  listMediaUseCase,
+  type IListMediaUseCase,
+} from "../application/use-cases/list-media.use-case";
+import {
+  deleteMediaUseCase,
+  type IDeleteMediaUseCase,
+} from "../application/use-cases/delete-media.use-case";
+import {
+  getMediaController,
+  type IGetMediaController,
+} from "../interface-adapters/controllers/get-media.controller";
+import {
+  listMediaController,
+  type IListMediaController,
+} from "../interface-adapters/controllers/list-media.controller";
+import {
+  deleteMediaController,
+  type IDeleteMediaController,
+} from "../interface-adapters/controllers/delete-media.controller";
+import { MEDIA_SYMBOLS } from "./symbols";
+
+export const MediaModule = new ContainerModule((bind: interfaces.Bind) => {
+  bind<IMediaRepository>(MEDIA_SYMBOLS.IMediaRepository).to(MockMediaRepository);
+
+  bind<IGetMediaUseCase>(MEDIA_SYMBOLS.IGetMediaUseCase).toDynamicValue((ctx) =>
+    getMediaUseCase(
+      ctx.container.get<IMediaRepository>(MEDIA_SYMBOLS.IMediaRepository),
+    ),
+  );
+
+  bind<IListMediaUseCase>(MEDIA_SYMBOLS.IListMediaUseCase).toDynamicValue((ctx) =>
+    listMediaUseCase(
+      ctx.container.get<IMediaRepository>(MEDIA_SYMBOLS.IMediaRepository),
+    ),
+  );
+
+  bind<IDeleteMediaUseCase>(MEDIA_SYMBOLS.IDeleteMediaUseCase).toDynamicValue((ctx) =>
+    deleteMediaUseCase(
+      ctx.container.get<IMediaRepository>(MEDIA_SYMBOLS.IMediaRepository),
+    ),
+  );
+
+  bind<IGetMediaController>(MEDIA_SYMBOLS.IGetMediaController).toDynamicValue((ctx) =>
+    getMediaController(
+      ctx.container.get<IGetMediaUseCase>(MEDIA_SYMBOLS.IGetMediaUseCase),
+    ),
+  );
+
+  bind<IListMediaController>(MEDIA_SYMBOLS.IListMediaController).toDynamicValue((ctx) =>
+    listMediaController(
+      ctx.container.get<IListMediaUseCase>(MEDIA_SYMBOLS.IListMediaUseCase),
+    ),
+  );
+
+  bind<IDeleteMediaController>(MEDIA_SYMBOLS.IDeleteMediaController).toDynamicValue((ctx) =>
+    deleteMediaController(
+      ctx.container.get<IDeleteMediaUseCase>(MEDIA_SYMBOLS.IDeleteMediaUseCase),
+    ),
+  );
+});

packages/media/src/di/symbols.ts

@@ -0,0 +1,11 @@
+export const MEDIA_SYMBOLS = {
+  IMediaRepository: Symbol.for("media:IMediaRepository"),
+  // Use cases
+  IGetMediaUseCase: Symbol.for("media:IGetMediaUseCase"),
+  IListMediaUseCase: Symbol.for("media:IListMediaUseCase"),
+  IDeleteMediaUseCase: Symbol.for("media:IDeleteMediaUseCase"),
+  // Controllers
+  IGetMediaController: Symbol.for("media:IGetMediaController"),
+  IListMediaController: Symbol.for("media:IListMediaController"),
+  IDeleteMediaController: Symbol.for("media:IDeleteMediaController"),
+} as const;

packages/media/src/entities/errors/common.ts

@@ -0,0 +1,5 @@
+export class InputParseError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+  }
+}

packages/media/src/entities/errors/media.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest";
+import { MediaNotFoundError } from "@/entities/errors/media";
+
+describe("MediaNotFoundError", () => {
+  it("is an instance of Error", () => {
+    const err = new MediaNotFoundError();
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(MediaNotFoundError);
+  });
+
+  it("has default message", () => {
+    const err = new MediaNotFoundError();
+    expect(err.message).toBe("Media not found");
+  });
+
+  it("accepts a custom message", () => {
+    const err = new MediaNotFoundError("Custom message");
+    expect(err.message).toBe("Custom message");
+  });
+});

packages/media/src/entities/errors/media.ts

@@ -0,0 +1,5 @@
+export class MediaNotFoundError extends Error {
+  constructor(message = "Media not found", options?: ErrorOptions) {
+    super(message, options);
+  }
+}

packages/media/src/entities/models/media.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { mediaSchema } from "@/entities/models/media";
+
+describe("mediaSchema", () => {
+  it("parses a valid media object", () => {
+    const result = mediaSchema.parse({
+      id: "1",
+      alt: "A photo",
+      url: "https://cdn.example.com/photo.png",
+      filename: "photo.png",
+      mimeType: "image/png",
+      filesize: 1024,
+    });
+    expect(result.id).toBe("1");
+    expect(result.alt).toBe("A photo");
+  });
+
+  it("parses a media object with optional width and height", () => {
+    const result = mediaSchema.parse({
+      id: "2",
+      alt: "A photo",
+      url: "https://cdn.example.com/photo.png",
+      filename: "photo.png",
+      mimeType: "image/png",
+      filesize: 2048,
+      width: 1920,
+      height: 1080,
+    });
+    expect(result.width).toBe(1920);
+    expect(result.height).toBe(1080);
+  });
+
+  it("parses without width and height (optional)", () => {
+    const result = mediaSchema.parse({
+      id: "3",
+      alt: "Doc",
+      url: "https://cdn.example.com/doc.pdf",
+      filename: "doc.pdf",
+      mimeType: "application/pdf",
+      filesize: 512,
+    });
+    expect(result.width).toBeUndefined();
+    expect(result.height).toBeUndefined();
+  });
+
+  it("throws for missing required fields", () => {
+    expect(() =>
+      mediaSchema.parse({ id: "1", alt: "x", url: "x" }),
+    ).toThrow();
+  });
+});

packages/media/src/entities/models/media.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+export const mediaSchema = z.object({
+  id: z.string(),
+  alt: z.string(),
+  url: z.string(),
+  filename: z.string(),
+  mimeType: z.string(),
+  filesize: z.number(),
+  width: z.number().optional(),
+  height: z.number().optional(),
+});
+
+export type Media = z.infer<typeof mediaSchema>;

packages/media/src/index.ts

@@ -1 +1,4 @@
-export {};
+export type { Media } from "./entities/models/media";
+export { MediaNotFoundError } from "./entities/errors/media";
+export { InputParseError } from "./entities/errors/common";
+export type { MediaRouter } from "./integrations/api/router";

packages/media/src/infrastructure/repositories/media.repository.mock.test.ts

@@ -0,0 +1,7 @@
+import { describe } from "vitest";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import { mediaRepositoryContract } from "@/__contracts__/media-repository.contract";
+
+describe("MockMediaRepository", () => {
+  mediaRepositoryContract.run(() => new MockMediaRepository());
+});

packages/media/src/infrastructure/repositories/media.repository.mock.ts

@@ -0,0 +1,29 @@
+import "reflect-metadata";
+import { injectable } from "inversify";
+
+import type { IMediaRepository } from "../../application/repositories/media.repository.interface";
+import type { Media } from "../../entities/models/media";
+
+@injectable()
+export class MockMediaRepository implements IMediaRepository {
+  private _media: Media[] = [];
+
+  /** Test helper — seeds the in-memory store directly. */
+  async _store(media: Media): Promise<void> {
+    this._media.push(media);
+  }
+
+  async getMedia(id: string): Promise<Media | undefined> {
+    return this._media.find((m) => m.id === id);
+  }
+
+  async listMedia(opts?: { limit?: number; offset?: number }): Promise<Media[]> {
+    const offset = opts?.offset ?? 0;
+    const limit = opts?.limit ?? 50;
+    return this._media.slice(offset, offset + limit);
+  }
+
+  async deleteMedia(id: string): Promise<void> {
+    this._media = this._media.filter((m) => m.id !== id);
+  }
+}

packages/media/src/infrastructure/repositories/media.repository.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it, vi } from "vitest";
+import { MediaRepository } from "@/infrastructure/repositories/media.repository";
+import { mediaRepositoryContract } from "@/__contracts__/media-repository.contract";
+import { stubPayloadConfig } from "@repo/core-testing/payload/stub-config";
+
+// ---------------------------------------------------------------------------
+// In-memory Payload stub
+// ---------------------------------------------------------------------------
+
+function buildPayloadStub() {
+  const store = new Map<string, Record<string, unknown>>();
+
+  return {
+    find: vi.fn(
+      async ({
+        limit,
+        page,
+      }: {
+        collection: string;
+        limit?: number;
+        page?: number;
+        overrideAccess?: boolean;
+      }) => {
+        let docs = Array.from(store.values());
+        const lim = limit ?? 50;
+        const pg = page ?? 1;
+        const offset = (pg - 1) * lim;
+        docs = docs.slice(offset, offset + lim);
+        return { docs };
+      },
+    ),
+    findByID: vi.fn(
+      async ({ id }: { collection: string; id: string; overrideAccess?: boolean }) => {
+        const doc = store.get(String(id));
+        if (!doc) throw new Error(`Not found: ${id}`);
+        return doc;
+      },
+    ),
+    delete: vi.fn(
+      async ({ id }: { collection: string; id: string; overrideAccess?: boolean }) => {
+        store.delete(String(id));
+        return { id };
+      },
+    ),
+  };
+}
+
+vi.mock("payload", () => ({
+  getPayload: vi.fn(),
+}));
+
+// ---------------------------------------------------------------------------
+// Contract suite
+// ---------------------------------------------------------------------------
+
+describe("MediaRepository", () => {
+  describe("contract", () => {
+    mediaRepositoryContract.run(async () => {
+      const stub = buildPayloadStub();
+      const { getPayload } = await import("payload");
+      (getPayload as ReturnType<typeof vi.fn>).mockResolvedValue(stub);
+      return new MediaRepository(stubPayloadConfig);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Impl-specific tests: Payload doc → domain mapping
+  // -------------------------------------------------------------------------
+
+  describe("getMedia", () => {
+    it("returns undefined when Payload throws (not found)", async () => {
+      const { getPayload } = await import("payload");
+      (getPayload as ReturnType<typeof vi.fn>).mockResolvedValue({
+        findByID: vi.fn().mockRejectedValue(new Error("Not found")),
+      });
+
+      const repo = new MediaRepository(stubPayloadConfig);
+      const result = await repo.getMedia("missing-id");
+      expect(result).toBeUndefined();
+    });
+
+    it("maps Payload doc fields to domain Media", async () => {
+      const { getPayload } = await import("payload");
+      (getPayload as ReturnType<typeof vi.fn>).mockResolvedValue({
+        findByID: vi.fn().mockResolvedValue({
+          id: "p-1",
+          alt: "Test image",
+          url: "https://cdn.example.com/test.png",
+          filename: "test.png",
+          mimeType: "image/png",
+          filesize: 2048,
+          width: 800,
+          height: 600,
+        }),
+      });
+
+      const repo = new MediaRepository(stubPayloadConfig);
+      const result = await repo.getMedia("p-1");
+      expect(result?.id).toBe("p-1");
+      expect(result?.alt).toBe("Test image");
+      expect(result?.width).toBe(800);
+      expect(result?.height).toBe(600);
+    });
+  });
+
+  describe("listMedia", () => {
+    it("returns an array of mapped Media docs", async () => {
+      const { getPayload } = await import("payload");
+      (getPayload as ReturnType<typeof vi.fn>).mockResolvedValue({
+        find: vi.fn().mockResolvedValue({
+          docs: [
+            {
+              id: "m-1",
+              alt: "First",
+              url: "https://cdn.example.com/first.png",
+              filename: "first.png",
+              mimeType: "image/png",
+              filesize: 100,
+            },
+          ],
+        }),
+      });
+
+      const repo = new MediaRepository(stubPayloadConfig);
+      const result = await repo.listMedia();
+      expect(result).toHaveLength(1);
+      expect(result[0]?.id).toBe("m-1");
+    });
+  });
+});

packages/media/src/infrastructure/repositories/media.repository.ts

@@ -0,0 +1,76 @@
+import "reflect-metadata";
+import { injectable } from "inversify";
+import { getPayload } from "payload";
+import type { SanitizedConfig } from "payload";
+
+import type { IMediaRepository } from "../../application/repositories/media.repository.interface";
+import type { Media } from "../../entities/models/media";
+
+type PayloadMediaDoc = {
+  id: string | number;
+  alt?: string | null;
+  url?: string | null;
+  filename?: string | null;
+  mimeType?: string | null;
+  filesize?: number | null;
+  width?: number | null;
+  height?: number | null;
+};
+
+function mapDoc(doc: PayloadMediaDoc): Media {
+  return {
+    id: String(doc.id),
+    alt: doc.alt ?? "",
+    url: doc.url ?? "",
+    filename: doc.filename ?? "",
+    mimeType: doc.mimeType ?? "",
+    filesize: doc.filesize ?? 0,
+    ...(doc.width != null && { width: doc.width }),
+    ...(doc.height != null && { height: doc.height }),
+  };
+}
+
+@injectable()
+export class MediaRepository implements IMediaRepository {
+  private config: SanitizedConfig;
+
+  constructor(config: SanitizedConfig) {
+    this.config = config;
+  }
+
+  async getMedia(id: string): Promise<Media | undefined> {
+    const payload = await getPayload({ config: this.config });
+    try {
+      const doc = await payload.findByID({
+        collection: "media",
+        id,
+        overrideAccess: true,
+      });
+      return mapDoc(doc as PayloadMediaDoc);
+    } catch {
+      return undefined;
+    }
+  }
+
+  async listMedia(opts?: { limit?: number; offset?: number }): Promise<Media[]> {
+    const payload = await getPayload({ config: this.config });
+    const result = await payload.find({
+      collection: "media",
+      limit: opts?.limit ?? 50,
+      page: opts?.offset
+        ? Math.floor(opts.offset / (opts.limit ?? 50)) + 1
+        : 1,
+      overrideAccess: true,
+    });
+    return result.docs.map((d) => mapDoc(d as PayloadMediaDoc));
+  }
+
+  async deleteMedia(id: string): Promise<void> {
+    const payload = await getPayload({ config: this.config });
+    await payload.delete({
+      collection: "media",
+      id,
+      overrideAccess: true,
+    });
+  }
+}

packages/media/src/integrations/api/index.ts

@@ -0,0 +1,2 @@
+export { mediaRouter } from "./router";
+export type { MediaRouter } from "./router";

packages/media/src/integrations/api/router.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { router, publicProcedure } from "@repo/core-shared/trpc/init";
+import { mediaContainer } from "../../di/container";
+import { MEDIA_SYMBOLS } from "../../di/symbols";
+import type { IGetMediaController } from "../../interface-adapters/controllers/get-media.controller";
+import type { IListMediaController } from "../../interface-adapters/controllers/list-media.controller";
+import type { IDeleteMediaController } from "../../interface-adapters/controllers/delete-media.controller";
+
+export const mediaRouter = router({
+  getMedia: publicProcedure
+    .input(z.object({ id: z.string().min(1) }))
+    .query(({ input }) => {
+      const ctrl = mediaContainer.get<IGetMediaController>(
+        MEDIA_SYMBOLS.IGetMediaController,
+      );
+      return ctrl(input);
+    }),
+
+  listMedia: publicProcedure
+    .input(
+      z
+        .object({
+          limit: z.number().optional(),
+          offset: z.number().optional(),
+        })
+        .optional(),
+    )
+    .query(({ input }) => {
+      const ctrl = mediaContainer.get<IListMediaController>(
+        MEDIA_SYMBOLS.IListMediaController,
+      );
+      return ctrl(input ?? {});
+    }),
+
+  deleteMedia: publicProcedure
+    .input(z.object({ id: z.string().min(1) }))
+    .mutation(({ input }) => {
+      const ctrl = mediaContainer.get<IDeleteMediaController>(
+        MEDIA_SYMBOLS.IDeleteMediaController,
+      );
+      return ctrl(input);
+    }),
+});
+
+export type MediaRouter = typeof mediaRouter;

packages/media/src/interface-adapters/controllers/delete-media.controller.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest";
+import { deleteMediaController } from "@/interface-adapters/controllers/delete-media.controller";
+import { deleteMediaUseCase } from "@/application/use-cases/delete-media.use-case";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import { MediaNotFoundError } from "@/entities/errors/media";
+import { InputParseError } from "@/entities/errors/common";
+import { mediaFactory } from "@/__factories__/media.factory";
+
+describe("deleteMediaController", () => {
+  it("deletes media successfully", async () => {
+    const repo = new MockMediaRepository();
+    const seed = mediaFactory.build({ id: "m-1" });
+    await repo._store(seed);
+
+    const useCase = deleteMediaUseCase(repo);
+    const controller = deleteMediaController(useCase);
+
+    await expect(controller({ id: "m-1" })).resolves.toBeUndefined();
+    const result = await repo.getMedia("m-1");
+    expect(result).toBeUndefined();
+  });
+
+  it("throws InputParseError when id is missing", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = deleteMediaUseCase(repo);
+    const controller = deleteMediaController(useCase);
+
+    await expect(controller({})).rejects.toThrow(InputParseError);
+  });
+
+  it("throws MediaNotFoundError when media does not exist", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = deleteMediaUseCase(repo);
+    const controller = deleteMediaController(useCase);
+
+    await expect(controller({ id: "missing" })).rejects.toThrow(MediaNotFoundError);
+  });
+});

packages/media/src/interface-adapters/controllers/delete-media.controller.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { InputParseError } from "../../entities/errors/common";
+import type { IDeleteMediaUseCase } from "../../application/use-cases/delete-media.use-case";
+
+const inputSchema = z.object({
+  id: z.string().min(1),
+});
+
+export type IDeleteMediaController = ReturnType<typeof deleteMediaController>;
+
+export const deleteMediaController =
+  (deleteMediaUseCase: IDeleteMediaUseCase) =>
+  async (input: Partial<z.infer<typeof inputSchema>>): Promise<void> => {
+    const parsed = inputSchema.safeParse(input);
+    if (!parsed.success) {
+      throw new InputParseError("Invalid delete-media input", { cause: parsed.error });
+    }
+    return deleteMediaUseCase(parsed.data);
+  };

packages/media/src/interface-adapters/controllers/get-media.controller.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { getMediaController } from "@/interface-adapters/controllers/get-media.controller";
+import { getMediaUseCase } from "@/application/use-cases/get-media.use-case";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import { MediaNotFoundError } from "@/entities/errors/media";
+import { InputParseError } from "@/entities/errors/common";
+import { mediaFactory } from "@/__factories__/media.factory";
+
+describe("getMediaController", () => {
+  it("returns media on valid input", async () => {
+    const repo = new MockMediaRepository();
+    const seed = mediaFactory.build({ id: "m-1" });
+    await repo._store(seed);
+
+    const useCase = getMediaUseCase(repo);
+    const controller = getMediaController(useCase);
+
+    const result = await controller({ id: "m-1" });
+    expect(result.id).toBe("m-1");
+  });
+
+  it("throws InputParseError when id is missing", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = getMediaUseCase(repo);
+    const controller = getMediaController(useCase);
+
+    await expect(controller({})).rejects.toThrow(InputParseError);
+  });
+
+  it("throws InputParseError when id is empty string", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = getMediaUseCase(repo);
+    const controller = getMediaController(useCase);
+
+    await expect(controller({ id: "" })).rejects.toThrow(InputParseError);
+  });
+
+  it("throws MediaNotFoundError when media does not exist", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = getMediaUseCase(repo);
+    const controller = getMediaController(useCase);
+
+    await expect(controller({ id: "missing" })).rejects.toThrow(MediaNotFoundError);
+  });
+});

packages/media/src/interface-adapters/controllers/get-media.controller.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { InputParseError } from "../../entities/errors/common";
+import type { Media } from "../../entities/models/media";
+import type { IGetMediaUseCase } from "../../application/use-cases/get-media.use-case";
+
+const inputSchema = z.object({
+  id: z.string().min(1),
+});
+
+export type IGetMediaController = ReturnType<typeof getMediaController>;
+
+export const getMediaController =
+  (getMediaUseCase: IGetMediaUseCase) =>
+  async (input: Partial<z.infer<typeof inputSchema>>): Promise<Media> => {
+    const parsed = inputSchema.safeParse(input);
+    if (!parsed.success) {
+      throw new InputParseError("Invalid get-media input", { cause: parsed.error });
+    }
+    return getMediaUseCase(parsed.data);
+  };

packages/media/src/interface-adapters/controllers/list-media.controller.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect } from "vitest";
+import { listMediaController } from "@/interface-adapters/controllers/list-media.controller";
+import { listMediaUseCase } from "@/application/use-cases/list-media.use-case";
+import { MockMediaRepository } from "@/infrastructure/repositories/media.repository.mock";
+import { mediaFactory } from "@/__factories__/media.factory";
+
+describe("listMediaController", () => {
+  it("returns empty array when no media exists", async () => {
+    const repo = new MockMediaRepository();
+    const useCase = listMediaUseCase(repo);
+    const controller = listMediaController(useCase);
+
+    const result = await controller({});
+    expect(result).toHaveLength(0);
+  });
+
+  it("returns all media", async () => {
+    const repo = new MockMediaRepository();
+    await repo._store(mediaFactory.build());
+    await repo._store(mediaFactory.build());
+
+    const useCase = listMediaUseCase(repo);
+    const controller = listMediaController(useCase);
+
+    const result = await controller({});
+    expect(result).toHaveLength(2);
+  });
+
+  it("passes limit and offset to use case", async () => {
+    const repo = new MockMediaRepository();
+    for (let i = 0; i < 5; i++) {
+      await repo._store(mediaFactory.build());
+    }
+
+    const useCase = listMediaUseCase(repo);
+    const controller = listMediaController(useCase);
+
+    const result = await controller({ limit: 2, offset: 1 });
+    expect(result).toHaveLength(2);
+  });
+});

packages/media/src/interface-adapters/controllers/list-media.controller.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { InputParseError } from "../../entities/errors/common";
+import type { Media } from "../../entities/models/media";
+import type { IListMediaUseCase } from "../../application/use-cases/list-media.use-case";
+
+const inputSchema = z.object({
+  limit: z.number().optional(),
+  offset: z.number().optional(),
+});
+
+export type IListMediaController = ReturnType<typeof listMediaController>;
+
+export const listMediaController =
+  (listMediaUseCase: IListMediaUseCase) =>
+  async (input: Partial<z.infer<typeof inputSchema>>): Promise<Media[]> => {
+    const parsed = inputSchema.safeParse(input);
+    if (!parsed.success) {
+      throw new InputParseError("Invalid list-media input", { cause: parsed.error });
+    }
+    return listMediaUseCase(parsed.data);
+  };

packages/media/tests/media.feature.test.ts

@@ -0,0 +1,83 @@
+// Feature-level test: exercises the full slice
+//   use case factory chain → mock repo
+// Tests the full dependency chain via direct injection (no container rebinding).
+
+import { describe, expect, it } from "vitest";
+import { MockMediaRepository } from "../src/infrastructure/repositories/media.repository.mock";
+import { getMediaUseCase } from "../src/application/use-cases/get-media.use-case";
+import { listMediaUseCase } from "../src/application/use-cases/list-media.use-case";
+import { deleteMediaUseCase } from "../src/application/use-cases/delete-media.use-case";
+import { getMediaController } from "../src/interface-adapters/controllers/get-media.controller";
+import { listMediaController } from "../src/interface-adapters/controllers/list-media.controller";
+import { deleteMediaController } from "../src/interface-adapters/controllers/delete-media.controller";
+import { MediaNotFoundError } from "../src/entities/errors/media";
+import { mediaFactory } from "../src/__factories__/media.factory";
+
+describe("media feature: end-to-end via direct injection", () => {
+  function buildChain() {
+    const repo = new MockMediaRepository();
+    const getUC = getMediaUseCase(repo);
+    const listUC = listMediaUseCase(repo);
+    const deleteUC = deleteMediaUseCase(repo);
+    const getCtrl = getMediaController(getUC);
+    const listCtrl = listMediaController(listUC);
+    const deleteCtrl = deleteMediaController(deleteUC);
+    return { repo, getCtrl, listCtrl, deleteCtrl };
+  }
+
+  it("listMedia returns empty array initially", async () => {
+    const { listCtrl } = buildChain();
+    const result = await listCtrl({});
+    expect(result).toHaveLength(0);
+  });
+
+  it("stores media and retrieves it by id", async () => {
+    const { repo, getCtrl } = buildChain();
+    const seed = mediaFactory.build({ id: "feat-1" });
+    await repo._store(seed);
+
+    const result = await getCtrl({ id: "feat-1" });
+    expect(result.id).toBe("feat-1");
+    expect(result.alt).toBe(seed.alt);
+  });
+
+  it("listMedia returns all stored media", async () => {
+    const { repo, listCtrl } = buildChain();
+    await repo._store(mediaFactory.build());
+    await repo._store(mediaFactory.build());
+    await repo._store(mediaFactory.build());
+
+    const result = await listCtrl({});
+    expect(result).toHaveLength(3);
+  });
+
+  it("deleteMedia removes media so it can no longer be retrieved", async () => {
+    const { repo, getCtrl, deleteCtrl } = buildChain();
+    const seed = mediaFactory.build({ id: "feat-del" });
+    await repo._store(seed);
+
+    await deleteCtrl({ id: "feat-del" });
+
+    await expect(getCtrl({ id: "feat-del" })).rejects.toThrow(MediaNotFoundError);
+  });
+
+  it("getMediaController throws MediaNotFoundError for missing id", async () => {
+    const { getCtrl } = buildChain();
+    await expect(getCtrl({ id: "does-not-exist" })).rejects.toBeInstanceOf(MediaNotFoundError);
+  });
+
+  it("deleteMediaController throws MediaNotFoundError for missing id", async () => {
+    const { deleteCtrl } = buildChain();
+    await expect(deleteCtrl({ id: "does-not-exist" })).rejects.toBeInstanceOf(MediaNotFoundError);
+  });
+
+  it("listMedia with limit respects pagination", async () => {
+    const { repo, listCtrl } = buildChain();
+    for (let i = 0; i < 5; i++) {
+      await repo._store(mediaFactory.build());
+    }
+
+    const result = await listCtrl({ limit: 3 });
+    expect(result).toHaveLength(3);
+  });
+});