# Feeling HQ

> Free interactive emotion and wellbeing wheels to help you identify, name, and understand your feelings with emotional granularity.

Feeling HQ is a web application that provides 11 interactive wheels and grids built on psychological frameworks — including Gloria Willcox's Feelings Wheel and Plutchik's Wheel of Emotions — for individuals, therapists, teams, and organizations to develop self-awareness, emotional intelligence, and team engagement.

## Core Features

- **Interactive Emotion Wheels**: 11 themed wheels and grids covering emotions, mood, energy, work satisfaction, relationships, values, needs, character strengths, nervous system states, team pulse, and mood-food connections.
- **AI "Find Your Feeling"**: Describe how you feel in plain text and AI matches you to the most relevant emotion on the wheel.
- **Event Sharing & Collaboration**: Create shareable emotion check-in events with unique short links. Participants anonymously select emotions, and results are visualized as a real-time word cloud.
- **Dark Mode**: Full dark mode support across all pages.

## Available Wheels

- [Emotion & Feeling Wheel](https://feelinghq.com/feelings): Full spectrum of human emotions — core, secondary, and tertiary layers (Anger, Sadness, Fear, Surprise, Love, Joy).
- [Mood Check-in Wheel](https://feelinghq.com/mood): Daily mood tracking and current emotional state identification.
- [Energy Level Wheel](https://feelinghq.com/energy): Gauge energy and vitality levels.
- [Work Satisfaction Wheel](https://feelinghq.com/work): Identify feelings about work and professional relationships.
- [Relationship Dynamics Wheel](https://feelinghq.com/relationship): Explore feelings about relationships and connections.
- [Life Values Grid](https://feelinghq.com/values): Identify core personal values.
- [Human Needs Grid](https://feelinghq.com/needs): Identify fundamental human needs.
- [Character Strengths Wheel](https://feelinghq.com/strengths): Explore personal strengths and character qualities.
- [Nervous System Wheel](https://feelinghq.com/nervous-system): Map emotions to nervous system states for somatic awareness.
- [Team Pulse Wheel](https://feelinghq.com/team-pulse): Specialized for team and group check-ins.
- [Mood & Food Connection Wheel](https://feelinghq.com/mood-food): Explore the relationship between mood and nutrition.

## How It Works

Each wheel organizes emotions (or values, needs, strengths) in a hierarchical structure:

1. **Core Layer**: 5–8 primary categories (e.g., Anger, Joy, Fear).
2. **Secondary Layer**: 4–5 more specific emotions within each core category.
3. **Tertiary Layer**: 2–3 highly specific emotions with descriptive text explaining each one.

Users interact by clicking or tapping on wheel segments to drill down from broad categories to specific emotions, gaining emotional granularity.

## Event Sharing

Authenticated users can create emotion-collection events:

1. Sign in with Google.
2. Choose a wheel and create an event with a title and optional description.
3. Share the generated short link (`feelinghq.com/e/{code}`) with participants.
4. Participants open the link, select an emotion from the wheel, and submit anonymously.
5. Results are visualized as a word cloud showing collective emotions in real time.
6. The event creator can end the event and share results.

No login is required for participants — only the event creator needs to sign in.

## AI Feeling Matcher

The AI feature on the landing page lets users type a natural-language description of how they feel. The system uses an LLM to match the description to the closest emotion on the Emotion & Feeling Wheel, then automatically highlights and navigates to that emotion. Rate-limited to 3 uses per hour.

## API

### POST /api/match-feeling

Match a text description to an emotion on the wheel.

**Request:**
```json
{
  "text": "I feel like nobody listens to me"
}
```

**Response:**
```json
{
  "core": "Anger",
  "secondary": "Frustrated",
  "tertiary": "Ignored",
  "color": "#e74c3c",
  "description": "Feeling overlooked or unheard...",
  "ci": 0,
  "si": 2,
  "ti": 1,
  "wheelSlug": "feelings"
}
```

**Rate Limits:** 3 requests per hour per IP address.

**Error Codes:**
- `400` — No text provided.
- `429` — Rate limit exceeded.
- `500` — Internal server error.
- `502` — AI service unavailable.

## Data Structure

Wheel data follows a consistent hierarchical schema:

```
WheelConfig
├── title: string
├── slug: string
├── description: string
├── data: CoreItem[]
│   ├── name: string
│   ├── color: string (hex)
│   └── secondary: SecondaryItem[]
│       ├── name: string
│       └── tertiary: TertiaryItem[]
│           ├── name: string
│           └── description: string
```

## Tech Stack

- **Frontend**: Next.js (App Router), React, TypeScript, Tailwind CSS
- **Backend**: Convex (serverless real-time database and functions)
- **Authentication**: Google OAuth via Convex Auth
- **AI**: OpenRouter API (Mistral Nemo)
- **Visualization**: Visx (word clouds)
- **Hosting**: Vercel

## Use Cases

- **Individuals**: Self-awareness, journaling prompts, therapy preparation.
- **Therapists**: Client emotion identification, session check-ins.
- **Teams**: Group check-ins, retrospectives, engagement surveys.
- **Organizations**: Employee wellbeing assessments, workshop facilitation.
- **Educators**: Emotional literacy in classrooms.

## Links

- Website: https://feelinghq.com
- How It Works: https://feelinghq.com/how-it-works