# ajagtapdev/yaad architecture

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

- Interactive diagram: https://gitdiagram.com/ajagtapdev/yaad
- Repository: https://github.com/ajagtapdev/yaad

## Overview

Based on our analysis of the file tree and README, “Yaad” is a full-stack Next.js web application built to serve as a “living memory” database for users—especially those with degenerative cognitive conditions. The purpose is to record, transcribe, store, and later retrieve cherished memories using AI-assisted methods together with vector search capabilities through Pinecone. In addition, authentication is handled via Clerk, and the application features a modern, responsive design with Tailwind CSS.

##### Main Components
- Client/User Interface: Represented by the Next.js frontend with pages (e.g., home, about, contact, team, privacy, terms, and the specialized “yaad” page) and UI components like Navbar, Footer, TextToSpeech, and TranscriptionComponent.
- API Layers: Inside the src/app/api folder you have multiple API endpoints (retrieve, speak, speakandstore, and transcribe) that handle memory processing:
– /api/retrieve: Likely handles searching for memories based on prompts.
– /api/speak: Handles text-to-speech functionalities.
– /api/speakandstore: Likely integrates both text-to-speech and storing memories.
– /api/transcribe: Processes audio inputs into text.
- Authentication Module: Although Clerk is an external service used for sign-in and sign-up, note that the app contains dedicated authentication pages in the “src/app/auth” folder, which interface with Clerk.
- External Services:
– Pinecone: The vector database service that stores embeddings of memories, enabling advanced retrieval.
– Clerk: Provides secure user authentication.
- Shared Libraries and Utilities: Found in directories like “src/lib” and “src/utils” that hold utility functions (e.g., apiHelpers and general application utilities).
- Static Assets: Represented by the “public” and “src/public” directories (audio files, fonts) and design assets such as Tailwind CSS classes and configurations.

