A full-stack AI-powered mental wellness companion featuring empathetic chat, mood tracking, smart journaling, and guided wellness exercises.
AI Companion — referred to internally as my-v0-project, built and scaffolded using v0.dev by Vercel.
AI Companion is a full-stack mental wellness web application that provides users with a judgment-free space to track their mood, journal their thoughts, chat with an empathetic AI, and practice guided wellness exercises. It is designed with privacy, simplicity, and emotional accessibility in mind.
- AI Companion Chat — Judgment-free conversation with empathetic AI responses (mock responses included; OpenAI integration ready)
- Smart Journaling — Write journal entries and receive AI-generated reflections
- Mood Tracking — Log daily moods (calm, happy, anxious, sad, neutral) with intensity scores and notes
- Guided Exercises — Four types of calming exercises: Breathing, Grounding, Affirmations, and Visualization
- Wellness Dashboard — Mood history, insights, and progress overview
- Dynamic Theming — Light / Dark / Auto theme switching with mood-reactive theming support
- Authentication — Login, Signup, and Demo login support
v0-ai-wellness-companion/
│
├── app/ # Next.js App Router (Frontend)
│ ├── page.tsx # Login / Signup page
│ ├── layout.tsx # Root layout with providers
│ ├── globals.css # Global styles
│ └── dashboard/
│ └── page.tsx # Protected dashboard page
│
├── components/
│ ├── layout/
│ │ └── sidebar.tsx # App sidebar with navigation
│ ├── dashboard/
│ │ └── dashboard-view.tsx # Main dashboard view
│ └── ui/ # shadcn/ui component library
│
├── lib/
│ ├── auth-context.tsx # Auth state (login, signup, logout)
│ ├── mood-context.tsx # Mood state management
│ └── theme-context.tsx # Theme (light/dark/auto) + mood theme
│
├── backend/ # FastAPI Backend (Python)
│ ├── app/
│ │ ├── main.py # FastAPI app entry point + CORS
│ │ ├── database.py # MongoDB connection handlers
│ │ ├── models/
│ │ │ └── user.py # Pydantic models (User, Token)
│ │ ├── api/
│ │ │ ├── auth.py # POST /auth/signup, /auth/login
│ │ │ ├── chat.py # POST /chat/send, GET /chat/history
│ │ │ ├── journal.py # POST /journal/create, GET /journal/list
│ │ │ ├── mood.py # POST /mood/log, GET /mood/history
│ │ │ └── exercises.py # GET /exercises/list, GET /exercises/:id
│ │ └── services/ # Business logic services
│ └── requirements.txt # Python dependencies
│
├── docker-compose.yml # Docker setup (MongoDB + Backend + Frontend)
├── next.config.mjs # Next.js configuration
├── tsconfig.json # TypeScript configuration
└── package.json # Node.js dependencies
| Technology | Purpose |
|---|---|
| Next.js 16 | React framework (App Router) |
| React 19 | UI library |
| TypeScript 5 | Type safety |
| Tailwind CSS 4 | Utility-first styling |
| shadcn/ui + Radix UI | Accessible component library |
| Recharts | Mood analytics & data visualization |
| Lucide React | Icon set |
| next-themes | Dark/Light/Auto theming |
| Vercel Analytics | Usage analytics |
| React Hook Form + Zod | Form handling & validation |
| Technology | Purpose |
|---|---|
| FastAPI | Python web framework |
| Uvicorn | ASGI server |
| MongoDB + Motor | NoSQL database (async driver) |
| Pydantic v2 | Data validation & serialization |
| PyJWT / python-jose | JWT authentication |
| Passlib + bcrypt | Password hashing |
| OpenAI SDK | AI response generation (ready to integrate) |
| python-dotenv | Environment variable management |
| Technology | Purpose |
|---|---|
| Docker Compose | Local multi-service orchestration |
| MongoDB 7.0 | Persistent data store |
| Vercel (recommended) | Frontend deployment |
| Gunicorn | Production WSGI for backend |
- Node.js 18+
- Python 3.10+
- MongoDB (local or Atlas)
- An OpenAI API key (for real AI responses)
# Install dependencies
npm install
# Start the development server
npm run devThe app will run at http://localhost:3000.
Environment variable (create a .env.local file):
VITE_API_URL=http://localhost:8000
cd backend
# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Create your .env file
cp .env.example .env
# Edit .env with your values (see Environment Variables below)
# Start the backend server
uvicorn app.main:app --reloadThe API will run at http://localhost:8000.
docker-compose up -dThis starts MongoDB, the FastAPI backend, and the Next.js frontend together.
DATABASE_URL=mongodb://localhost:27017/ai-companion
JWT_SECRET=your-super-secret-key
OPENAI_API_KEY=your-openai-api-key
ENVIRONMENT=development
FRONTEND_URL=http://localhost:3000VITE_API_URL=http://localhost:8000All routes are prefixed with /api.
| Method | Endpoint | Description |
|---|---|---|
| POST | /auth/signup |
Register a new user |
| POST | /auth/login |
Log in and receive a JWT token |
| Method | Endpoint | Description |
|---|---|---|
| POST | /chat/send |
Send a message; receive an AI response |
| GET | /chat/history/{session_id} |
Retrieve chat history for a session |
| Method | Endpoint | Description |
|---|---|---|
| POST | /journal/create |
Create a new journal entry with AI reflection |
| GET | /journal/list/{user_id} |
List all journal entries for a user |
| Method | Endpoint | Description |
|---|---|---|
| POST | /mood/log |
Log a mood (calm / happy / anxious / sad / neutral) with intensity 1–10 |
| GET | /mood/history/{user_id} |
Retrieve mood history for a user |
| Method | Endpoint | Description |
|---|---|---|
| GET | /exercises/list |
Get all available guided exercises |
| GET | /exercises/{exercise_id} |
Get a specific exercise by ID |
| Method | Endpoint | Description |
|---|---|---|
| GET | / |
API info and status |
| GET | /health |
Health check endpoint |
{
"_id": ObjectId,
"email": str,
"password": str, # bcrypt hashed
"name": str,
"created_at": datetime,
"updated_at": datetime
}{
"_id": ObjectId,
"user_id": ObjectId,
"messages": [
{ "role": "user" | "assistant", "content": str, "timestamp": datetime }
],
"created_at": datetime
}{
"_id": ObjectId,
"user_id": ObjectId,
"title": str,
"content": str,
"ai_reflection": str,
"date": datetime,
"created_at": datetime
}{
"_id": ObjectId,
"user_id": ObjectId,
"mood": "calm" | "happy" | "anxious" | "sad" | "neutral",
"intensity": int, # 1–10
"note": str,
"date": datetime
}The sidebar provides access to all app sections:
| Page | Route | Description |
|---|---|---|
| Dashboard | /dashboard |
Overview, mood insights |
| Chat | /chat |
AI companion conversation |
| Journal | /journal |
Personal journal with AI reflections |
| Mood Tracker | /mood |
Daily mood logging and history |
| Exercises | /exercises |
Guided breathing, grounding, affirmations, visualization |
| Settings | /settings |
Theme and account preferences |
To try the app without creating an account:
Email: demo@example.com
Password: demo123
Or click the "Try Demo" button on the login page.
npm run build
# Deploy via Vercel CLI or connect your GitHub repo at vercel.compip install gunicorn
gunicorn app.main:app --workers 4docker-compose -f docker-compose.yml up -d --buildnpm run dev # Start dev server (localhost:3000)
npm run build # Production build
npm run lint # Lint with ESLint
npm run start # Start production serveruvicorn app.main:app --reload # Dev server with hot reload
pytest # Run test suite
black . # Format code
flake8 . # Lint code- Chat responses are currently mocked (random pre-written replies). Swap in the OpenAI SDK call in
backend/app/api/chat.pywith yourOPENAI_API_KEYfor real AI responses. - Authentication uses an in-memory store in the current backend. Wire up MongoDB properly for production persistence.
- Password hashing is not yet applied in
auth.py— integratepasslibbcrypt before going to production. - JWT tokens are issued as
"demo_token"— implement real JWT signing usingpython-jose.
- Fork the repository
- Create a feature branch:
git checkout -b feature/your-feature - Commit your changes:
git commit -m "feat: add your feature" - Push to the branch:
git push origin feature/your-feature - Open a pull request
MIT License — see LICENSE for details.