# mazidulfarabi/melissa-ai architecture

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

- Interactive diagram: https://gitdiagram.com/mazidulfarabi/melissa-ai
- Repository: https://github.com/mazidulfarabi/melissa-ai

## Overview

##### Project Type & Purpose
- This is a lightweight, full-stack web application (a modern AI chatbot) with a static front-end and a serverless backend.
- The front-end delivers a chat UI in the browser (HTML/CSS/JS), while the backend is a Netlify Function (Node.js) that handles calls to the OpenRouter AI service with an automatic API-key fallback mechanism.

##### Main Architectural Components
a. Presentation Layer (Client-side)
- index.html + stylesheet.css: The chat interface and styling.
- jscript.js: Controls user input, local greeting checks, sessionStorage, rate-limit logic, UI updates, audio playback (chat.mp3).
- sessionStorage: Persists chat history and status flags in the browser.
b. Application Layer (Serverless Backend)
- Netlify Functions (functions/chat.js): Receives AJAX requests from the front-end, orchestrates AI API calls using environment variables (OPENROUTER_API_KEY, OPENROUTER_API_KEY_BACKUP), implements fallback logic, parses responses, and returns JSON.
- netlify.toml / _headers: Configure routes, headers, deploy settings.
c. Integration Layer (External Service)
- OpenRouter AI (Mistral 7B model): External AI inference service.
d. Hosting & Deployment
- Netlify CDN: Hosts static assets and serves the function, with automatic build & deploy from the repository.

##### Component Interactions & Data Flow
1. User types message in the browser UI.
2. jscript.js intercepts the input, runs a local-greeting check.
- If it matches a common greeting, generate a local response and update UI.
- Otherwise, send an HTTPS POST to /.netlify/functions/chat.
3. Netlify Function receives the payload, reads the primary API key from env vars.
4. Function calls OpenRouter AI.
- On success: return the AI’s response.
- On rate-limit or key failure: switch to backup key and retry.
5. Function returns JSON to jscript.js.
6. Front-end updates the chat UI (typing animation, sound alert), persists message/response in sessionStorage, updates online/offline status, and triggers smart alerts as needed.

##### Architectural Patterns & Principles
- Serverless API Gateway: the Netlify Function serves as a thin API layer.
- Automatic Fallback Circuit: a two-step key-switch strategy for high availability.
- Progressive Enhancement: local checks for trivial cases to reduce external calls.
- Stateless Functions + State in Browser: The function remains stateless; sessionStorage holds transient conversation state.

##### Diagramming Recommendations
- jscript.js (UI logic, rate-limit, audio)
- chat.js (Netlify Function, Node.js, fallback logic)
- OpenRouter AI (Mistral 7B)
d. Environment Variables & Config

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        UI["index.html<br/>(Chat Interface)"]:::client
        STYLE["stylesheet.css<br/>(Styling)"]:::client
        JS["jscript.js<br/>(UI logic, rate-limit, audio)"]:::client
        AUDIO["chat.mp3<br/>(Audio Asset)"]:::asset
        STORAGE["sessionStorage<br/>(Chat History)"]:::storage
    end

    %% Application Layer
    subgraph "Serverless Backend (Netlify Functions)"
        direction TB
        FUNC["chat.js<br/>(Function, Node.js, fallback logic)"]:::server
        PKG["package.json"]:::server
        LOCK["package-lock.json"]:::server
    end

    %% Config Files
    subgraph "Configuration"
        direction TB
        NETLIFY["netlify.toml"]:::config
        HEADERS["_headers"]:::config
    end

    %% External Service
    subgraph "External AI Service"
        direction TB
        AI["OpenRouter AI<br/>(Mistral 7B)"]:::external
    end

    %% Documentation / Legal
    subgraph "Docs & Legal"
        direction TB
        README["README.md"]:::docs
        SETUP["SETUP.md"]:::docs
        LICENSE["LICENSE"]:::docs
        PRIVACY["privacy-policy.html"]:::docs
    end

    %% Hosting
    NetlifyCDN["Netlify CDN<br/>(Static & Functions)"]:::hosting

    %% Data Flow
    UI -->|"User Message"| JS
    JS -->|"POST /.netlify/functions/chat"| FUNC
    FUNC -->|"AI Request (key1→key2)"| AI
    AI -->|"Response JSON"| FUNC
    FUNC -->|"Response JSON"| JS
    JS -->|"UI Update + sessionStorage write"| STORAGE
    STORAGE -->|"Persisted History"| JS
    NetlifyCDN -->|Serves| UI
    NetlifyCDN -->|Serves| FUNC
    NETLIFY -->|Configures| FUNC
    HEADERS -->|Configures| UI

    %% Click Events
    click UI "https://github.com/mazidulfarabi/melissa-ai/blob/main/index.html"
    click STYLE "https://github.com/mazidulfarabi/melissa-ai/blob/main/stylesheet.css"
    click JS "https://github.com/mazidulfarabi/melissa-ai/blob/main/jscript.js"
    click AUDIO "https://github.com/mazidulfarabi/melissa-ai/blob/main/chat.mp3"
    click FUNC "https://github.com/mazidulfarabi/melissa-ai/blob/main/functions/chat.js"
    click PKG "https://github.com/mazidulfarabi/melissa-ai/blob/main/functions/package.json"
    click LOCK "https://github.com/mazidulfarabi/melissa-ai/blob/main/functions/package-lock.json"
    click NETLIFY "https://github.com/mazidulfarabi/melissa-ai/blob/main/netlify.toml"
    click HEADERS "https://github.com/mazidulfarabi/melissa-ai/tree/main/_headers"
    click README "https://github.com/mazidulfarabi/melissa-ai/blob/main/README.md"
    click SETUP "https://github.com/mazidulfarabi/melissa-ai/blob/main/SETUP.md"
    click LICENSE "https://github.com/mazidulfarabi/melissa-ai/tree/main/LICENSE"
    click PRIVACY "https://github.com/mazidulfarabi/melissa-ai/blob/main/privacy-policy.html"

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,color:#004085;
    classDef server fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
    classDef config fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef docs fill:#f5f5f5,stroke:#333333,color:#333333;
    classDef hosting fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
    classDef asset fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef storage fill:#f0f0f0,stroke:#888888,color:#888888;
```
