https://github.com/tulsibasetti/moddmapper
A RESTful Mood Tracking API with Insights and UI
https://github.com/tulsibasetti/moddmapper
fastapi mysql-database python3 streamlit
Last synced: 3 months ago
JSON representation
A RESTful Mood Tracking API with Insights and UI
- Host: GitHub
- URL: https://github.com/tulsibasetti/moddmapper
- Owner: TulsiBasetti
- Created: 2025-06-20T13:10:22.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-20T14:28:18.000Z (about 1 year ago)
- Last Synced: 2025-06-20T14:41:48.469Z (about 1 year ago)
- Topics: fastapi, mysql-database, python3, streamlit
- Language: Python
- Homepage:
- Size: 16.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🧠 MoodMapper – Your Personal Mood Journal & Insight Engine
MoodMapper is a mood journaling platform that helps users log daily emotions and understand their emotional patterns over time. It features a custom-built REST API using Flask and MySQL, with an optional modern frontend powered by Streamlit.
---
## 🚀 Features
- 🧾 REST API with 8 endpoints
- 👤 User registration and listing
- 📅 Mood logging with trigger notes
- ✏️ Edit and delete mood logs
- 📊 View mood summary and recent activity
- 💻 Frontend using Streamlit
- 🔐 Secrets and URLs stored in `.env`
- ✅ API tested using Postman
---
## 📦 Tech Stack
| Layer | Technology |
|--------------|-------------------------------|
| Backend | Python + Flask (REST API) |
| Database | MySQL (`mysql-connector-python`) |
| Frontend | Streamlit (optional UI) |
| Config | `.env` file for secure secrets |
| API Testing | Postman |
---
## 🔌 API Endpoints
### 👤 User APIs
| Method | Endpoint | Description |
|--------|--------------|--------------------|
| POST | `/users` | Register a new user |
| GET | `/users` | List all users |
### 📅 Mood APIs
| Method | Endpoint | Description |
|--------|-------------------------|---------------------------------|
| POST | `/moods` | Log a new mood |
| GET | `/moods/` | View all moods for a user |
| PUT | `/moods/` | Update a specific mood entry |
| DELETE | `/moods/` | Delete a specific mood entry |
### 📊 Insights APIs
| Method | Endpoint | Description |
|--------|-------------------------------------------|---------------------------|
| GET | `/moods/stats/summary/` | Mood counts by type |
| GET | `/moods/recent/` | 5 most recent mood entries|
---
## 🗃️ Database Schema
You can either use the SQL below or run the provided `mysql.sql` script.
```sql
CREATE DATABASE IF NOT EXISTS moodmapper;
USE moodmapper;
CREATE TABLE IF NOT EXISTS users (
id INT AUTO_INCREMENT PRIMARY KEY,
name VARCHAR(100) NOT NULL,
email VARCHAR(100) UNIQUE
);
CREATE TABLE IF NOT EXISTS moods (
id INT AUTO_INCREMENT PRIMARY KEY,
mood VARCHAR(50) NOT NULL,
trigger_note TEXT,
date DATE NOT NULL,
user_id INT,
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);
```
## ⚙️ Environment Setup (`.env`)
Create a `.env` file in your project root directory with the following content:
```env
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=your_mysql_password
DB_NAME=moodmapper
BASE_URL=http://127.0.0.1:5000
```
✅ The frontend uses BASE_URL to point to the backend — helpful for future deployment flexibility.
## 🧑💻 How to Run the Project
1. Clone & Install
```
git clone https://github.com/your-username/moodmapper.git
cd moodmapper
# Create virtual environment
python -m venv moodmapper_venv
moodmapper_venv\Scripts\activate # Windows
source moodmapper_venv/bin/activate # macOS/Linux
# Install dependencies
pip install -r requirements.txt
```
2. Set Up Database
You can either:
- Run mysql.sql in SQLYog or MySQL CLI, or
- Paste the SQL schema (shown above)
- Make sure the database name is moodmapper.
3. Run Flask Backend (Terminal 1)
```
python app.py
```
4. Run Streamlit Frontend (Terminal 2)
```
streamlit run frontend_app.py
```
Keep both Flask and Streamlit running in separate terminals for full functionality.
## 📮 Testing the API with Postman
All 8 API endpoints were tested using Postman to ensure:
- Correct request/response formats
- Expected HTTP status codes
- Error handling and validations
You can import a Postman collection or test manually using POST, GET, PUT, DELETE methods with the base URL:
http://127.0.0.1:5000/
## 📊 Sample API Request
### POST/users
```
{
"name": "lisa",
"email": "lisa@example.com"
}
```
Response:
```
{
"message": "User added",
"user_id": 10
}
```
### POST /moods
```
{
"mood": "Happy",
"trigger_note": "Completed project milestone",
"user_id": 1
}
```
Response:
```
{
"message": "Mood logged successfully"
}
```
### Get Moods for a User (GET)
- Method: GET
- URL: http://localhost:5000/moods/1
```
[
{
"date": "Fri, 20 Jun 2025 00:00:00 GMT",
"id": 3,
"mood": "excited",
"trigger_note": "completed project",
"user_id": 2
},
{
"date": "Fri, 20 Jun 2025 00:00:00 GMT",
"id": 4,
"mood": "excited",
"trigger_note": "had a fun day ",
"user_id": 2
},
{
"date": "Fri, 20 Jun 2025 00:00:00 GMT",
"id": 5,
"mood": "excited",
"trigger_note": "had a fun day ",
"user_id": 2
}
]
```
### Recent 5 Moods (GET)
Method: GET
URL: http://localhost:5000/moods/recent/1
```
[
{
"date": "Fri, 20 Jun 2025 00:00:00 GMT",
"id": 2,
"mood": "happy",
"trigger_note": "completed project",
"user_id": 1
},
{
"date": "Fri, 20 Jun 2025 00:00:00 GMT",
"id": 6,
"mood": "happy",
"trigger_note": "attended a session on LLM",
"user_id": 1
},
{
"date": "Fri, 20 Jun 2025 00:00:00 GMT",
"id": 7,
"mood": "happy",
"trigger_note": "attended a session on LLM",
"user_id": 1
},
{
"date": "Fri, 20 Jun 2025 00:00:00 GMT",
"id": 9,
"mood": "Happy",
"trigger_note": "Completed project milestone",
"user_id": 1
}
]
```