JoyFormula

Your Joy Theorem summarized from your happiness patterns
share your happy moments and get your formula ready!
Collection of all your joy theorem
Build your habits of happiness in your Joy Repo!
gift if you feel low-energy!
click to see the detail
Your Joy Formula is here

Inspiration

JoyFormula was inspired by Stanford’s Designing Your Life course, which encourages people to journal happy moments to better understand what brings them joy. We found this practice meaningful and effective, but noticed that many mental wellness apps turn reflection into a chore. They often feel rigid, time-consuming, or like homework. We wanted to design something lighter and more human: an experience that feels like sharing a happy moment with a friend who listens and helps you understand why it mattered.

What it does

JoyFormula helps users decode and replicate their happiness. Users simply message a happy moment, and an AI coach responds like a supportive friend, asking a few gentle follow-up questions. The system then transforms the moment into a structured “Joy Formula” made up of five elements: Scene, People, Action, Trigger, and Senses. Over time, JoyFormula analyzes multiple entries to reveal personal happiness patterns and proactively suggests when users might recreate those joyful moments in real life.

How we built it

We designed the product experience in Figma, focusing on a calm, conversational interface that reduces friction and feels natural to use. We then used Figma Make to turn static designs into interactive screens by prompting them, allowing us to rapidly prototype without heavy front-end engineering.
On the back end, we built the AI system that powers the experience, including the conversational personality, system prompts, follow-up question logic, Joy Formula structure, and output formatting. The front end and back end communicate to deliver a seamless, chat-based reflection flow.

Core Languages & Frameworks:

Languages: Python (Backend), TypeScript / JavaScript (Frontend), and SQL.
Frontend Core: React 18.3.1 powered by Vite 6.3.5 (utilizing the SWC compiler for high-speed builds).
Backend Core: FastAPI 0.115.0 with Uvicorn (ASGI server) for high-performance asynchronous execution.
Database Layer: PostgreSQL for production environments and SQLite for local development, managed via the SQLAlchemy 2.0 ORM.

Frontend Ecosystem:

Styling & UI: Tailwind CSS for utility-first styling paired with Radix UI for accessible, unstyled primitives.
Data Visualization: Recharts, specifically utilized for joy pattern visualization.
State & Logic: React Hook Form for robust form management and Axios for API requests.

UX/UI Components:

Lucide React: Iconography.
Next-themes: Seamless dark mode support.
framer-motion: Advanced UI animations.
cmdk: Integrated command palette.
sonner: Polished toast notifications.

AI / LLM Multi-Provider Architecture
The system employs a unified abstraction layer, allowing for seamless switching between high-performance models:

Primary Model: Google Gemini ($gemini-2.5-flash-preview$)
Extensibility: Built-in support for integrating custom AI endpoints.

Dev Tools & Infrastructure:

Validation: Pydantic v2 for strict data validation and settings management.
Documentation: Auto-generated interactive API docs via Swagger / OpenAPI.
Developer Experience: Rich for enhanced CLI terminal interfaces and python-dotenv for environment variable management.
Localization: A custom i18n module providing native support for English and Chinese. (currently setup in English)

Challenges we ran into

Our biggest challenge was connecting the front end and back end, as they were initially built in isolation. Differences in assumptions about data structure, output formats, and interaction flow caused friction during integration. We resolved this by clearly aligning the contract between the two systems, defining what data is passed, how responses are structured, and how the UI should react to them.

Accomplishments that we're proud of

We’re proud of creating a mental wellness tool that feels genuinely friendly rather than clinical. Turning abstract emotional experiences into structured, reusable insights, without making users feel like they’re doing work, was a major win. We’re also proud of how quickly we went from concept to an interactive, AI-powered prototype within the hackathon timeframe.

What we learned

We learned that structure can be powerful when it’s invisible. By embedding reflection inside conversation, users can gain deep insights without cognitive overload. We also learned the importance of aligning design and AI system thinking early, especially when building conversational products that rely on tight front-end and back-end coordination.

What's next for JoyFormula

Next, we plan to integrate JoyFormula directly into iMessage, turning it into a channel users already use every day. By meeting users where they naturally share moments, we want the experience to feel frictionless, intuitive, and effortless, like texting a friend about something that made you happy, rather than opening a separate mental wellness app.