# harshrawat27/vocabularyai architecture

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

- Interactive diagram: https://gitdiagram.com/harshrawat27/vocabularyai
- Repository: https://github.com/harshrawat27/vocabularyai

## Overview

##### Main Components
- Frontend Client: Represented by the various pages and components within the “app” directory. These include pages for authentication (e.g., auth, login, auth-success), blog (blog, blog/[slug]), dashboard (dashboard with its multiple sub-pages), pricing, and more.
- API Endpoints: Many endpoints reside under “app/api/…” for features like authentication (including token handling), payments, subscriptions, searches, highlights, vocabulary, and YouTube timestamps. These indicate a serverless API approach within the Next.js app.
- Backend/Logic Layer: Include the “lib” folder which contains business logic integrations (e.g., authOptions, dbConnect, OpenAI integrations, PayPal, and Sanity queries) and the “models” directory, which defines data models (like Highlight, Search, User, and YouTubeHighlight).
- Content Management and External Services: There is integration with Sanity (via “sanity.config.js”, “schemas”, and related queries) as well as third-party integrations for payment processing (PayPal) and possibly OpenAI.
- Shared Components & Utilities: The “components” folder (including dashboard layouts and UI components) and “utils” for adapters provide shared UI and functional logic.

##### Relationships and Interactions
- Client Devices <-> Next.js Frontend: User browsers interact with the Next.js pages (both static and dynamic routes).
- Frontend <-> API Routes: The frontend pages and client-side code consume API endpoints (such as fetching user data, handling sign-in, subscription management, etc.).
- Server/Backend Integrations: API routes or server components in Next.js internally rely on libraries from “lib” to handle authentication, database connections, third-party services, and payment processing.
- Data Models: Show how the “models” layer interacts with the logic to represent data (highlights, searches, subscriptions, etc.) for persistence.

##### Architectural Patterns and Design Principles
- Full-Stack Modular Architecture: The separation of API routes from page components, with the “app” directory using server-side and client-side logic, stresses clear separation of concerns.
- Component-Based Frontend Design: The inclusion of a robust “components” directory underscores the reuse of UI components.
- Domain-Driven Structure: The file tree organizes functionality by feature (blog, dashboard, learning resources) which is a common domain-driven strategy.
- Serverless API: Next.js API routes are deployed as isolated serverless functions for modular scalability.

