OpenWatch

OpenWatch is a modern Watch streaming platform built with Next.js. It focuses on Watch discovery, playback, authenticated Watch progress, user profiles, XP-based gamification, leaderboards, and a scalable domain plugin architecture.

Author: Nikhil Mathew

Current Product Flow

OpenWatch is currently Watch-first. Comics have been removed from the active application codebase, routes, dashboard, profile data, and documentation.

The main user flow is:

1. Open / for the public landing/discovery entry.
2. Browse Watch from /watch or /home.
3. Search Watch from /watch/search or /search.
4. View Watch details at /watch/[id].
5. Watch episodes at /watch/[id]/watch.
6. Track Watch progress from Watch pages and the user dashboard.
7. Earn XP and level progress as episodes are updated.
8. View profile, history, stats, and leaderboard progress from /user, /profile/[username], and /leaderboard.

Architecture

The app is moving toward a factory/plugin architecture so shared layouts and UI components do not need to change whenever a new content domain is added.

Core layers:

• src/app contains thin route entry points and Next.js App Router files.
• src/components/ui contains shared UI primitives such as buttons, cards, loaders, badges, inputs, progress bars, skeletons, and carousel utilities.
• src/components/layout contains shared app shell pieces such as header, footer, page containers, and domain shell wrappers.
• src/config exposes domain configuration lookup used by shared UI.
• src/plugins contains the domain plugin factory and registries.
• src/features/watch contains the Watch domain plugin, config, pages, API adapter, and hooks.
• src/features/progress contains progress tracking API/hook utilities.
• src/context contains app-level providers such as authentication.
• src/lib contains shared backend/client infrastructure such as MongoDB, JWT, and API client utilities.

Domain Plugin Flow

New domains should be added through the plugin layer, not by modifying shared layouts or core components.

Current Watch plugin files:

• src/features/WATC./watch.config.js
• src/features/watch/plugin.js
• src/features/WATC./pages/watchHomePage.jsx
• src/features/watch/api/watch.api.js
• src/features/watch/hooks/useWatchQueries.js

Shared plugin infrastructure:

• src/plugins/createDomainPlugin.js
• src/plugins/domainRegistry.js
• src/plugins/domainConfigRegistry.js

Route entry points can resolve domain pages through the registry:

import { createRegisteredDomainPage } from "@/plugins/domainRegistry";

export default createRegisteredDomainPage("watch", "home");

The goal is that a future domain, such as Drama, can be implemented by creating src/features/drama, registering its config/plugin, and adding thin route files. Shared layout, UI primitives, authentication, loaders, and API client behavior should remain unchanged.

Design System

OpenWatch uses a pure black foundation with semantic tokens and domain accents.

• Global background: black or near-black.
• Shared surfaces: charcoal panels and cards.
• Text: white primary text and muted gray secondary text.
• Watch accent: orange.
• Future domain accents should be registered in domain config only.

Shared UI should consume semantic variables such as accent, surface, border, foreground, and muted text rather than hardcoding domain colors in individual components.

Data And APIs

• Watch data is fetched through the Watch API service adapter in src/features/watch/api/watch.api.js.
• Tenrai provider details should stay inside the Watch API layer.
• Auth, profile, progress, settings, and leaderboard data are handled by internal Next.js API routes under src/app/api.
• MongoDB is used for user data and progress persistence.

Authentication And Progress

OpenWatch supports authenticated user flows:

• Register and login.
• Remembered sessions using secure cookies.
• User dashboard and public profile pages.
• Watch progress tracking.
• Watchlist status management.
• XP and level calculation.
• Leaderboard integration.

Progress behavior should remain stable:

• Episode progress updates are synchronized with the server.
• User XP/level state updates through authenticated progress actions.
• Dashboard and profile pages read progress from internal user APIs.

Main Routes

• / - Landing/discovery page.
• /home - Watch home alias.
• /watch - Watch homepage/discovery.
• /watch/[id] - Watch detail page.
• /watch/[id]/watch - Watch Watch/player page.
• /watch/search - Watch search.
• /watch/genres - Watch genre discovery.
• /watch/schedule - Watch weekly schedule.
• /watch/rankings - Watch rankings.
• /search - Global Watch search entry.
• /login - Login page.
• /register - Register page.
• /user - Authenticated user dashboard.
• /user/setting - User settings.
• /profile/[username] - Public profile page.
• /leaderboard - Leaderboard page.

Undefined routes should fall through to the app's 404 page.

Branch Flow

This repository uses three branch prefixes/types:

• feat/* for feature work.
• fix/* for bug fixes.
• release/* for stable release branches.

Stable release flow:

1. Build feature work on a feat/* branch.
2. Merge completed feature work into a release/* branch, such as release/1.0.
3. Merge the stable release branch into master.
4. Keep master as the latest stable code.

Current release path:

feat/openWatch-initial -> release/1.0 -> master

Development

Install dependencies:

pnpm install

Create an environment file:

MONGODB_URI=mongodb://localhost:27017/openWatch
PROVIDER_API_URL=https://api.tenrai.org/v1

Run the development server:

pnpm dev

Build for production:

pnpm build
pnpm start

Lint:

pnpm lint

Notes

• Use pnpm for this project.
• Do not commit .env.
• Keep route files thin where possible.
• Keep provider-specific API logic inside feature API adapters.
• Keep new domain functionality inside the domain plugin layer.
• Avoid reintroducing Comics routes or manga/chapter progress unless that domain is intentionally rebuilt as a new plugin.