# devxoshakya/anveshna architecture

> Architecture diagram of the GitHub repository devxoshakya/anveshna, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devxoshakya/anveshna
- Repository: https://github.com/devxoshakya/anveshna

## Overview

1. **Repository shape**
   - This is a **Next.js App Router** frontend written in **TypeScript + React**.
   - The code is organized as a multi-page consumer app for an anime platform called **Anveshna**.
   - There is no separate backend in this repo; the UI appears to call external/content APIs through client-side hooks.

2. **Routing and page boundaries**
   - All user-facing screens live under `app/(shared)`, which suggests a **shared site shell** reused across pages.
   - Main routes include **home, search, trending, watch, chat, history, about, privacy-policy, dmca-policy**.
   - `app/(shared)/watch/[id]` is the dynamic detail/playback route for an individual anime title.

3. **Global shell and layout**
   - `app/layout.tsx` and `app/globals.css` define the root document and global styling.
   - `components/layout/*` contains the persistent chrome: **Navbar, Sidebar, Footer**, plus search/filter controls.
   - `components/theme-provider.tsx` and `components/ui/theme-toggle.tsx` indicate a **theme system** for dark/light behavior.

4. **Home/discovery subsystem**
   - The home experience is built from `components/home/*` and `components/cards/*`.
   - Key pieces:
     - `HomeCardList` for listing anime cards
     - `category-nav` and `pagination-component` for browsing sets of content
     - `watch-history-slider` for recently watched items
     - `TrendingAnimeCard`, `CardGrid`, `CardItem` for reusable catalog presentation
   - This is the main discovery surface for the catalog.

5. **Search and filtering flow**
   - Search-related UI is split between `components/layout/anime-search.tsx`, `SearchFilter.tsx`, and the `app/(shared)/search` route.
   - `hooks/useFilters.ts` likely owns filter state and query shaping.
   - `components/chat/SearchResultCard.tsx` and cards in the search route suggest shared result presentation across features.

6. **Watch/playback subsystem**
   - The watch experience is centered on `app/(shared)/watch/[id]/page.tsx`.
   - `components/watch/*` handles title metadata and episode navigation:
     - `AnimeDataList`, `WatchAnimeData` for title/episode data
     - `EpisodeList`, `Seasons` for episode grouping
   - Playback is isolated in `components/watch/video/*`:
     - `UnifiedPlayer` as the top-level player abstraction
     - `Player`, `MediaSource`, `IFramePLayer`, `Loader`
     - `PlayerStyles.css` for player-specific styling
   - `types/streaming.ts` defines the data contract for streaming/video sources.

7. **Chat / AI subsystem**
   - The chat page (`app/(shared)/chat`) is a separate conversational UI.
   - `hooks/useAi.ts` and `components/kokonutui/*` show an AI/streaming response flow with loading states.
   - `components/chat/ChatMessages`, `ChatPlaceholder`, and `SearchResultCard` suggest the chat can return anime-oriented answers or recommendations.
   - `hooks/useAutoScroll.ts` supports the streaming-message UX by keeping the latest response visible.

8. **Shared UI kit**
   - `components/ui/*` is a reusable design system: button, card, input, textarea, table, pagination, badge, breadcrumb, alert, skeleton, etc.
   - `components/skeletons/*` and `components/shared/StatusIndicator.tsx` provide loading and status primitives used across pages.
   - `components.json` suggests the project uses a structured component setup similar to a modern UI toolkit.

9. **Behavioral hooks and client-side state**
   - `hooks/` contains the main interaction logic:
     - `useApi` for fetching
     - `useAi` for AI/streaming requests
     - `useCountdown` and `useTime` for timed UI behavior
     - `use-mobile` for responsive behavior
     - `useAutoScroll` for message streams
   - These hooks are the main boundary between UI components and runtime behavior/data fetching.

10. **Utilities, assets, and styling**
   - `lib/utils.ts` and `lib/registry.tsx` provide shared helpers and integration glue.
   - `public/` contains static assets, including the landing imagery referenced in the README.
   - The app uses standard Next.js global CSS plus component-scoped styling where needed.

