# piyushthedev27/animeverse architecture

> Architecture diagram of the GitHub repository piyushthedev27/animeverse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/piyushthedev27/animeverse
- Repository: https://github.com/piyushthedev27/animeverse

## Overview

##### Project type and purpose
- This is a full-stack web application: “AnimeVerse Recommendation System” built on Next.js 13+ with TypeScript, React, Tailwind, Clerk for authentication, and MongoDB/Mongoose for persistence.
- It serves a public anime recommendation frontend, a set of server-side API endpoints, and integrates with Clerk (auth) and MongoDB Atlas.

##### File structure
- src/app – Next.js App Router (UI pages in React Server/Client components plus API routes under src/app/api).
- src/components – UI components divided into reusable ui/, layout/, sections/, providers/.
- src/contexts & src/hooks – React Context and custom hooks for state-management and data fetching.
- src/lib – data-access: mongoose connection (mongodb.ts), models/, utilities (auth, validation, recommendations).
- seed-database.js & src/lib/seedData.ts – scripts to populate the database.
- public – static assets.
- Configuration & build: next.config.ts, tsconfig.json, tailwind.config.ts, eslint.config.mjs.

##### README for insights
- The app offers personalized recommendations, watchlist management, advanced search/filter, real-time UI updates via server-side endpoints.
- Tech stack confirms: Next.js (App Router), React, TypeScript, Tailwind, Clerk auth, MongoDB/Mongoose, Vercel deployment.

##### Main components and their interactions
a. Frontend Layer
- Next.js App Router (src/app) – Server/Client components render pages and layouts (LandingPage, sign-in/up, search, sections).
- UI Components (src/components/ui) provide building blocks (cards, grids, buttons).
- React Context & Hooks (src/contexts, src/hooks) manage client state and call API endpoints.
b. API Layer (Backend)
- Next.js Serverless Functions under src/app/api – group endpoints by feature (anime, search, watchlist, recommendations, auth webhooks).
- Each route implements business logic, uses lib/api/client.ts or direct calls to lib/models and utils.
c. Data Access Layer
- MongoDB connection (src/lib/mongodb.ts) and Mongoose models (Anime, User, Watchlist).
- Utility modules for seeding (seedData), auth verification (verify.ts), recommendation algorithms.
d. External Services
- Clerk – handles user signup/sign-in workflows and webhooks (src/app/api/webhooks/clerk).
- MongoDB Atlas – persistent storage accessed via Mongoose.
e. Deployment
- Vercel – hosts the Next.js app as serverless functions + static assets.

