# sanaya27/novella-app architecture

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

- Interactive diagram: https://gitdiagram.com/sanaya27/novella-app
- Repository: https://github.com/sanaya27/novella-app

## Overview

##### Project type and purpose
- This is a full-stack, real-time “dating/chat” web application with AI-powered suggestions (“Novella”).
- The root is a monorepo containing:
- novella-app (React SPA frontend)
- novella-backend (Node/Express API + WebSocket server)
- Supporting docs (API integration, troubleshooting, MD guides)

##### File structure
- Top-level “novella-app” folder: React code under src/pages, src/components, context, utils, public for static assets (3D butterflies).
- Top-level “novella-backend” folder:
- config (DB config)
- controllers (chatController.js, etc.)
- middleware (auth, socketAuth)
- models (Member, Match, Message, ChatMessage)
- routes (REST endpoints: auth, members, matches, messages, heartSync, butterflies)
- src/server.js (entry point)
- utils (helpers, seedDatabase)
- Root also contains legacy “Components”, “Entities”, “Pages” directories, various demos and MD guides.

##### README
- Minimal: merely project name/taglines.
- Other MD files (API_INTEGRATION_GUIDE.md, NOVELLA_CHAT_AI_INTEGRATION.md) document integration with external AI services.

- Frontend (React SPA)
- Backend API & WS Server (Express + Socket.IO)
- Database (MongoDB)
- External AI Service (e.g., OpenAI)
- Static Asset Store (butterfly FBX/textures served via public folder or CDN)

- Frontend → Backend (REST calls for auth, profiles, matches, heartSync, butterflies)
- Frontend ↔ Backend (WebSocket for real-time chat messages)
- Backend → Database (CRUD on Member, Match, Message, ChatMessage models)
- Backend → AI Service (HTTP API for chat suggestions)
- Frontend ← Static Assets (3D butterflies)

c. Architectural patterns/design principles:
- Monorepo with clear separation: “novella-app” vs “novella-backend”
- MVC style in backend: routes → controllers → models
- Context API in React for global state (UserContext)
- Real-time communication via WebSocket + auth middleware
- Extensible “Entities” schema as JSON (graph-QL style)

d. Key technologies/frameworks:
- Frontend: React, React Router, Context API, JSX components
- Backend: Node.js, Express, Socket.IO, Mongoose (MongoDB)
- External AI: HTTP-based AI prompt system
- Deployment/config: .env, Dockerish scripts (setup.sh/.bat), seedDatabase.js