11. **Testing strategy**
   - `__tests__` mirrors the production structure: components, hooks, pages, and shared utilities.
   - Jest configuration (`jest.config.js`, `jest.setup.js`, `test-setup.ts`) indicates the repo is designed for **component-level and hook-level verification** rather than end-to-end infrastructure.
   - Test coverage is especially strong around watch/player, chat, and home-page behavior.

12. **Runtime and deployment context**
   - The repo is set up for **Bun** (`bun.lock`, `bunfig.toml`) but remains Node-compatible.
   - The README shows deployment targets like **Vercel** and self-hosting via **Diploi**.
   - `.env.example` implies runtime configuration is driven by environment variables, likely for API keys or endpoint settings.

13. **Architectural summary**
   - The main data flow is: **route → page component → feature component tree → hooks/API/AI layer → rendered UI**.
   - The most important domain boundaries are:
     - **catalog/discovery**
     - **watch/playback**
     - **chat/AI**
     - **shared shell and design system**
   - For an architecture diagram, the repo should be drawn as a **frontend-only Next.js application** with feature modules feeding off shared UI primitives and hook-based data access.

Main entry points: [`app/(shared)/layout.tsx`](https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/layout.tsx) (Shared Shell), [`components/home/HomeCardList.tsx`](https://github.com/devxoshakya/anveshna/blob/main/components/home/HomeCardList.tsx) (Discovery UI), [`hooks/useApi.ts`](https://github.com/devxoshakya/anveshna/blob/main/hooks/useApi.ts) (Core Hooks), [`app/(shared)/watch/[id]/page.tsx`](https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/watch/[id]/page.tsx) (Watch Detail)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_routing["Routing"]
  node_node_app_root["App Root<br/>Next root<br/>[layout.tsx]"]
  node_node_shared_layout["Shared Shell<br/>route shell<br/>[layout.tsx]"]
  node_node_home_page["Home Page<br/>route page<br/>[page.tsx]"]
  node_node_search_page["Search Page<br/>route page<br/>[page.tsx]"]
  node_node_trending_page["Trending Page<br/>route page<br/>[page.tsx]"]
  node_node_watch_page["Watch Page<br/>route page<br/>[page.tsx]"]
  node_node_watch_detail_page["Watch Detail<br/>route page<br/>[page.tsx]"]
  node_node_chat_page["Chat Page<br/>route page<br/>[page.tsx]"]
  node_node_static_pages["Static Pages<br/>content routes<br/>[page.tsx]"]
end

subgraph group_group_features["Features"]
  node_node_chrome["Site Chrome<br/>layout chrome<br/>[Navbar.tsx]"]
  node_node_home_discovery["Discovery UI<br/>catalog feature<br/>[HomeCardList.tsx]"]
  node_node_catalog_cards["Catalog Cards<br/>presentation<br/>[CardGrid.tsx]"]
  node_node_search_flow["Search & Filters<br/>query flow<br/>[anime-search.tsx]"]
  node_node_watch_metadata["Watch Metadata<br/>title detail<br/>[AnimeDataList.tsx]"]
  node_node_video_player["Player Stack<br/>video playback<br/>[UnifiedPlayer.tsx]"]
  node_node_chat_ui["Chat UI<br/>conversation feature<br/>[ChatMessages.tsx]"]
  node_node_ai_stream["AI Stream<br/>response flow<br/>[useAi.ts]"]
end

subgraph group_group_shared["Shared Foundation"]
  node_node_theme(("Theme System<br/>[theme-provider.tsx]"))
  node_node_ui_kit["UI Kit<br/>design system<br/>[button.tsx]"]
  node_node_skeletons["Loading Primitives<br/>skeletons<br/>[skeletons.tsx]"]
  node_node_hooks_core["Core Hooks<br/>client hooks<br/>[useApi.ts]"]
  node_node_utils["Shared Helpers<br/>utilities<br/>[utils.ts]"]
end

subgraph group_group_assets["Assets & Types"]
  node_node_streaming_types["Streaming Types<br/>contract<br/>[streaming.ts]"]
  node_node_public_assets[("Public Assets<br/>static assets")]
end

node_node_app_root -->|"wraps"| node_node_shared_layout
node_node_shared_layout -->|"provides"| node_node_theme
node_node_shared_layout -->|"renders"| node_node_chrome
node_node_shared_layout -->|"hosts"| node_node_home_page
node_node_shared_layout -->|"hosts"| node_node_search_page
node_node_shared_layout -->|"hosts"| node_node_trending_page
node_node_shared_layout -->|"hosts"| node_node_watch_page
node_node_shared_layout -->|"hosts"| node_node_watch_detail_page
node_node_shared_layout -->|"hosts"| node_node_chat_page
node_node_shared_layout -->|"hosts"| node_node_static_pages
node_node_home_page -->|"composes"| node_node_home_discovery
node_node_home_discovery -->|"uses"| node_node_catalog_cards
node_node_home_discovery -->|"fetches"| node_node_hooks_core
node_node_home_discovery -->|"shows"| node_node_public_assets
node_node_search_page -->|"composes"| node_node_search_flow
node_node_search_flow -->|"filters"| node_node_hooks_core
node_node_search_flow -->|"renders"| node_node_catalog_cards
node_node_trending_page -->|"renders"| node_node_catalog_cards
node_node_watch_page -->|"composes"| node_node_watch_metadata
node_node_watch_detail_page -->|"loads"| node_node_watch_metadata
node_node_watch_detail_page -->|"plays"| node_node_video_player
node_node_watch_metadata -->|"shapes"| node_node_streaming_types
node_node_video_player -->|"consumes"| node_node_streaming_types
node_node_video_player -->|"shows"| node_node_skeletons
node_node_chat_page -->|"composes"| node_node_chat_ui
node_node_chat_page -->|"streams"| node_node_ai_stream
node_node_chat_ui -->|"uses"| node_node_ai_stream
node_node_ai_stream -->|"extends"| node_node_hooks_core
node_node_chrome -->|"uses"| node_node_ui_kit
node_node_chrome -->|"uses"| node_node_skeletons
node_node_ui_kit -->|"depends on"| node_node_utils
node_node_hooks_core -->|"depends on"| node_node_utils

click node_node_app_root "https://github.com/devxoshakya/anveshna/blob/main/app/layout.tsx"
click node_node_shared_layout "https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/layout.tsx"
click node_node_home_page "https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/home/page.tsx"
click node_node_search_page "https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/search/page.tsx"
click node_node_trending_page "https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/trending/page.tsx"
click node_node_watch_page "https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/watch/page.tsx"
click node_node_watch_detail_page "https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/watch/[id]/page.tsx"
click node_node_chat_page "https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/chat/page.tsx"
click node_node_static_pages "https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/about/page.tsx"
click node_node_chrome "https://github.com/devxoshakya/anveshna/blob/main/components/layout/Navbar.tsx"
click node_node_theme "https://github.com/devxoshakya/anveshna/blob/main/components/theme-provider.tsx"
click node_node_ui_kit "https://github.com/devxoshakya/anveshna/blob/main/components/ui/button.tsx"
click node_node_skeletons "https://github.com/devxoshakya/anveshna/blob/main/components/skeletons/skeletons.tsx"
click node_node_hooks_core "https://github.com/devxoshakya/anveshna/blob/main/hooks/useApi.ts"
click node_node_utils "https://github.com/devxoshakya/anveshna/blob/main/lib/utils.ts"
click node_node_home_discovery "https://github.com/devxoshakya/anveshna/blob/main/components/home/HomeCardList.tsx"
click node_node_catalog_cards "https://github.com/devxoshakya/anveshna/blob/main/components/cards/CardGrid.tsx"
click node_node_search_flow "https://github.com/devxoshakya/anveshna/blob/main/components/layout/anime-search.tsx"
click node_node_watch_metadata "https://github.com/devxoshakya/anveshna/blob/main/components/watch/AnimeDataList.tsx"
click node_node_video_player "https://github.com/devxoshakya/anveshna/blob/main/components/watch/video/UnifiedPlayer.tsx"
click node_node_chat_ui "https://github.com/devxoshakya/anveshna/blob/main/components/chat/ChatMessages.tsx"
click node_node_ai_stream "https://github.com/devxoshakya/anveshna/blob/main/hooks/useAi.ts"
click node_node_streaming_types "https://github.com/devxoshakya/anveshna/blob/main/types/streaming.ts"
click node_node_public_assets "https://github.com/devxoshakya/anveshna/tree/main/public"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_app_root,node_node_shared_layout,node_node_home_page,node_node_search_page,node_node_trending_page,node_node_watch_page,node_node_watch_detail_page,node_node_chat_page,node_node_static_pages toneBlue
class node_node_chrome,node_node_home_discovery,node_node_catalog_cards,node_node_search_flow,node_node_watch_metadata,node_node_video_player,node_node_chat_ui,node_node_ai_stream toneAmber
class node_node_theme,node_node_ui_kit,node_node_skeletons,node_node_hooks_core,node_node_utils toneMint
class node_node_streaming_types,node_node_public_assets toneRose
```

## Components

### Routing

App Router pages and route boundaries

- [App Root](https://github.com/devxoshakya/anveshna/blob/main/app/layout.tsx): Next root · Root document and global app entry · `app/layout.tsx`
- [Shared Shell](https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/layout.tsx): route shell · Persistent app shell for shared pages · `app/(shared)/layout.tsx`
- [Home Page](https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/home/page.tsx): route page · Main discovery landing page · `app/(shared)/home/page.tsx`
- [Search Page](https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/search/page.tsx): route page · Search and filtered catalog route · `app/(shared)/search/page.tsx`
- [Trending Page](https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/trending/page.tsx): route page · Trending catalog route · `app/(shared)/trending/page.tsx`
- [Watch Page](https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/watch/page.tsx): route page · Watch landing and detail route · `app/(shared)/watch/page.tsx`
- [Watch Detail](https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/watch/[id]/page.tsx): route page · Dynamic title playback route · `app/(shared)/watch/[id]/page.tsx`
- [Chat Page](https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/chat/page.tsx): route page · AI/chat interaction route · `app/(shared)/chat/page.tsx`
- [Static Pages](https://github.com/devxoshakya/anveshna/blob/main/app/(shared)/about/page.tsx): content routes · About, history, and policy pages · `app/(shared)/about/page.tsx`

### Features

Major product areas and page-level subsystems

- [Site Chrome](https://github.com/devxoshakya/anveshna/blob/main/components/layout/Navbar.tsx): layout chrome · Navbar, sidebar, footer, and search controls · `components/layout/Navbar.tsx`
- [Discovery UI](https://github.com/devxoshakya/anveshna/blob/main/components/home/HomeCardList.tsx): catalog feature · Home browsing, category navigation, pagination, and history · `components/home/HomeCardList.tsx`
- [Catalog Cards](https://github.com/devxoshakya/anveshna/blob/main/components/cards/CardGrid.tsx): presentation · Reusable anime card and grid presentation · `components/cards/CardGrid.tsx`
- [Search & Filters](https://github.com/devxoshakya/anveshna/blob/main/components/layout/anime-search.tsx): query flow · Search input, filters, and result shaping · `components/layout/anime-search.tsx`
- [Watch Metadata](https://github.com/devxoshakya/anveshna/blob/main/components/watch/AnimeDataList.tsx): title detail · Title data, episode lists, and season grouping · `components/watch/AnimeDataList.tsx`
- [Player Stack](https://github.com/devxoshakya/anveshna/blob/main/components/watch/video/UnifiedPlayer.tsx): video playback · Unified player, sources, iframe fallback, and loader · `components/watch/video/UnifiedPlayer.tsx`
- [Chat UI](https://github.com/devxoshakya/anveshna/blob/main/components/chat/ChatMessages.tsx): conversation feature · Messages, placeholder states, and anime result cards · `components/chat/ChatMessages.tsx`
- [AI Stream](https://github.com/devxoshakya/anveshna/blob/main/hooks/useAi.ts): response flow · Streaming AI hooks and loading states · `hooks/useAi.ts`

### Shared Foundation

Reusable chrome, UI kit, hooks, and helpers

- [Theme System](https://github.com/devxoshakya/anveshna/blob/main/components/theme-provider.tsx): theme · Light/dark theme provider and toggle · `components/theme-provider.tsx`
- [UI Kit](https://github.com/devxoshakya/anveshna/blob/main/components/ui/button.tsx): design system · Reusable inputs, cards, buttons, tables, badges, and alerts · `components/ui/button.tsx`
- [Loading Primitives](https://github.com/devxoshakya/anveshna/blob/main/components/skeletons/skeletons.tsx): skeletons · Skeleton and status components · `components/skeletons/skeletons.tsx`
- [Core Hooks](https://github.com/devxoshakya/anveshna/blob/main/hooks/useApi.ts): client hooks · API, timing, mobile, and countdown behavior · `hooks/useApi.ts`
- [Shared Helpers](https://github.com/devxoshakya/anveshna/blob/main/lib/utils.ts): utilities · Common utilities and registry glue · `lib/utils.ts`

### Assets & Types

Static assets and shared contracts

- [Streaming Types](https://github.com/devxoshakya/anveshna/blob/main/types/streaming.ts): contract · Data contract for video and stream sources · `types/streaming.ts`
- [Public Assets](https://github.com/devxoshakya/anveshna/tree/main/public): static assets · Images and other static media · `public`

## Connections

- App Root → Shared Shell: wraps · Root document provides the shared app shell
- Shared Shell → Theme System: provides · Shared shell wires theme behavior for the site
- Shared Shell → Site Chrome: renders · Persistent navigation and footer chrome
- Shared Shell → Home Page: hosts · Shared shell contains the main site routes
- Shared Shell → Search Page: hosts · Shared shell contains the main site routes
- Shared Shell → Trending Page: hosts · Shared shell contains the main site routes
- Shared Shell → Watch Page: hosts · Shared shell contains the main site routes
- Shared Shell → Watch Detail: hosts · Shared shell contains the main site routes
- Shared Shell → Chat Page: hosts · Shared shell contains the main site routes
- Shared Shell → Static Pages: hosts · Shared shell contains the support and policy routes
- Home Page → Discovery UI: composes · Home route is built from discovery modules
- Discovery UI → Catalog Cards: uses · Discovery lists render shared catalog cards
- Discovery UI → Core Hooks: fetches · Home browsing depends on client-side hooks
- Discovery UI → Public Assets: shows · Landing content can reference static imagery
- Search Page → Search & Filters: composes · Search route is centered on filter and query flow
- Search & Filters → Core Hooks: filters · Search state and query shaping use hooks
- Search & Filters → Catalog Cards: renders · Search results reuse catalog presentation
- Trending Page → Catalog Cards: renders · Trending route is presented as catalog cards
- Watch Page → Watch Metadata: composes · Watch route assembles title and episode metadata
- Watch Detail → Watch Metadata: loads · Dynamic watch page drives title-specific metadata
- Watch Detail → Player Stack: plays · Playback is delegated to the player stack
- Watch Metadata → Streaming Types: shapes · Episode and source data follow the streaming contract
- Player Stack → Streaming Types: consumes · Player stack consumes source definitions
- Player Stack → Loading Primitives: shows · Loader and placeholder states are shared primitives
- Chat Page → Chat UI: composes · Chat route is built from conversation UI
- Chat Page → AI Stream: streams · Chat page relies on AI response hooks
- Chat UI → AI Stream: uses · Message UI is driven by streaming response state
- AI Stream → Core Hooks: extends · AI flow depends on shared client behavior hooks
- Site Chrome → UI Kit: uses · Layout controls are built from the UI kit
- Site Chrome → Loading Primitives: uses · Chrome reuses loading/status primitives
- UI Kit → Shared Helpers: depends on · UI primitives share helper utilities
- Core Hooks → Shared Helpers: depends on · Runtime hooks share common helpers