##### Architectural Patterns and Design Principles
– Highlight the Next.js app structure with clear segmentation between pages, API routes, and components.
– Show a separation of concerns: Frontend (application UI) versus Backend (API endpoints and processing logic).
– Emphasize modularity in the API design, treating each endpoint as a distinct microservice that interacts with both internal utilities and external services.
– Note the use of external authentication (Clerk) and a specialized vector database (Pinecone), illustrating modern cloud service integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    UD("User Devices (Browsers/Mobile)"):::external

    subgraph "Client UI (Next.js Client/App)"
        subgraph "Pages"
            AboutPage("About Page"):::frontend
            ContactPage("Contact Page"):::frontend
            PrivacyPage("Privacy Page"):::frontend
            TeamPage("Team Page"):::frontend
            TermsPage("Terms Page"):::frontend
            YaadPage("Yaad Page"):::frontend
        end
        subgraph "UI Components"
            Navbar("Navbar"):::frontend
            Footer("Footer"):::frontend
            TextToSpeech("TextToSpeech"):::frontend
            TranscriptionComponent("TranscriptionComponent"):::frontend
        end
        subgraph "Authentication Pages"
            AuthSignIn("Auth Sign-In"):::frontend
            AuthSignUp("Auth Sign-Up"):::frontend
        end
    end

    subgraph "API Endpoints"
        API_Retrieve("API: retrieve"):::api
        API_Speak("API: speak"):::api
        API_SpeakAndStore("API: speakandstore"):::api
        API_Transcribe("API: transcribe"):::api
    end

    subgraph "External Services"
        Clerk("Clerk (Authentication)"):::external
        Pinecone("Pinecone (Vector DB)"):::external
    end

    subgraph "Shared Libraries & Utilities"
        UtilsLib("Utility Functions"):::shared
        APIHelpers("API Helpers"):::shared
    end

    subgraph "Static Assets & Styling"
        PublicAssets("Public Assets"):::static
        AudioAssets("Audio Assets"):::static
        GlobalsCSS("Globals CSS"):::static
        TailwindConfig("Tailwind Config"):::static
    end

    subgraph "Configuration Files"
        NextConfig("Next Config"):::config
        TSConfig("TSConfig"):::config
        PostCSS("PostCSS Config"):::config
        ESLint("ESLint Config"):::config
    end

    %% Connections from User Devices to Client UI
    UD -->|"accesses"| AboutPage
    UD -->|"accesses"| Navbar

    %% Client UI interactions (pages triggering API calls)
    YaadPage -->|"triggers"| API_Speak
    YaadPage -->|"triggers"| API_SpeakAndStore
    YaadPage -->|"triggers"| API_Transcribe
    AboutPage --- PublicAssets

    %% API Endpoints using Shared Libraries
    API_Retrieve -->|"utilizes"| UtilsLib
    API_Speak -->|"utilizes"| APIHelpers
    API_SpeakAndStore -->|"utilizes"| UtilsLib
    API_Transcribe -->|"utilizes"| APIHelpers

    %% API Endpoints integration with External Services
    API_Retrieve -->|"queries"| Pinecone
    API_SpeakAndStore -->|"storesAndRetrieves"| Pinecone
    API_Transcribe -->|"integratesWith"| Pinecone

    %% Authentication flow from Auth pages to Clerk
    AuthSignIn -->|"authenticatesVia"| Clerk
    AuthSignUp -->|"authenticatesVia"| Clerk

    %% UI Components styling connection
    Navbar --- GlobalsCSS
    Footer --- GlobalsCSS
    TextToSpeech --- GlobalsCSS
    TranscriptionComponent --- GlobalsCSS

    %% Click Events for Client/UI Pages
    click AboutPage "https://github.com/ajagtapdev/yaad/tree/master/src/app/about"
    click ContactPage "https://github.com/ajagtapdev/yaad/tree/master/src/app/contact"
    click PrivacyPage "https://github.com/ajagtapdev/yaad/tree/master/src/app/privacy"
    click TeamPage "https://github.com/ajagtapdev/yaad/tree/master/src/app/team"
    click TermsPage "https://github.com/ajagtapdev/yaad/tree/master/src/app/terms"
    click YaadPage "https://github.com/ajagtapdev/yaad/blob/master/src/app/yaad/page.tsx"

    %% Click Events for UI Components
    click Navbar "https://github.com/ajagtapdev/yaad/blob/master/src/components/Navbar.tsx"
    click Footer "https://github.com/ajagtapdev/yaad/blob/master/src/components/Footer.tsx"
    click TextToSpeech "https://github.com/ajagtapdev/yaad/blob/master/src/components/TextToSpeech.tsx"
    click TranscriptionComponent "https://github.com/ajagtapdev/yaad/blob/master/src/components/TranscriptionComponent.tsx"

    %% Click Events for API Endpoints
    click API_Retrieve "https://github.com/ajagtapdev/yaad/blob/master/src/app/api/retrieve/route.ts"
    click API_Speak "https://github.com/ajagtapdev/yaad/blob/master/src/app/api/speak/route.ts"
    click API_SpeakAndStore "https://github.com/ajagtapdev/yaad/blob/master/src/app/api/speakandstore/route.ts"
    click API_Transcribe "https://github.com/ajagtapdev/yaad/blob/master/src/app/api/transcribe/route.ts"

    %% Click Events for Authentication Pages
    click AuthSignIn "https://github.com/ajagtapdev/yaad/blob/master/src/app/auth/sign-in/[[...rest]]/page.tsx"
    click AuthSignUp "https://github.com/ajagtapdev/yaad/blob/master/src/app/auth/sign-up/[[...rest]]/page.tsx"

    %% Click Events for Shared Libraries
    click UtilsLib "https://github.com/ajagtapdev/yaad/blob/master/src/lib/utils.ts"
    click APIHelpers "https://github.com/ajagtapdev/yaad/blob/master/src/utils/apiHelpers.ts"

    %% Click Events for Static Assets & Styling
    click PublicAssets "https://github.com/ajagtapdev/yaad/tree/master/public"
    click AudioAssets "https://github.com/ajagtapdev/yaad/tree/master/src/public/audio"
    click GlobalsCSS "https://github.com/ajagtapdev/yaad/blob/master/src/app/globals.css"
    click TailwindConfig "https://github.com/ajagtapdev/yaad/blob/master/tailwind.config.ts"

    %% Click Events for Configuration Files
    click NextConfig "https://github.com/ajagtapdev/yaad/blob/master/next.config.mjs"
    click TSConfig "https://github.com/ajagtapdev/yaad/blob/master/tsconfig.json"
    click PostCSS "https://github.com/ajagtapdev/yaad/blob/master/postcss.config.mjs"
    click ESLint "https://github.com/ajagtapdev/yaad/blob/master/.eslintrc.json"

    %% Style Definitions
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef api fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef shared fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef static fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef config fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
