The light in emotional darkness
A mental wellness platform for safe expression, peer support, and emotional wellbeing.
- Overview
- Problem Statement
- Solution
- Key Features
- System Architecture
- Tech Stack
- Project Folder Structure
- Installation & Setup
- Running the Project Locally
- API Overview
- Future Improvements
- Contributing
- License
- Authors
LUMORA is a full-stack mental wellness platform that helps users express emotions, track mood, and receive peer support through safe, moderated digital spaces. It combines journaling, mood tracking, anonymous peer chat, and community interaction into a single application designed with empathy and safety at its core.
Many people—especially students, young adults, LGBTQIA+ communities, and older adults—struggle silently with their mental health. Stigma, family pressure, and limited access to affordable support make it difficult to speak openly about what they’re going through. Public social platforms are noisy, performative, and rarely feel safe enough for honest vulnerability, especially for those who already face judgment or isolation. Lumora is a calm, anonymous web app designed to fill this gap. It provides a gentle space where individuals can vent, journal, and connect with supportive peers through community zones and 1:1 conversations—without revealing their identity or worrying about how others will react.
LUMORA addresses these challenges by providing:
- Write & Vent Journaling — a private space to process emotions with optional expiration (shelf life) so entries disappear when the user is ready to let go.
- Mood Tracking Dashboard — visual analytics of emotional trends over time.
- Anonymous Peer Chat — real-time, moderated 1-on-1 conversations where users are matched by topic and remain completely anonymous.
- Community Zones — themed discussion spaces (including protected circles for specific communities) where users can share posts, reply, and react.
- Server-side Moderation — automated profanity detection, commercial spam filtering, and progressive violation enforcement to keep all spaces safe.
| Feature | Description |
|---|---|
| 🔐 User Authentication | Secure signup/login with JWT-based authentication and bcrypt password hashing |
| 🏠 Onboarding & Dashboard | Personalized landing page with aggregated wellness stats (mood averages, journal count, peer sessions) |
| 📝 Write & Vent Journal | Create journal entries with mood scores, custom icons, and configurable shelf life (auto-expiry) |
| 📊 Mood Tracking | 14-day mood trend analytics with daily average scores |
| 💬 Anonymous Peer Chat | Real-time WebSocket-based 1-on-1 chat with topic-based matching, seeker/listener roles, and anonymous identities |
| 🛡️ Automated Moderation | Server-side profanity and spam detection with progressive warnings and auto-session termination after 3 violations |
| 🌐 Community Zones | Themed discussion spaces with posts, replies, and "I Hear You" reactions |
| 🔒 Protected Circles | Sanctuary spaces (Women's Circle, LGBTQ+ Circle) with friction-gated access for safe community interaction |
| 🚩 Reporting & Blocking | Users can report sessions/posts and block peers they don't want to interact with again |
| 💛 Crisis Detection | Client-side detection of crisis language with immediate display of helpline resources |
┌─────────────────────┐ WebSocket (Socket.IO) ┌──────────────────────┐
│ │ ◄──────────────────────────────────► │ │
│ React Frontend │ │ Flask Backend │
│ (Vite + Tailwind) │ ◄────── REST API (Axios/JSON) ────► │ (Flask-SocketIO) │
│ │ │ │
└─────────────────────┘ └──────────┬───────────┘
│
│ SQLAlchemy ORM
│
┌─────────▼──────────┐
│ │
│ PostgreSQL │
│ Database │
│ │
└────────────────────┘
- Frontend communicates with the backend via REST APIs (Axios) and WebSocket (Socket.IO) for real-time peer chat.
- Backend handles authentication, business logic, moderation, and database operations.
- Database stores users, journal entries, chat sessions, messages, community posts, moderation events, and more.
| Layer | Technology |
|---|---|
| Frontend | React 18, Vite, Tailwind CSS, Zustand (state management) |
| Backend | Python, Flask 3.1, Flask-SocketIO, Eventlet |
| Database | PostgreSQL, SQLAlchemy 2.0, Flask-SQLAlchemy |
| Authentication | JWT (PyJWT), bcrypt |
| Real-time | Socket.IO (flask-socketio + socket.io-client) |
| HTTP Client | Axios |
| Utilities | clsx, tailwind-merge, python-dotenv |
lumora-react/
├── lumora-backend/
│ ├── app.py # Application factory & entry point
│ ├── config.py # Environment configuration
│ ├── extensions.py # Shared Flask extensions (SocketIO)
│ ├── requirements.txt # Python dependencies
│ ├── socket_events.py # WebSocket event handlers
│ ├── database/
│ │ └── db.py # SQLAlchemy setup & model registration
│ ├── models/
│ │ ├── user_model.py # User model
│ │ ├── journal_model.py # Journal entry model
│ │ ├── chat_session.py # Chat session model
│ │ ├── message.py # Chat message model
│ │ ├── matching_queue.py # Matching queue model
│ │ ├── block.py # User block model
│ │ ├── report.py # Session report model
│ │ ├── feedback.py # Session feedback model
│ │ ├── moderation.py # Moderation event model
│ │ ├── community_zone.py # Community zone model
│ │ ├── community_post.py # Community post model
│ │ ├── community_reply.py # Community reply model
│ │ ├── community_reaction.py # Community reaction model
│ │ └── community_report.py # Community report model
│ ├── routes/
│ │ ├── auth_routes.py # Authentication endpoints
│ │ ├── chat_routes.py # Peer chat endpoints
│ │ ├── community_routes.py # Community zone endpoints
│ │ ├── journal_routes.py # Journal endpoints
│ │ └── dashboard_routes.py # Dashboard stats endpoint
│ ├── services/
│ │ ├── auth_service.py # Auth business logic
│ │ ├── chat_service.py # Chat session & message logic
│ │ ├── matching_service.py # Queue & matching logic
│ │ ├── community_service.py# Community CRUD & zone seeding
│ │ ├── moderation_service.py # Profanity/spam detection & enforcement
│ │ └── reflection_service.py # Reflection utilities
│ └── utils/
│ ├── jwt_utils.py # JWT encode/decode & decorator
│ ├── password_utils.py # bcrypt hash/verify helpers
│ ├── topic_matcher.py # Topic overlap & circle compatibility
│ └── zone_permissions.py # Zone access permission checks
│
├── lumora-frontend/
│ ├── index.html
│ ├── package.json
│ ├── vite.config.js
│ └── src/
│ ├── App.jsx # Root component (routing, layout, auth guard)
│ ├── main.jsx # React entry point
│ ├── index.css # Global styles (Tailwind)
│ ├── components/
│ │ ├── features/
│ │ │ ├── AuthView.jsx # Login / Signup
│ │ │ ├── HomeView.jsx # Dashboard landing
│ │ │ ├── JournalView.jsx # Write & Vent journal
│ │ │ ├── ChatView.jsx # Anonymous peer chat
│ │ │ ├── CommunityView.jsx # Community zones & posts
│ │ │ └── ZonedCard.jsx # Zone card component
│ │ └── ui/
│ │ └── FrictionGate.jsx # Confirmation gate for protected zones
│ ├── lib/
│ │ └── utils.js # cn() utility (clsx + tailwind-merge)
│ ├── services/
│ │ ├── api.js # Axios instance configuration
│ │ ├── authService.js # Auth API calls
│ │ └── journalService.js # Journal API calls
│ └── store/
│ └── userStore.js # Zustand user state management
│
└── README.md
| Software | Version |
|---|---|
| Node.js | v18+ |
| Python | 3.10+ |
| PostgreSQL | 14+ |
| Git | Latest |
# Navigate to the backend directory
cd lumora-backend
# Create a virtual environment
python -m venv venv
# Activate the virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate
# Install Python dependencies
pip install -r requirements.txt# Navigate to the frontend directory
cd lumora-frontend
# Install Node dependencies
npm installCreate a .env file in the lumora-backend/ directory:
SECRET_KEY=your_flask_secret_key
JWT_SECRET=your_jwt_signing_secret
DATABASE_URL=postgresql://postgres:your_password@localhost:5432/lumora_db| Variable | Description |
|---|---|
SECRET_KEY |
Flask application secret key for session security |
JWT_SECRET |
Secret key used to sign and verify JWT tokens |
DATABASE_URL |
PostgreSQL connection URI in the format postgresql://user:password@host:port/dbname |
-
Ensure PostgreSQL is running on your machine.
-
Create the database:
CREATE DATABASE lumora_db;- Tables are created automatically on first application startup via
db.create_all(). Community zones are also seeded automatically.
Start the backend (from lumora-backend/):
python app.pyThe backend will start on http://localhost:5000 with SocketIO and debug mode enabled.
Start the frontend (from lumora-frontend/):
npm run devThe frontend will start on http://localhost:5173 (Vite dev server).
Verify the backend is running:
curl http://localhost:5000/
# Expected: {"status": "Lumora backend is running 🌸"}Verify SocketIO is operational:
curl "http://localhost:5000/socket.io/?EIO=4&transport=polling"
# Expected: A response containing a session ID and "websocket" in upgradesAll authenticated endpoints require a JWT token in the Authorization: Bearer <token> header.
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /api/auth/signup |
No | Create a new user account |
| POST | /api/auth/login |
No | Authenticate and receive a JWT token |
| GET | /api/auth/me |
JWT | Get current user profile |
| POST | /api/auth/forgot-password |
No | Generate a password reset token |
| POST | /api/auth/reset-password |
No | Reset password with a valid token |
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /api/chat/join |
JWT | Join the matching queue |
| POST | /api/chat/cancel |
JWT | Cancel matching search |
| GET | /api/chat/status |
JWT | Check queue status |
| GET | /api/chat/session/:id |
JWT | Get session details |
| POST | /api/chat/end-session |
JWT | End an active session |
| POST | /api/chat/send-message |
JWT | Send a message |
| GET | /api/chat/messages/:id |
JWT | Fetch messages (supports ?after= polling) |
| POST | /api/chat/report |
JWT | Report a session |
| POST | /api/chat/block |
JWT | Block a user |
| POST | /api/chat/feedback |
JWT | Submit session feedback |
| POST | /api/chat/moderation |
JWT | Log a moderation event |
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /api/community/zones |
JWT | List all community zones |
| GET | /api/community/zones/:id/posts |
JWT | Get posts in a zone (paginated) |
| POST | /api/community/posts |
JWT | Create a new post |
| DELETE | /api/community/posts/:id |
JWT | Delete own post |
| GET | /api/community/posts/:id/replies |
JWT | Get replies for a post |
| POST | /api/community/posts/:id/reply |
JWT | Reply to a post |
| DELETE | /api/community/replies/:id |
JWT | Delete own reply |
| POST | /api/community/posts/:id/hear |
JWT | React with "I Hear You" |
| DELETE | /api/community/posts/:id/hear |
JWT | Remove reaction |
| POST | /api/community/posts/:id/report |
JWT | Report a post |
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /api/journal/create |
JWT | Create a journal entry |
| GET | /api/journal/user/:id |
JWT | Get all non-expired entries (own only) |
| DELETE | /api/journal/delete/:id |
JWT | Delete a journal entry |
| GET | /api/journal/mood-trend/:id |
JWT | 14-day mood trend data |
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /api/dashboard/stats |
JWT | Aggregated wellness stats (mood avg, journal count, sessions, posts) |
The peer chat system uses Socket.IO for real-time communication. JWT authentication is verified on connection.
| Event | Direction | Description |
|---|---|---|
connect |
Client → Server | Authenticate with JWT via auth.token |
join_queue |
Client → Server | Join the matching queue with role, topics, and circle preference |
leave_queue |
Client → Server | Cancel matching and leave the queue |
send_message |
Client → Server | Send a message in an active session |
end_session |
Client → Server | End an active chat session |
queue_joined |
Server → Client | Confirmation that user is waiting in the queue |
match_found |
Server → Client | Both users notified of a successful match with session details |
receive_message |
Server → Client | Broadcast a new message to all participants in a session room |
session_ended |
Server → Client | Notify both users that the session has ended |
session_terminated |
Server → Client | Notify that the session was terminated due to moderation violations |
moderation_warning |
Server → Client | Warn the sender that their message was blocked |
error |
Server → Client | Error message for invalid operations |
- 🤖 AI-Powered Mood Insights — Use NLP to analyze journal entries and provide personalized emotional insights.
- 📱 Mobile App — Build a React Native or Flutter mobile application.
- 🌍 Multi-language Support — Localize the platform for non-English speaking users.
- 👩⚕️ Professional Counselor Integration — Allow licensed counselors to join as verified listeners.
- 📈 Advanced Analytics — Weekly/monthly wellness reports with exportable data.
- 🔔 Push Notifications — Notify users of community replies, chat matches, and wellness reminders.
- 🧪 Comprehensive Testing — Add unit tests, integration tests, and end-to-end test coverage.
- 🐳 Docker Deployment — Containerize the application for simplified deployment.
Contributions are welcome! Follow these steps to contribute:
-
Fork the repository.
-
Create a feature branch:
git checkout -b feature/your-feature-name
-
Make your changes and commit with a clear message:
git commit -m "feat: add your feature description" -
Push to your branch:
git push origin feature/your-feature-name
-
Open a Pull Request with a detailed description of your changes.
- Follow existing code style and project structure.
- Keep PRs focused — one feature or fix per pull request.
- Do not commit
.envfiles, database credentials, or API keys. - Test your changes locally before submitting.
This project is licensed under the MIT License.
You are free to use, modify, and distribute this software in accordance with the terms of the license.
Varshini Nandula
Vakalapudi Roshini
Built with 💛 for emotional wellbeing
LUMORA — the light in emotional darkness 🌸