##### Relevant Technologies, Frameworks, or Libraries
- Next.js: A primary framework used to build the React-based full-stack application.
- NextAuth: Look at the “[...nextauth]” routes for authentication details.
- PayPal: Integrated via “app/lib/paypal.ts” and related type definitions.
- Sanity: Managed via “sanity.config.js”, “schemas”, and query functions.
- TypeScript & JavaScript: Mixed usage across the project as seen in .ts, .tsx, and .js files.
- Other libraries: OpenAI (via “app/lib/openai.ts”), Tailwind CSS configured in “tailwind.config.ts”, and global styles.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Device
    Browser(["User Browser"]):::external

    %% Frontend Layer
    subgraph "Frontend (Pages & Components)"
        FE_Pages["Frontend Pages (app/)"]:::frontend
        FE_Blog["Blog Pages (app/blog, app/blog/[slug])"]:::frontend
        FE_Dashboard["Dashboard Pages (app/dashboard)"]:::frontend
        FE_Auth["Auth Pages (app/auth, app/auth/signin, app/auth/error)"]:::frontend
        FE_Components["Shared UI Components (app/components)"]:::frontend
    end

    %% API Endpoints Layer
    subgraph "Serverless API Routes"
        API_Root["API Root (app/api/)"]:::api
        API_Auth["Auth API (app/api/auth, [...nextauth], token)"]:::api
        API_Payments["Payments & Subscriptions API (app/api/payments, subscribe, subscriptions)"]:::api
        API_Content["Content APIs (app/api/highlights, learning-resources, searches, vocabulary, youtube-timestamps)"]:::api
    end

    %% Backend / Logic Layer
    subgraph "Business Logic & Data Models"
        BLib["Business Logic (app/lib)"]:::logic
        DModels["Data Models (models)"]:::logic
    end

    %% External Services Layer
    subgraph "External Integrations"
        Ext_Sanity["Sanity CMS (sanity.config.js & schemas)"]:::external
        Ext_PayPal["PayPal Integration (app/lib/paypal.ts)"]:::external
        Ext_OpenAI["OpenAI Integration (app/lib/openai.ts)"]:::external
    end

    %% Shared Utilities Layer
    subgraph "Shared Components & Utilities"
        Utils["Utility Functions (app/utils)"]:::util
    end

    %% Data Flow Connections
    Browser -->|"requests"| FE_Pages
    FE_Pages -->|"API calls"| API_Root
    FE_Blog -->|"renders content"| FE_Pages
    FE_Dashboard -->|"renders personalized data"| FE_Pages
    FE_Auth -->|"authentication flow"| FE_Pages
    FE_Components -->|"UI composition"| FE_Pages

    API_Root -->|"delegates auth"| API_Auth
    API_Root -->|"handles payments"| API_Payments
    API_Root -->|"serves content"| API_Content

    API_Auth -->|"uses business logic"| BLib
    API_Payments -->|"triggers payment logic"| BLib
    API_Content -->|"fetches data"| BLib

    BLib -->|"manages data"| DModels
    BLib -->|"queries content"| Ext_Sanity
    BLib -->|"processes payments"| Ext_PayPal
    BLib -->|"calls OpenAI"| Ext_OpenAI

    FE_Pages ---|"uses utilities"| Utils

    %% Click Events for Frontend
    click FE_Pages "https://github.com/harshrawat27/vocabularyai/tree/main/app/"
    click FE_Blog "https://github.com/harshrawat27/vocabularyai/tree/main/app/blog"
    click FE_Blog "https://github.com/harshrawat27/vocabularyai/tree/main/app/blog/[slug]"
    click FE_Dashboard "https://github.com/harshrawat27/vocabularyai/tree/main/app/dashboard"
    click FE_Auth "https://github.com/harshrawat27/vocabularyai/tree/main/app/auth"
    click FE_Components "https://github.com/harshrawat27/vocabularyai/tree/main/app/components"

    %% Click Events for APIs
    click API_Root "https://github.com/harshrawat27/vocabularyai/tree/main/app/api/"
    click API_Auth "https://github.com/harshrawat27/vocabularyai/tree/main/app/api/auth"
    click API_Auth "https://github.com/harshrawat27/vocabularyai/blob/main/app/api/auth/[...nextauth]"
    click API_Auth "https://github.com/harshrawat27/vocabularyai/tree/main/app/api/auth/token"
    click API_Payments "https://github.com/harshrawat27/vocabularyai/tree/main/app/api/payments"
    click API_Payments "https://github.com/harshrawat27/vocabularyai/tree/main/app/api/subscribe"
    click API_Payments "https://github.com/harshrawat27/vocabularyai/tree/main/app/api/subscriptions"
    click API_Content "https://github.com/harshrawat27/vocabularyai/tree/main/app/api/highlights"
    click API_Content "https://github.com/harshrawat27/vocabularyai/tree/main/app/api/learning-resources"
    click API_Content "https://github.com/harshrawat27/vocabularyai/tree/main/app/api/searches"
    click API_Content "https://github.com/harshrawat27/vocabularyai/tree/main/app/api/vocabulary"
    click API_Content "https://github.com/harshrawat27/vocabularyai/tree/main/app/api/youtube-timestamps"

    %% Click Events for Business Logic & Data Models
    click BLib "https://github.com/harshrawat27/vocabularyai/tree/main/app/lib"
    click DModels "https://github.com/harshrawat27/vocabularyai/tree/main/models"

    %% Click Events for External Services
    click Ext_Sanity "https://github.com/harshrawat27/vocabularyai/blob/main/sanity.config.js"
    click Ext_Sanity "https://github.com/harshrawat27/vocabularyai/tree/main/schemas"
    click Ext_PayPal "https://github.com/harshrawat27/vocabularyai/blob/main/app/lib/paypal.ts"
    click Ext_OpenAI "https://github.com/harshrawat27/vocabularyai/blob/main/app/lib/openai.ts"

    %% Click Events for Utilities
    click Utils "https://github.com/harshrawat27/vocabularyai/tree/main/app/utils"

    %% Style Definitions
    classDef frontend fill:#ffdddd,stroke:#cc0000,stroke-width:2px;
    classDef api fill:#ddffdd,stroke:#00aa00,stroke-width:2px;
    classDef logic fill:#ddddff,stroke:#0000cc,stroke-width:2px;
    classDef external fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef util fill:#e6e6e6,stroke:#999999,stroke-width:2px;
```
