Kura - Mental Health Audio Journal

Kura is an AI-powered audio journaling platform that helps users track their emotional journey through natural voice recordings and intelligent analysis.

🏥 Important: Kura is NOT a medical tool. It's a personal wellness companion designed to complement, not replace, professional mental health care.

✨ Features

• 🎤 Audio Recording: MediaRecorder (WebM/Opus) → ffmpeg (WAV 16kHz mono)
• ☁️ Cloud Storage: Google Cloud Storage with automatic backup
• 📊 Weekly Reports: AI-powered emotional analysis with HTML/PDF export
• 🌦️ Mental Weather: Emotion tracking using weather metaphors instead of clinical scores
• 🔐 Privacy First: Your data, your control - delete anytime
• 📱 Responsive Design: Works seamlessly on desktop and mobile

🎯 Core Values

1. Non-Medical: Kura is a personal wellness tool, not a diagnostic instrument
2. Data Ownership: Full user control - your recordings are never used to train AI models
3. Weather Metaphor: Emotional states represented as weather (☀️ sunny to 🌩️ stormy) instead of cold clinical scores

🚀 Tech Stack

Frontend

• React 18 + TypeScript
• Material-UI (MUI) v7 for design
• Vite for fast development
• Zustand for state management
• React Router v6 for navigation

Backend

• FastAPI (Python 3.11)
• Google Cloud Platform (Cloud Run, Cloud Storage, Speech-to-Text)
• Gemini 2.0 Flash for emotion analysis
• Eventarc for automatic pipeline triggers

📋 Prerequisites

• Node.js 18+
• Python 3.11+
• Docker & Docker Compose
• GCP account with configured Cloud Storage bucket

🛠️ Development Setup

Option 1: Automatic Script

./dev-setup.sh

Option 2: Manual Setup

1. Environment Variables

# web/.env
cp web/.env.sample web/.env
# Edit VITE_BACKEND_URL=http://localhost:8000

# api/.env
cp api/.env.sample api/.env
# Edit GCP_BUCKET=your-bucket-name
# Edit GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

2. Frontend (React + Vite)

cd web
npm install
npm run dev  # → http://localhost:3000

3. Backend (FastAPI)

cd api
python -m venv venv
source venv/bin/activate  # Linux/Mac
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000  # → http://localhost:8000

🐳 Docker Launch (Recommended)

# Build and launch complete stack
docker-compose up --build

# Web: http://localhost:3000
# API: http://localhost:8000
# Swagger: http://localhost:8000/docs

☁️ GCS Configuration

1. Create a GCS bucket
2. Generate a service account JSON key
3. Set GCP_BUCKET and GOOGLE_APPLICATION_CREDENTIALS in api/.env

🏗️ Project Architecture

web/           # React 18 + TypeScript + Vite
├── src/
│   ├── components/    # Banner, Navbar, ChatWindow, etc.
│   ├── routes/        # Dashboard, Recorder, History, Report, Mental Weather
│   ├── store/         # Zustand (state management)
│   ├── api/          # HTTP client
│   ├── theme/        # MUI theme customization
│   └── types/        # TypeScript interfaces
api/           # FastAPI + ffmpeg
├── app/
│   ├── main.py       # API routes
│   ├── storage.py    # GCS operations
│   └── audio.py      # ffmpeg audio processing

📱 User Interface Pages

🏠 Dashboard

Overview of your emotional journey with weekly weather summary and key metrics.

🎤 Recorder

Voice recording interface with real-time audio capture and instant upload.

📅 History

Chronological list of all sessions with emotion scores and detailed transcriptions.

📊 Reports

Weekly summaries with AI-generated insights, highlights, and exportable HTML/PDF reports.

🌦️ Mental Weather

Visual timeline showing emotional progression across weeks using weather metaphors.

✅ QA Checklist

Functional Tests

• Recording: Start/Stop → local audio preview
• Upload: WebM → server → GCS (.webm + .wav 16kHz)
• History: Display local + server sessions list
• Reports: Weekly summaries → downloadable HTML export
• Mental Weather: 4-week emotional progression visualization
• Delete: Session removal via API

Technical Tests

• CORS: http://localhost:3000 → http://localhost:8000
• Docker: docker-compose up → everything works
• Health: GET /healthz → {ok: true}
• ffmpeg: WebM → WAV 16kHz mono conversion
• GCS: Storage with structure mj-audio-raw/<YYYY-WXX>/session_*/

UI Tests

• Responsive: mobile/desktop compatibility
• Banner: non-medical disclaimer displayed
• Navigation: React Router v6 working
• State: Zustand local cache functional
• Theme: MUI custom theme applied correctly

🐛 Troubleshooting

CORS Errors

• Verify VITE_BACKEND_URL in web/.env
• Check API CORS configuration

GCS Errors

• Verify service account credentials
• Check bucket permissions and existence

ffmpeg Errors

• Ensure ffmpeg is installed in API container
• Check audio file format compatibility

Audio Recording Issues

• Test with different browsers (Chrome recommended)
• Verify microphone permissions
• Check MediaRecorder browser support

🔗 Related Repositories

• Backend Pipeline: GCPU-hackathon-vertex - ML pipeline with Gemini 2.0
• Documentation: See DEMO_GUIDE.md for complete presentation script

📄 License

This project was developed for the Google Cloud Platform University Hackathon 2025.

🙏 Acknowledgments

• Google Cloud Platform for infrastructure
• Gemini 2.0 Flash for AI-powered emotion analysis
• Material-UI team for the design system

---

Made with ❤️ for mental wellness