# lokeshkumar3103ar/memoji architecture

> Architecture diagram of the GitHub repository lokeshkumar3103ar/memoji, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lokeshkumar3103ar/memoji
- Repository: https://github.com/lokeshkumar3103ar/memoji

## Overview

1. **Overall shape**
   - This is a **single-page browser app** with a small **serverless API layer** for anything that needs secrets or external lookups.
   - The primary runtime is the **browser**; the backend is just a couple of **Vercel API routes** under `api/`.

2. **Frontend shell**
   - `index.html`, `styles.css`, and `app.js` form the UI layer.
   - `index.html` likely bootstraps the camera/meme experience, while `styles.css` handles the visual layout for the webcam view, overlays, and controls.
   - `app.js` is the main orchestrator: it handles UI state, camera access, face/emotion detection, meme/emoji selection, capture/share actions, and calling backend endpoints.

3. **Real-time computer vision pipeline**
   - The app uses **face-api.js** in the browser, as called out in the README.
   - The flow is: **camera stream → face detection → emotion classification → UI update**.
   - The detected expression is the core signal that drives all downstream behavior.

4. **Emotion-to-reaction mapping**
   - The client maintains local mappings from emotions to:
     - **emoji reactions**
     - **meme search queries**
   - The README explicitly mentions editable `CONFIG.EMOTION_QUERIES` and `CONFIG.EMOTION_EMOJI` in `app.js`, so `app.js` is not just behavior code; it also contains the app’s main content/configuration tables.

5. **Meme mode vs emoji overlay mode**
   - The UI appears to support at least two distinct presentation modes:
     - **Emoji overlay mode**: replaces or overlays the face with a large emoji.
     - **Meme match mode**: fetches a relevant GIF/meme based on the detected emotion.
   - This mode switch is an important product boundary because it changes whether the app is purely local rendering or involves a network call.

6. **Serverless API boundary**
   - The `api/` directory contains `api/analyze.js` and `api/meme.js`, which are deployed as **serverless functions** on Vercel.
   - This is the architecture’s trust boundary: the browser should not hold secrets, so anything involving AI or third-party API keys should be routed through these functions.

7. **External service integration**
   - The README lists **Azure OpenAI** environment variables and an optional **Tenor API key**.
   - That means the app has at least two external-service dependencies:
     - **Azure OpenAI** for analysis/AI-assisted logic
     - **Tenor** for meme/GIF retrieval
   - These are kept behind the API routes so the browser never needs to know the credentials.

8. **Capture and media assets**
   - `assets/faaah.mp3` and `assets/vine-boom-sound-meme.mp3` indicate the app includes **audio reactions** tied to certain states/events.
   - This is a local asset subsystem: no network dependency, just browser playback when an emotion/meme event fires.
   - The app likely also captures still images from the video stream for download/share.

9. **Deployment/runtime model**
   - `vercel.json` defines how the project is hosted on **Vercel**.
   - The deployment model is a static frontend plus auto-routed API functions, which fits the README’s “secure API architecture” note.
   - The app is otherwise host-agnostic and can also run from a simple static server for local testing.

10. **Configuration and setup files**
   - `config.example.js` and `generate_config.js` suggest local/environment-specific config generation or templating.
   - These are supporting files, not runtime architecture pillars, but they indicate the app expects configurable endpoints/keys during setup.
   - `MEMOJI APP AUDIT.md` is documentation/audit material, likely useful for maintenance rather than the runtime flow.

11. **Data flow summary**
   - The main end-to-end path is:
     - user opens page
     - browser requests camera permission
     - webcam frames are processed locally
     - emotion is inferred
     - UI updates with emoji/audio
     - if meme mode is active, a serverless API call returns a matching GIF or AI-derived result
   - The key architectural idea is **local-first perception with server-side secret handling only where needed**.

12. **Important diagram boundaries**
   - Draw a hard boundary around the **browser/client** versus **Vercel serverless/API**.
   - Draw another boundary around **external services**: Azure OpenAI and Tenor.
   - Treat the webcam and face detection as a **client-only real-time processing loop**, not as backend processing.

