FotoOwl Headless Media SDK

Architecture Overview

This monorepo contains a framework-agnostic core SDK (@fotoowl/media-core), a React wrapper (@fotoowl/media-react), a headless UI component library (@fotoowl/media-ui-react), and a Vite Web App consuming them.

Strict dependency rules are enforced via npm workspaces: wrappers do not contain business logic, and UI components do not import the SDK or wrappers.

Judgment & Scoping Decisions

Due to the strict 8-12 hour time constraint, the following scoping decisions were made:

• React Native Wrappers Cut: media-native and media-ui-native were scoped out. The pure TypeScript architecture of media-core guarantees it can seamlessly support Native implementations in the future without modifying the underlying business logic.
• API Endpoints: Implemented robust search and searchVideos with pagination. curated/trending and single-item fetch were scoped out to prioritize perfecting the strict boundary wiring between the packages.
• In-Memory Caching: A Map-based cache was implemented in media-core to handle request de-duping rapidly.

AI Usage & Skills Log

AI coding assistants were explicitly permitted and utilized during this build.

• AI-Assisted: Boilerplate workspace configuration (package.json, tsconfig.json overrides for NodeNext/Vite bundler module resolution), Vite setup, and the premium CSS/UI styling in the final App.tsx.
• Hand-Written / Manually Audited: The strict dependency boundary enforcement, the headless hook implementations (useGrid, useReelSwiper), the event emitter logic, and the caching mechanisms.
• Skill Docs Testing: The two documents (skills/media-react-wiring.md and skills/media-ui-components.md) were drafted and then explicitly fed back into the AI context window. This successfully steered the AI to generate the App.tsx wiring without accidentally importing @fotoowl/media-core directly, proving the skills enforce the architectural boundaries.

Live Links

• GitHub Repository: https://github.com/jhasaurav97/fotoowl-headless-media-sdk
• App URL: https://fotoowl-headless-media-sdk-web.vercel.app/
• SDK & Components Docs: Handled via this README and the skills/ directory documents.