##### Detailed breakdown of essential elements
- Frontend:
- Pages: Home, Chat, Chatbot, Garden, HeartSync, etc.
- Components: ButterflyAnimation, ChatInput, SmartSuggestions
- Context: UserContext
- Backend:
- Routes: /auth, /members, /matches, /messages, /heartSync, /butterflies
- Controllers & Middleware: chatController.js, auth.js, socketAuth.js
- Models: Mongoose schemas for Member, Match, Message, ChatMessage
- Data flow:
- User signs up/logs in → POST /auth → JWT
- SPA requests profile data → GET /members/:id
- Real-time chat → WebSocket connect → join room → emit/receive chat messages
- When sending a message → backend may call AI Service → AI suggestions → SPA displays SmartSuggestions
- HeartSync: periodic heartbeat data → POST /heartSync → models store and return aggregated heart rate
- Butterfly animations: triggered by backend events or SPA state

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client" 
        direction TB
        Frontend["React SPA"]:::frontend
        subgraph "Pages" 
            direction TB
            Home["Home, Chat, Chatbot, Garden, HeartSync, etc."]:::frontend
        end
        subgraph "Components" 
            direction TB
            UIComponents["Butterfly3D, Layout, Dating Subcomponents"]:::frontend
            LegacyChat["ChatInput, ChatMessage, SmartSuggestions, TypingIndicator"]:::frontend
            LegacyDating["ButterflyAnimation, ButterflyBurst, HeartRateDisplay, RealisticButterfly"]:::frontend
        end
        UserContext["UserContext"]:::frontend
        StaticAssets["3D Butterflies (FBX, Textures)"]:::frontend
    end

    %% Server Layer
    subgraph "Server"
        direction TB
        RESTAPI["REST API"]:::backend
        WS["WebSocket Server"]:::backend
        RESTAPI --> Database
        WS --> Database
    end

    %% Database
    Database["MongoDB"]:::database

    %% External Services
    ExternalAI["External AI Service"]:::external
    CDN["Static Asset Store / CDN"]:::external

    %% Connections
    Frontend -->|"HTTP (REST)"| RESTAPI
    Frontend -->|"WebSocket"| WS
    RESTAPI -->|"CRUD"| Database
    WS -->|"CRUD"| Database
    RESTAPI -->|"HTTP API"| ExternalAI
    Frontend -->|"GET Assets"| StaticAssets
    StaticAssets -->|"Served via CDN"| Frontend

    %% Click Events - Client
    click Frontend "https://github.com/sanaya27/novella-app/tree/main/novella-app/"
    click Home "https://github.com/sanaya27/novella-app/tree/main/novella-app/src/pages/"
    click UIComponents "https://github.com/sanaya27/novella-app/tree/main/novella-app/src/components/"
    click LegacyChat "https://github.com/sanaya27/novella-app/tree/main/Components/chat/"
    click LegacyDating "https://github.com/sanaya27/novella-app/tree/main/Components/dating/"
    click UserContext "https://github.com/sanaya27/novella-app/blob/main/novella-app/src/context/UserContext.js"
    click StaticAssets "https://github.com/sanaya27/novella-app/tree/main/novella-app/public/butterflies/"

    %% Click Events - Server
    click RESTAPI "https://github.com/sanaya27/novella-app/blob/main/novella-backend/src/server.js"
    click Database "https://github.com/sanaya27/novella-app/blob/main/novella-backend/config/database.js"
    click WS "https://github.com/sanaya27/novella-app/blob/main/novella-backend/src/server.js"
    click RESTAPI "https://github.com/sanaya27/novella-app/blob/main/novella-backend/src/server.js"
    click AuthRoute "https://github.com/sanaya27/novella-app/blob/main/novella-backend/routes/auth.js"
    click MembersRoute "https://github.com/sanaya27/novella-app/blob/main/novella-backend/routes/members.js"
    click MatchesRoute "https://github.com/sanaya27/novella-app/blob/main/novella-backend/routes/matches.js"
    click MessagesRoute "https://github.com/sanaya27/novella-app/blob/main/novella-backend/routes/messages.js"
    click HeartSyncRoute "https://github.com/sanaya27/novella-app/blob/main/novella-backend/routes/heartSync.js"
    click ButterfliesRoute "https://github.com/sanaya27/novella-app/blob/main/novella-backend/routes/butterflies.js"
    click ChatController "https://github.com/sanaya27/novella-app/blob/main/novella-backend/controllers/chatController.js"
    click JWTAuth "https://github.com/sanaya27/novella-app/blob/main/novella-backend/middleware/auth.js"
    click SocketAuth "https://github.com/sanaya27/novella-app/blob/main/novella-backend/middleware/socketAuth.js"
    click MemberModel "https://github.com/sanaya27/novella-app/blob/main/novella-backend/models/Member.js"
    click MatchModel "https://github.com/sanaya27/novella-app/blob/main/novella-backend/models/Match.js"
    click MessageModel "https://github.com/sanaya27/novella-app/blob/main/novella-backend/models/Message.js"
    click ChatMessageModel "https://github.com/sanaya27/novella-app/blob/main/novella-backend/models/ChatMessage.js"
    click Helpers "https://github.com/sanaya27/novella-app/blob/main/novella-backend/utils/helpers.js"
    click SeedDB "https://github.com/sanaya27/novella-app/blob/main/novella-backend/utils/seedDatabase.js"

    %% Classes
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#E6FFED,stroke:#28a745,color:#28a745;
    classDef database fill:#FFECD1,stroke:#DB8E00,color:#DB8E00;
    classDef external fill:#F0F0F0,stroke:#6a737d,color:#6a737d;
```