Main entry points: [`app.js`](https://github.com/lokeshkumar3103ar/memoji/blob/main/app.js) (Main App), [`api/analyze.js`](https://github.com/lokeshkumar3103ar/memoji/blob/main/api/analyze.js) (Analyze API), [`api/meme.js`](https://github.com/lokeshkumar3103ar/memoji/blob/main/api/meme.js) (Meme API), [`index.html`](https://github.com/lokeshkumar3103ar/memoji/blob/main/index.html) (Page Shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser App"]
  node_index_html["Page Shell<br/>html bootstrap<br/>[index.html]"]
  node_styles_css["App Styles<br/>ui styling<br/>[styles.css]"]
  node_app_js["Main App<br/>client orchestrator<br/>[app.js]"]
  node_camera_loop(("Camera Loop<br/>video pipeline"))
  node_face_api{{"Face API.js<br/>cv library"}}
  node_emotion_map["Reaction Map<br/>emotion config<br/>[app.js]"]
  node_emoji_mode(("Emoji Mode<br/>local overlay"))
  node_meme_mode(("Meme Mode<br/>networked reaction"))
  node_capture_share(("Capture Share<br/>media actions"))
end

subgraph group_serverless["API Layer"]
  node_api_analyze["Analyze API<br/>vercel function<br/>[analyze.js]"]
  node_api_meme["Meme API<br/>vercel function<br/>[meme.js]"]
end

subgraph group_external["External Services"]
  node_azure_openai{{"Azure OpenAI<br/>ai service"}}
  node_tenor{{"Tenor<br/>gif service"}}
end

subgraph group_assets["Media Assets"]
  node_faaah_mp3["Faaah Sound<br/>audio asset<br/>[faaah.mp3]"]
  node_vine_boom["Vine Boom<br/>audio asset"]
end

node_vercel_json["Vercel Config<br/>deployment config<br/>[vercel.json]"]
node_config_example["Config Template<br/>setup config<br/>[config.example.js]"]
node_generate_config["Config Generator<br/>setup script<br/>[generate_config.js]"]

node_index_html -->|"loads"| node_styles_css
node_index_html -->|"boots"| node_app_js
node_app_js -->|"controls"| node_camera_loop
node_camera_loop -->|"detects"| node_face_api
node_face_api -->|"expressions"| node_app_js
node_app_js -->|"uses"| node_emotion_map
node_emotion_map -->|"drives"| node_emoji_mode
node_emotion_map -->|"drives"| node_meme_mode
node_app_js -->|"renders"| node_emoji_mode
node_app_js -->|"requests"| node_meme_mode
node_meme_mode -->|"fetches"| node_api_meme
node_app_js -->|"analyzes"| node_api_analyze
node_api_analyze -->|"uses"| node_azure_openai
node_api_meme -->|"queries"| node_tenor
node_app_js -->|"handles"| node_capture_share
node_app_js -->|"plays"| node_faaah_mp3
node_app_js -->|"plays"| node_vine_boom
node_vercel_json -->|"routes"| node_api_analyze
node_vercel_json -->|"routes"| node_api_meme
node_generate_config -->|"derives"| node_config_example
node_config_example -.->|"configures"| node_app_js

click node_index_html "https://github.com/lokeshkumar3103ar/memoji/blob/main/index.html"
click node_styles_css "https://github.com/lokeshkumar3103ar/memoji/blob/main/styles.css"
click node_app_js "https://github.com/lokeshkumar3103ar/memoji/blob/main/app.js"
click node_emotion_map "https://github.com/lokeshkumar3103ar/memoji/blob/main/app.js"
click node_api_analyze "https://github.com/lokeshkumar3103ar/memoji/blob/main/api/analyze.js"
click node_api_meme "https://github.com/lokeshkumar3103ar/memoji/blob/main/api/meme.js"
click node_faaah_mp3 "https://github.com/lokeshkumar3103ar/memoji/blob/main/assets/faaah.mp3"
click node_vine_boom "https://github.com/lokeshkumar3103ar/memoji/blob/main/assets/vine-boom-sound-meme.mp3"
click node_vercel_json "https://github.com/lokeshkumar3103ar/memoji/blob/main/vercel.json"
click node_config_example "https://github.com/lokeshkumar3103ar/memoji/blob/main/config.example.js"
click node_generate_config "https://github.com/lokeshkumar3103ar/memoji/blob/main/generate_config.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index_html,node_styles_css,node_app_js,node_camera_loop,node_face_api,node_emotion_map,node_emoji_mode,node_meme_mode,node_capture_share toneBlue
class node_api_analyze,node_api_meme toneAmber
class node_azure_openai,node_tenor toneMint
class node_faaah_mp3,node_vine_boom toneRose
class node_vercel_json,node_config_example,node_generate_config toneNeutral
```

## Components

### Browser App

Static frontend and real-time client-side interaction loop.

- [Page Shell](https://github.com/lokeshkumar3103ar/memoji/blob/main/index.html): html bootstrap · Entry document that loads the app UI and bootstraps the browser experience. · `index.html`
- [App Styles](https://github.com/lokeshkumar3103ar/memoji/blob/main/styles.css): ui styling · Visual styling for the webcam view, overlays, and controls. · `styles.css`
- [Main App](https://github.com/lokeshkumar3103ar/memoji/blob/main/app.js): client orchestrator · Coordinates camera access, face/emotion detection, reaction state, capture/share actions, and API calls. · `app.js`
- **Camera Loop**: video pipeline · Browser-side webcam stream and frame processing loop.
- **Face API.js**: cv library · In-browser face detection and expression classification library used by the app.
- [Reaction Map](https://github.com/lokeshkumar3103ar/memoji/blob/main/app.js): emotion config · Local emotion-to-emoji and emotion-to-query tables maintained in the client. · `app.js`
- **Emoji Mode**: local overlay · Presentation mode that overlays or replaces the face with a large emoji.
- **Meme Mode**: networked reaction · Presentation mode that requests a matching meme or GIF for the detected emotion.
- **Capture Share**: media actions · Still capture and sharing/download actions triggered from the UI.

### API Layer

Vercel serverless functions used for secret-backed lookups.

- [Analyze API](https://github.com/lokeshkumar3103ar/memoji/blob/main/api/analyze.js): vercel function · Serverless analysis endpoint that keeps secret-backed AI logic off the client. · `api/analyze.js`
- [Meme API](https://github.com/lokeshkumar3103ar/memoji/blob/main/api/meme.js): vercel function · Serverless endpoint that resolves a suitable meme or GIF for the current emotion. · `api/meme.js`

### External Services

Third-party services reached through the API boundary.

- **Azure OpenAI**: ai service · External AI service used behind the analyze endpoint.
- **Tenor**: gif service · External GIF/meme source used behind the meme endpoint.

### Media Assets

Local audio reactions bundled with the app.

- [Faaah Sound](https://github.com/lokeshkumar3103ar/memoji/blob/main/assets/faaah.mp3): audio asset · Local audio reaction asset bundled with the app. · `assets/faaah.mp3`
- [Vine Boom](https://github.com/lokeshkumar3103ar/memoji/blob/main/assets/vine-boom-sound-meme.mp3): audio asset · Local audio reaction asset bundled with the app. · `assets/vine-boom-sound-meme.mp3`

### Other components

- [Vercel Config](https://github.com/lokeshkumar3103ar/memoji/blob/main/vercel.json): deployment config · Hosting and function routing configuration for Vercel. · `vercel.json`
- [Config Template](https://github.com/lokeshkumar3103ar/memoji/blob/main/config.example.js): setup config · Example configuration used to generate or document local environment settings. · `config.example.js`
- [Config Generator](https://github.com/lokeshkumar3103ar/memoji/blob/main/generate_config.js): setup script · Helper for generating environment-specific configuration. · `generate_config.js`

## Connections

- Page Shell → App Styles: loads · Page shell includes the stylesheet.
- Page Shell → Main App: boots · Page shell loads the main browser orchestrator.
- Main App → Camera Loop: controls · Main app starts and manages the webcam processing loop.
- Camera Loop → Face API.js: detects · Webcam frames are analyzed with face-api.js.
- Face API.js → Main App: expressions · Detected expressions feed back into application state.
- Main App → Reaction Map: uses · Client logic looks up emoji and query mappings for the current emotion.
- Reaction Map → Emoji Mode: drives · Emotion mapping selects the emoji reaction.
- Reaction Map → Meme Mode: drives · Emotion mapping selects the meme search/query path.
- Main App → Emoji Mode: renders · Main app updates the local emoji overlay presentation.
- Main App → Meme Mode: requests · Main app requests meme content when meme mode is active.
- Meme Mode → Meme API: fetches · Browser calls the meme endpoint for a matching GIF or meme.
- Main App → Analyze API: analyzes · Client can call the analysis endpoint for secret-backed AI logic.
- Analyze API → Azure OpenAI: uses · Analyze function delegates to Azure OpenAI.
- Meme API → Tenor: queries · Meme function queries Tenor for reactions.
- Main App → Capture Share: handles · Main app manages capture and share/download actions.
- Main App → Faaah Sound: plays · App can trigger bundled audio reactions.
- Main App → Vine Boom: plays · App can trigger bundled audio reactions.
- Vercel Config → Analyze API: routes · Deployment config exposes the analyze function.
- Vercel Config → Meme API: routes · Deployment config exposes the meme function.
- Config Generator → Config Template: derives · Generator uses the example config as a template.
- Config Template → Main App: configures · Client behavior references generated runtime settings.