##### Architectural patterns & design principles
- **Separation of Concerns**: UI vs. business logic vs. data access.
- **Modularization**: Feature-based API routing and component grouping.
- **Serverless Functions**: Each API route deployed as an isolated function.
- **React Server/Client Components**: Leverage Next.js 13 App Router for data fetching and incremental rendering.
- **Context & Hooks**: Encapsulate state and side effects cleanly.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser)"
        User["User (Browser)"]:::external
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        AppRouter["Next.js App Router"]:::frontend
        Layout["layout.tsx"]:::frontend
        RootPage["page.tsx"]:::frontend
        SignIn["sign-in page"]:::frontend
        SignUp["sign-up page"]:::frontend
        LandingComp["LandingPage.tsx"]:::frontend
        UI["UI Components (ui/)"]:::frontend
        LayoutComps["Layout Components (layout/)"]:::frontend
        Sections["Section Components (sections/)"]:::frontend
        Providers["ClerkProvider.tsx"]:::frontend
        Context["AppContext.tsx"]:::frontend
        Hooks["Custom Hooks (hooks/)"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        AnimeList["/api/anime"]:::backend
        AnimeById["/api/anime/[id]"]:::backend
        AnimeSearchAPI["/api/anime/search"]:::backend
        SearchAPI["/api/search"]:::backend
        CurrentlyAiringAPI["/api/currently-airing"]:::backend
        GenresAPI["/api/genres"]:::backend
        RecsAPI["/api/recommendations"]:::backend
        TrendingRecsAPI["/api/recommendations/trending"]:::backend
        WatchlistAPI["/api/watchlist"]:::backend
        WatchlistItemAPI["/api/watchlist/[animeId]"]:::backend
        UserPrefAPI["/api/user/preferences"]:::backend
        AuthTestAPI["/api/auth/test"]:::backend
        DebugAPI["/api/debug"]:::backend
        TestNewAPI["/api/test-new"]:::backend
        SeedAPI["/api/seed"]:::backend
        WebhookClerk["/api/webhooks/clerk"]:::backend
    end

    %% Data Access & Business Logic
    subgraph "Data Access & Business Logic"
        MongoConn["mongodb.ts"]:::data
        Models["Mongoose Models (models/)"]:::data
        ApiClient["api/client.ts"]:::data
        UtilsAuth["utils/auth.ts"]:::data
        UtilsDB["utils/database.ts"]:::data
        UtilsRecs["utils/recommendations.ts"]:::data
        UtilsVal["utils/validation.ts"]:::data
    end

    %% Offline Seed Scripts
    subgraph "Offline"
        SeedScript["seed-database.js"]:::data
        SeedLib["seedData.ts"]:::data
    end

    %% Database
    subgraph "Database"
        MongoDB["MongoDB Atlas"]:::data
    end

    %% External Services
    subgraph "External Services"
        Clerk["Clerk Auth Service"]:::external
        Vercel["Vercel Deployment"]:::external
    end

    %% Connections
    User --> AppRouter
    AppRouter --> Layout
    Layout --> RootPage
    AppRouter --> SignIn
    AppRouter --> SignUp
    RootPage --> LandingComp
    AppRouter --> UI
    AppRouter --> LayoutComps
    AppRouter --> Sections
    AppRouter --> Providers
    AppRouter --> Context
    AppRouter --> Hooks

    Hooks --> AnimeList
    Hooks --> SearchAPI
    Hooks --> RecsAPI
    Hooks --> WatchlistAPI
    Hooks --> UserPrefAPI
    Hooks --> AuthTestAPI

    SignIn --> Clerk
    SignUp --> Clerk
    Providers --> Clerk

    %% Frontend/API Deployment
    Vercel --> AppRouter
    Vercel --> AnimeList

    %% API to Data Access
    AnimeList --> MongoConn
    AnimeList --> Models
    AnimeById --> MongoConn
    AnimeSearchAPI --> MongoConn
    SearchAPI --> MongoConn
    CurrentlyAiringAPI --> MongoConn
    GenresAPI --> MongoConn
    RecsAPI --> MongoConn
    TrendingRecsAPI --> MongoConn
    WatchlistAPI --> MongoConn
    WatchlistItemAPI --> MongoConn
    UserPrefAPI --> MongoConn
    AuthTestAPI --> MongoConn
    DebugAPI --> MongoConn
    TestNewAPI --> MongoConn
    SeedAPI --> MongoConn
    WebhookClerk --> MongoConn

    %% Models and Utils relationships
    MongoConn --> MongoDB
    Models --> MongoConn
    ApiClient --> MongoConn
    UtilsAuth --> Models
    UtilsDB --> MongoConn
    UtilsRecs --> Models
    UtilsVal --> Models

    SeedScript --> MongoDB
    SeedLib --> MongoDB

    %% Click Events
    click AppRouter "https://github.com/piyushthedev27/animeverse/tree/main/src/app/"
    click Layout "https://github.com/piyushthedev27/animeverse/blob/main/src/app/layout.tsx"
    click RootPage "https://github.com/piyushthedev27/animeverse/blob/main/src/app/page.tsx"
    click SignIn "https://github.com/piyushthedev27/animeverse/blob/main/src/app/sign-in/[[...sign-in]]/page.tsx"
    click SignUp "https://github.com/piyushthedev27/animeverse/blob/main/src/app/sign-up/[[...sign-up]]/page.tsx"
    click LandingComp "https://github.com/piyushthedev27/animeverse/blob/main/src/components/LandingPage.tsx"
    click UI "https://github.com/piyushthedev27/animeverse/tree/main/src/components/ui/"
    click LayoutComps "https://github.com/piyushthedev27/animeverse/tree/main/src/components/layout/"
    click Sections "https://github.com/piyushthedev27/animeverse/tree/main/src/components/sections/"
    click Providers "https://github.com/piyushthedev27/animeverse/blob/main/src/components/providers/ClerkProvider.tsx"
    click Context "https://github.com/piyushthedev27/animeverse/blob/main/src/contexts/AppContext.tsx"
    click Hooks "https://github.com/piyushthedev27/animeverse/tree/main/src/hooks/"
    click AnimeList "https://github.com/piyushthedev27/animeverse/blob/main/src/app/api/anime/route.ts"
    click AnimeById "https://github.com/piyushthedev27/animeverse/blob/main/src/app/api/anime/[id]/route.ts"
    click AnimeSearchAPI "https://github.com/piyushthedev27/animeverse/blob/main/src/app/api/anime/search/route.ts"
    click SearchAPI "https://github.com/piyushthedev27/animeverse/blob/main/src/app/api/search/route.ts"
    click CurrentlyAiringAPI "https://github.com/piyushthedev27/animeverse/blob/main/src/app/api/currently-airing/route.ts"
    click GenresAPI "https://github.com/piyushthedev27/animeverse/blob/main/src/app/api/genres/route.ts"
    click RecsAPI "https://github.com/piyushthedev27/animeverse/blob/main/src/app/api/recommendations/route.ts"
    click TrendingRecsAPI "https://github.com/piyushthedev27/animeverse/blob/main/src/app/api/recommendations/trending/route.ts"
    click WatchlistAPI "https://github.com/piyushthedev27/animeverse/blob/main/src/app/api/watchlist/route.ts"
    click WatchlistItemAPI "https://github.com/piyushthedev27/animeverse/blob/main/src/app/api/watchlist/[animeId]/route.ts"
    click UserPrefAPI "https://github.com/piyushthedev27/animeverse/blob/main/src/app/api/user/preferences/route.ts"
    click AuthTestAPI "https://github.com/piyushthedev27/animeverse/blob/main/src/app/api/auth/test/route.ts"
    click DebugAPI "https://github.com/piyushthedev27/animeverse/blob/main/src/app/api/debug/route.ts"
    click TestNewAPI "https://github.com/piyushthedev27/animeverse/blob/main/src/app/api/test-new/route.ts"
    click SeedAPI "https://github.com/piyushthedev27/animeverse/blob/main/src/app/api/seed/route.ts"
    click WebhookClerk "https://github.com/piyushthedev27/animeverse/blob/main/src/app/api/webhooks/clerk/route.ts"
    click MongoConn "https://github.com/piyushthedev27/animeverse/blob/main/src/lib/mongodb.ts"
    click Models "https://github.com/piyushthedev27/animeverse/blob/main/src/lib/models/index.ts"
    click ApiClient "https://github.com/piyushthedev27/animeverse/blob/main/src/lib/api/client.ts"
    click UtilsAuth "https://github.com/piyushthedev27/animeverse/blob/main/src/lib/utils/auth.ts"
    click UtilsDB "https://github.com/piyushthedev27/animeverse/blob/main/src/lib/utils/database.ts"
    click UtilsRecs "https://github.com/piyushthedev27/animeverse/blob/main/src/lib/utils/recommendations.ts"
    click UtilsVal "https://github.com/piyushthedev27/animeverse/blob/main/src/lib/utils/validation.ts"
    click SeedScript "https://github.com/piyushthedev27/animeverse/blob/main/seed-database.js"
    click SeedLib "https://github.com/piyushthedev27/animeverse/blob/main/src/lib/seedData.ts"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFD580,stroke:#333,stroke-width:1px
    classDef external fill:#D8BFD8,stroke:#333,stroke-width:1px
```
