# deepanshu1531/friday-ai architecture

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

- Interactive diagram: https://gitdiagram.com/deepanshu1531/friday-ai
- Repository: https://github.com/deepanshu1531/friday-ai

## Overview

##### Project Type and Purpose
- The “Friday AI” project is a full-stack web application built on Next.js that serves as a 3D-avatar chat assistant.
- It offers user authentication (JWT), chat sessions saved in MongoDB, AI model integration (via Ollama, Huggingface, etc.), and voice bi-directional interaction using the Web Speech API.

##### High-Level Architecture
- Client (Browser)
- Next.js React app under src/app & src/components
- Three.js + @react-three/fiber for 3D avatar rendering
- Tailwind CSS + Framer Motion for UI/UX
- Web Speech API for speech-to-text and text-to-speech
- Server (Next.js API Routes)
- Located in src/pages/api
- Routes: /auth/login, /auth/register, /chat, /chat-history, /health-check
- Middleware for JWT auth (src/middleware/authMiddleware.ts)
- Service Layer
- Business logic in src/services (AuthService, ChatService, OllamaService, UtilsService)
- Data Layer
- MongoDB accessed via Mongoose models in src/models (User, ChatSession, FridayModel)
- DB connection abstraction in src/lib/dbConnect.ts
- External AI Providers
- Ollama (local or remote LLM inference)
- Potential endpoints for Huggingface or Replicate

##### Key Architectural Patterns
- Layered Architecture:
- Presentation Layer (React UI + Avatar + Voice)
- API Layer (Next.js serverless routes + middleware)
- Business Logic Layer (Services)
- Data Access Layer (Mongoose models)
- Separation of Concerns: Each folder (`components`, `services`, `models`, `lib`, `middleware`) has a distinct responsibility.
- Serverless / Function-as-a-Service: API routes deploy as isolated endpoints.

a. Main Components
- Browser Client
- Next.js Frontend (UI + 3D Avatar + Voice)
- Next.js API Routes (Auth, Chat, History, Health)
- Service Layer (AuthService, ChatService, OllamaService)
- MongoDB Database
- External AI Engines (Ollama, optional Huggingface)
b. Data Flows & Relationships
1. User loads Next.js app → UI + Avatar render
2. User speaks/types → Web Speech API → Frontend → POST /api/chat
3. /api/chat → ChatService → OllamaService (or other AI) → AI response
4. ChatService saves session via ChatSession model → MongoDB
5. Frontend polls or GET /api/chat-history to load past sessions
6. /api/auth routes manage JWT issuance and verification via authMiddleware
c. Architectural Highlights
- Stateless API endpoints with JWT for auth
- 3D rendering decoupled from chat logic
- Services abstract external API calls and business rules
d. Key Technologies
- Next.js (SSR/SSG + API Routes)
- React + Three.js (@react-three/fiber)
- MongoDB + Mongoose
- JWT for auth
- Web Speech API for TTS/STT

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client (Browser)"
        direction TB
        Layout["Layout (src/components/Layout.tsx)"]:::frontend
        Globals["Global Styles (src/app/globals.css)"]:::frontend
        HomePage["Home Page (src/app/page.tsx)"]:::frontend
        ChatPage["Chat Page (src/app/chat/page.tsx)"]:::frontend
        LoginUI["Login UI (src/components/auth_acreen/LoginPage.tsx)"]:::frontend
        RegisterUI["Register UI (src/components/auth_acreen/RegisterPage.tsx)"]:::frontend
        Avatar3D["Avatar3D (src/components/main_screen/Avatar3D.tsx)"]:::frontend
        ChatInterface["ChatInterface (src/components/main_screen/ChatInterface.tsx)"]:::frontend
        InputArea["InputArea (src/components/main_screen/InputArea.tsx)"]:::frontend
        Sidebar["Sidebar (src/components/main_screen/Sidebar.tsx)"]:::frontend
        AppLayout["App Layout (src/app/layout.tsx)"]:::frontend
    end

    %% API Layer
    subgraph "API Layer (Next.js Serverless)"
        direction TB
        LoginAPI["POST /api/auth/login (src/pages/api/auth/login.ts)"]:::api
        RegisterAPI["POST /api/auth/register (src/pages/api/auth/register.ts)"]:::api
        ChatAPI["POST /api/chat (src/pages/api/chat.ts)"]:::api
        HistoryAPI["GET /api/chat-history (src/pages/api/chat-history.ts)"]:::api
        HealthAPI["GET /api/health-check (src/pages/api/health-check.ts)"]:::api
        AuthMW["authMiddleware (src/middleware/authMiddleware.ts)"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        AuthService["AuthService (src/services/AuthService.ts)"]:::service
        ChatService["ChatService (src/services/ChatService.ts)"]:::service
        OllamaService["OllamaService (src/services/OllamaService.ts)"]:::service
        UtilsService["UtilsService (src/services/UtilsService.ts)"]:::service
        IdentityPrompts["identityPrompts (src/services/identityPrompts.ts)"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DBConnect["dbConnect (src/lib/dbConnect.ts)"]:::data
        EnvLoader["env (src/lib/env.ts)"]:::data
        LangDetect["languageDetection (src/lib/languageDetection.ts)"]:::data
        UserModel["UserModel (src/models/User.ts)"]:::data
        ChatSessionModel["ChatSessionModel (src/models/ChatSession.ts)"]:::data
        FridayModel["FridayModel (src/models/FridayModel.ts)"]:::data
    end

    %% External AI
    subgraph "External AI Services"
        direction TB
        Ollama["Ollama Engine"]:::external
        Huggingface["Huggingface (optional)"]:::external
    end

    %% Client Flows
    AppLayout -->|renders| HomePage
    AppLayout -->|renders| ChatPage
    AppLayout -->|renders| LoginUI
    AppLayout -->|renders| RegisterUI
    HomePage -->|uses| Welcome
    ChatPage -->|uses| Avatar3D
    ChatPage -->|uses| ChatInterface
    ChatInterface -->|contains| InputArea
    ChatInterface -->|contains| Sidebar

    %% Client to API
    ChatInterface -->|"POST /api/chat"| ChatAPI
    ChatPage -->|"GET /api/chat-history"| HistoryAPI
    LoginUI -->|"POST /api/auth/login"| LoginAPI
    RegisterUI -->|"POST /api/auth/register"| RegisterAPI

    %% API to Middleware & Services
    LoginAPI -->|uses| AuthMW
    RegisterAPI -->|uses| AuthMW
    ChatAPI -->|uses| AuthMW
    HistoryAPI -->|uses| AuthMW

    LoginAPI -->|calls| AuthService
    RegisterAPI -->|calls| AuthService
    ChatAPI -->|calls| ChatService
    HistoryAPI -->|calls| ChatService
    HealthAPI -->|calls| UtilsService

    %% Services to External & Data
    ChatService -->|requests| OllamaService
    OllamaService -->|POST inference| Ollama
    ChatService -->|saves session| ChatSessionModel
    ChatService -->|reads sessions| ChatSessionModel
    AuthService -->|reads/writes| UserModel
    UtilsService -->|loads vars| EnvLoader
    UtilsService -->|detects language| LangDetect
    AuthService -->|connects DB| DBConnect
    ChatService -->|connects DB| DBConnect

    %% Click Events
    click AppLayout "https://github.com/deepanshu1531/friday-ai/blob/Main/src/app/layout.tsx"
    click Globals "https://github.com/deepanshu1531/friday-ai/blob/Main/src/app/globals.css"
    click HomePage "https://github.com/deepanshu1531/friday-ai/blob/Main/src/app/page.tsx"
    click ChatPage "https://github.com/deepanshu1531/friday-ai/blob/Main/src/app/chat/page.tsx"
    click LoginUI "https://github.com/deepanshu1531/friday-ai/blob/Main/src/components/auth_acreen/LoginPage.tsx"
    click RegisterUI "https://github.com/deepanshu1531/friday-ai/blob/Main/src/components/auth_acreen/RegisterPage.tsx"
    click Avatar3D "https://github.com/deepanshu1531/friday-ai/blob/Main/src/components/main_screen/Avatar3D.tsx"
    click ChatInterface "https://github.com/deepanshu1531/friday-ai/blob/Main/src/components/main_screen/ChatInterface.tsx"
    click InputArea "https://github.com/deepanshu1531/friday-ai/blob/Main/src/components/main_screen/InputArea.tsx"
    click Sidebar "https://github.com/deepanshu1531/friday-ai/blob/Main/src/components/main_screen/Sidebar.tsx"
    click Layout "https://github.com/deepanshu1531/friday-ai/blob/Main/src/components/Layout.tsx"
    click LoginAPI "https://github.com/deepanshu1531/friday-ai/blob/Main/src/pages/api/auth/login.ts"
    click RegisterAPI "https://github.com/deepanshu1531/friday-ai/blob/Main/src/pages/api/auth/register.ts"
    click ChatAPI "https://github.com/deepanshu1531/friday-ai/blob/Main/src/pages/api/chat.ts"
    click HistoryAPI "https://github.com/deepanshu1531/friday-ai/blob/Main/src/pages/api/chat-history.ts"
    click HealthAPI "https://github.com/deepanshu1531/friday-ai/blob/Main/src/pages/api/health-check.ts"
    click AuthMW "https://github.com/deepanshu1531/friday-ai/blob/Main/src/middleware/authMiddleware.ts"
    click AuthService "https://github.com/deepanshu1531/friday-ai/blob/Main/src/services/AuthService.ts"
    click ChatService "https://github.com/deepanshu1531/friday-ai/blob/Main/src/services/ChatService.ts"
    click OllamaService "https://github.com/deepanshu1531/friday-ai/blob/Main/src/services/OllamaService.ts"
    click UtilsService "https://github.com/deepanshu1531/friday-ai/blob/Main/src/services/UtilsService.ts"
    click IdentityPrompts "https://github.com/deepanshu1531/friday-ai/blob/Main/src/services/identityPrompts.ts"
    click DBConnect "https://github.com/deepanshu1531/friday-ai/blob/Main/src/lib/dbConnect.ts"
    click EnvLoader "https://github.com/deepanshu1531/friday-ai/blob/Main/src/lib/env.ts"
    click LangDetect "https://github.com/deepanshu1531/friday-ai/blob/Main/src/lib/languageDetection.ts"
    click UserModel "https://github.com/deepanshu1531/friday-ai/blob/Main/src/models/User.ts"
    click ChatSessionModel "https://github.com/deepanshu1531/friday-ai/blob/Main/src/models/ChatSession.ts"
    click FridayModel "https://github.com/deepanshu1531/friday-ai/blob/Main/src/models/FridayModel.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef api fill:#E6F4EA,stroke:#22863A,stroke-width:1px
    classDef service fill:#EDE5F4,stroke:#6F42C1,stroke-width:1px
    classDef data fill:#FFEFD5,stroke:#D2691E,stroke-width:1px
    classDef external fill:#F5E6FF,stroke:#9B59B6,stroke-width:1px
```
