MindMirror

Emotion-Aware AI Companion with Real-Time Avatar Conversations, Dynamic Agent Orchestration, Mood Analytics, and IoT-Driven Wellness Feedback

MindMirror is a full-stack emotional wellness platform that combines AI-driven conversational avatars, adaptive agent orchestration, session intelligence, and hardware-driven wellness interventions into a cohesive system for supportive, reflective human-AI interaction.

Problem & Vision

Most people face emotional challenges in isolation. During difficult moments—anxiety, overwhelm, loneliness, sadness—they need someone to notice what they're experiencing before offering solutions.

MindMirror reimagines emotional support by:

Creating emotionally aware conversations through real-time avatar interactions
Remembering and understanding previous interactions to build continuity
Adapting the environment through mood-responsive hardware in real-time
Generating actionable insights through session analysis and transcript intelligence

This is not therapy, counseling, or diagnosis. It's a platform for emotional awareness, wellness reflection, and human-centered technology that meets people where they are.

Key Features

🎭 Real-Time AI Avatar

TRUGEN-powered conversational avatar with natural speech and embodied presence
Emotion-aware dialogue that adapts tone and response style to user state
Multi-modal communication (speech, visual facial expressions, environmental feedback)

🧠 Dynamic Agent Provisioning

Per-session ephemeral agents created on demand with unique system prompts
Context-aware initialization that recalls previous sessions and emotional history
Stateless architecture enabling horizontal scaling and concurrent sessions

🛠️ Runtime Tool Orchestration

Three dynamically provisioned tools bound to each agent:
- save_session_summary – Captures session insights, emotion shifts, and actionable steps
- update_ambient_lighting – Triggers mood-responsive hardware lighting in real-time
- start_breathing_exercise – Activates multi-phase breathing sequences with visual/haptic feedback
Tools execute via secure webhooks with automatic cleanup on session end

📊 Session Intelligence

Full transcript capture with async polling to ensure data consistency
Structured session summaries: topic, emotion arc, key insights, recommended actions
Multi-session context awareness – agents reference past interactions to provide continuity

🏠 IoT & Hardware Integration

Arduino-based peripheral control for:
- Emotion-driven LED lighting with smooth color transitions aligned to detected emotions
- Breathing exercise vibration motors with precise timing (4s inhale, 7s hold, 8s exhale)
- OLED display for real-time face visualization and breathing progress
Serial communication via jSerialComm for low-latency hardware control
Event-driven triggers from AI conversation directly activate wellness interventions

📱 Full-Stack Dashboard

React + TypeScript frontend with Tailwind CSS for responsive, modern UI
Session history grid with emotion tracking, summaries, and downloadable transcripts
Real-time PDF generation of session reflections
Authenticated user workspace with past session review and action tracking

🔐 Secure & Authenticated

JWT-based authentication with Spring Security
Role-based access control (user, admin)
PostgreSQL persistence with Flyway migrations
Webhook validation via HMAC secrets

Architecture Overview

MindMirror follows a stateless, event-driven, cloud-native architecture designed for scalability and real-time responsiveness.

graph TB
subgraph Client["Client Tier"]
A["React Frontend<br/>(Dashboard + Auth)"]
B["TRUGEN Avatar SDK<br/>(Embedded IFrame)"]
end
subgraph Backend["Backend Services<br/>(Spring Boot + Java 21)"]
C["Session Controller<br/>(REST API)"]
D["Webhook Receiver<br/>(Tool Execution)"]
E["Session Service<br/>(Orchestration)"]
F["TrugenAgent Service<br/>(Dynamic Provisioning)"]
G["Hardware Integration<br/>(Serial Communication)"]
H["Transcript Service<br/>(Async Polling + Storage)"]
end
subgraph AI["AI & Knowledge"]
I["TRUGEN API<br/>(Agent Cluster)"]
J["Dynamic Knowledge Bases<br/>(Core Persona + Behavioral Patterns)"]
K["LLM Provider<br/>(Google Gemini 3.1 Pro)"]
end
subgraph Storage["Data Persistence"]
L["PostgreSQL<br/>(Sessions, Users, Transcripts)"]
end
subgraph Hardware["Physical Layer"]
M["Arduino Microcontroller"]
N["NeoPixel LED Ring<br/>(Emotion-Aware Lighting)"]
O["Vibration Motors<br/>(Breathing Guidance)"]
P["OLED Display<br/>(Face + Progress)"]
end
A -->|Start Session| C
C -->|Provision Agent| F
F -->|Create + Bind Tools| I
F -->|Load KB| J
J -->|Content Injection| I
I -->|Avatar URL| B
B -->|Conversation| I
I -->|Tool Execution| D
D -->|Route by Tool| E
E -->|Save Summary| L
D -->|Emotion Update| G
D -->|Breathing Trigger| G
G -->|Serial Commands| M
M --> N
M --> O
M --> P
H -->|Poll TRUGEN| I
H -->|Store Transcript| L
I -->|Use for Context| K
A -->|View History| L

System Flow: End-to-End Session Lifecycle

1. Session Initialization

User clicks "Start Session" → Auth token validated via JWT filter → SessionController.startSession() invoked → SessionService.initializeTrugenSession() called

2. Agent Provisioning (Ephemeral & Stateless)

TrugenAgentService.createEphemeralAgentForUser(userId):
├─ Load past sessions for user (max 3)
├─ Build dynamic system prompt with:
│ ├─ Base philosophy (emotional awareness, non-therapeutic)
│ ├─ Previous session context (topics, outcomes, emotion arcs)
│ └─ Behavioral patterns & grounding techniques
├─ Dynamically provision 3 tools:
│ ├─ Session summary tool (webhook → SessionService)
│ ├─ Emotion lighting tool (webhook → HardwareIntegrationService → Arduino)
│ └─ Breathing exercise tool (webhook → HardwareIntegrationService → Arduino)
├─ Initialize two Knowledge Bases on TRUGEN cluster:
│ ├─ Core KB: Identity constraints & philosophy
│ └─ Behavioral KB: Grounding techniques & patterns
└─ Return agent ID + tool IDs for cleanup

3. Conversation & Real-Time Hardware Sync

Avatar receives user speech → LLM (Gemini 3.1 Pro) generates response → During response:
├─ [Silent] Detects emotion → triggers update_ambient_lighting tool
│ └─ HardwareIntegrationService sends emotion name via serial
│ └─ Arduino maps emotion → RGB color (happy=gold, calm=blue, etc.)
│ └─ NeoPixel ring smoothly transitions to color
│
└─ [When appropriate] If user is anxious/overwhelmed:
├─ Avatar says: "Let's take a deep breath together. Follow the rhythm."
├─ Triggers start_breathing_exercise tool
│ └─ HardwareIntegrationService sends "breath" command via serial
│ └─ Arduino enters breathing mode:
│ ├─ Phase 1 (4s): Inhale - fill NeoPixel ring + vibrate inhale motor
│ ├─ Phase 2 (7s): Hold - full ring + both motors engaged
│ └─ Phase 3 (8s): Exhale - deplete ring + vibrate exhale motor
├─ Agent goes silent during 3 cycles (~57 seconds total)
└─ After completion: Shows "GOOD JOB!" on OLED display

4. Session Capture & Persistence

As conversation progresses:
├─ TRUGEN API streams conversation messages
├─ WebhookController receives tool calls:
│ ├─ save_session_summary: Extracts structured data → SessionHistory entity
│ ├─ update_ambient_lighting: Routes to hardware service
│ └─ start_breathing_exercise: Routes to hardware service
│
└─ TranscriptCronWorker (every 60 seconds):
├─ Polls TRUGEN API for updated transcript
├─ Persists to PostgreSQL as Transcript entity
└─ Marks SyncStatus as complete when all messages received
When user ends session:
├─ Agent lifecycle webhooks captured
├─ Session marked COMPLETED
├─ Agent + all 3 tools deleted from TRUGEN cluster (automatic cleanup)
└─ Transcript finalized and available in dashboard

5. Dashboard Review & Export

User navigates to dashboard → SessionController.getHistory() retrieves all past sessions → React grid displays:
├─ Session date, topic, emotion arc
├─ Summary snippet
├─ "View Data" modal (full details)
└─ "PDF" button → generates downloadable transcript via jsPDF

Technical Highlights

Agent Lifecycle Management

Dynamic Creation: Each session receives a unique, context-aware agent provisioned on demand
Automatic Cleanup: Agent + all tools deleted at session end to prevent resource leaks
Stateless Design: No agent persistence between sessions → horizontal scaling without state replication
Context Injection: Past session summaries baked into system prompt at creation time for continuity

Tool Orchestration

Webhook-Driven Execution: Tools call back to backend via secure HTTPS webhooks
Per-User Isolation: Tool webhooks include userId + HMAC secret for multi-tenancy
Transparent Hardware Triggering: Tools execute silently (no user-facing notifications)
Graceful Degradation: If hardware unreachable, conversation continues without interruption

Session Intelligence

Async Transcript Polling: CronWorker prevents race conditions between agent streams and DB writes
Structured Storage: SessionHistory + Transcript entities separate concerns (metadata vs. raw data)
Emotion Tracking: emotionStart/emotionEnd capture mood arc across session
Actionable Insights: Agents summarize concrete next steps for user follow-up

Knowledge Base Management

Dynamic Lifecycle: KBs created at app startup, deleted at shutdown
Classpath Resource Injection: Core persona + behavioral patterns loaded from properties files
Dual-KB Strategy:
- Core KB: Fixed identity rules (non-therapeutic, supportive stance)
- Behavioral KB: Grounding techniques, CBT templates, wellness frameworks
Cluster-Level Persistence: KBs stored on TRUGEN managed infrastructure, shared across agents

Hardware Communication

Serial Protocol: jSerialComm sends emotion names + control commands via COM port
Low-Latency Feedback: Arduino responds in <100ms to color/motor changes
State Management: Arduino tracks current emotion, breath phase, animation progress
OLED Rendering: Face expressions mapped to emotion state + real-time breath visualization

Authentication & Security

JWT-Based: Stateless token exchange via Bearer header
Spring Security Integration: Method-level authorization with @Secured annotations
CORS Configured: Frontend requests validated against allowed origins
Webhook Secret Validation: HMAC secrets included in tool URLs to prevent unauthorized webhook calls
Role-Based Access: Users vs. Admins with different endpoint permissions

Innovation & Differentiation

Why This Is More Than a Chatbot

Hardware-Software Codesign: Real-time bidirectional coupling between AI responses and physical environment
- Mood lights adjust during conversation without user awareness
- Breathing exercises triggered by AI perception of user emotion, not explicit user request
- This closes the gap between digital empathy and embodied wellness
Per-Session Agent Provisioning: Unlike static chatbots, MindMirror creates ephemeral, context-injected agents
- Each agent receives the user's past session context at creation time
- Eliminates cold-start problem and enables memory without persistent state
- Scales horizontally without database contention
Stateless Architecture for Emotional Continuity
- No agent persistence = no memory leaks or stale context
- Yet users feel remembered because past sessions are injected into prompt
- Achieves "memory at scale" without costly session replay
Tool Orchestration as Wellness Mechanism
- Tools aren't just for API calls; they're emotional interventions
- Breathing exercise tool auto-mutes agent during exercise (prevents instruction-following paralysis)
- Emotion lighting tool works silently (respects user's cognitive load)
Multi-Sensor Emotion Awareness
- Avatar detects emotion from user speech (STT confidence, tone, semantic content)
- Triggers environment change before user consciously recognizes their emotional state
- Creates preemptive wellness support

Real-World Impact

First Session: User feels noticed and understood (core philosophy)
Subsequent Sessions: Agent references past interactions, building sense of relationship
Hardware Feedback: Users report increased grounding during anxiety (breathing + lights)
Data Export: Transcript PDFs enable reflection and therapy integration
Scalability: Stateless design supports thousands of concurrent sessions on standard infrastructure

Technology Stack

Backend

Language: Java 21
Framework: Spring Boot 4.0.6
Authentication: JWT (JJWT 0.13.0) + Spring Security
ORM: Spring Data JPA + Hibernate
Database: PostgreSQL with Flyway migrations
HTTP Client: Spring RestClient
Hardware Communication: jSerialComm 2.11.4
Build: Maven
Logging: SLF4J + Lombok

Frontend

Language: TypeScript
Framework: React 18+ with Vite
Styling: Tailwind CSS
PDF Export: jsPDF
Icons: Lucide React
State Management: React Context API
Build Tool: Vite

AI & External Services

Agent Platform: TRUGEN API (v1)
LLM Provider: Google Gemini 3.1 Pro
STT Provider: Deepgram Flux (General EN)
TTS Provider: ElevenLabs Turbo v2.5
Avatar Asset ID: 665a1170 (TRUGEN gallery)

Hardware

Microcontroller: Arduino (compatible MCU)
Display: Adafruit SH1106 OLED (128×64)
LEDs: Adafruit NeoPixel Ring (12 addressable RGB)
Motors: Vibration motors (inhale + exhale pins)
Libraries: Adafruit GFX, Adafruit NeoPixel, Wire (I2C)

DevOps

Containerization: Docker + Docker Compose
Reverse Proxy: ngrok (for webhook callbacks from TRUGEN cluster)
Environment: Java 21, PostgreSQL 14+

Project Structure

MindMirror/
├── ai_mindmirror/ # Backend Spring Boot application
│ ├── src/main/java/com/thedebugnaths/ai_mindmirror/
│ │ ├── auth/ # JWT + Spring Security config
│ │ ├── controller/ # REST endpoints (Auth, Session, Webhook, Admin)
│ │ ├── dto/ # Data transfer objects
│ │ │ └── trugen/ # TRUGEN API request/response models
│ │ ├── entity/ # JPA entities (User, Session, Transcript, etc.)
│ │ ├── repository/ # Spring Data JPA repositories
│ │ ├── service/ # Business logic
│ │ │ ├── TrugenAgentService.java # Agent provisioning + KB management
│ │ │ ├── SessionService.java # Session orchestration
│ │ │ ├── HardwareIntegrationService.java # Serial communication
│ │ │ ├── TranscriptService.java # Transcript storage + retrieval
│ │ │ ├── TranscriptCronWorker.java # Async polling
│ │ │ ├── WebhookService.java # Tool callback routing
│ │ │ └── AuthService.java # User auth + JWT
│ │ └── exception/ # Custom exceptions + global handler
│ ├── src/main/resources/
│ │ ├── application.properties # Environment variables + config
│ │ ├── core-persona.txt # Core KB content (philosophy + rules)
│ │ ├── behavioral-patterns.txt # Behavioral KB (grounding, CBT)
│ │ └── db/migration/ # Flyway SQL migrations
│ ├── pom.xml # Maven dependencies
│ └── Dockerfile # Container image
│
├── mindmirror_frontend/ # React TypeScript frontend
│ ├── src/
│ │ ├── pages/ # Page components (Login, Register, Dashboard, SessionRoom)
│ │ ├── context/ # React Context (AuthContext)
│ │ ├── utils/ # API client + helpers
│ │ ├── components/ # Reusable UI components
│ │ ├── App.tsx # Router setup
│ │ └── main.tsx # Entry point
│ ├── package.json # Node.js dependencies
│ ├── tailwind.config.js # Tailwind CSS config
│ └── vite.config.ts # Vite build config
│
├── ArduinoScript.cpp # Firmware for microcontroller
│ ├── Setup # OLED + NeoPixel + pins initialization
│ ├── Loop # Main firmware loop
│ ├── Serial reading # Command parsing (emotion, breath, etc.)
│ ├── Breathing mechanics # Phase management (inhale/hold/exhale)
│ ├── OLED rendering # Face expressions
│ └── NeoPixel animation # Color transitions + breath visualization
│
├── docker-compose.yml # PostgreSQL + app orchestration
├── LICENSE # GPL 3.0
└── README.md # This file

Installation & Setup

Prerequisites

Java 21 (OpenJDK or Oracle JDK)
Node.js 18+ (for frontend)
Maven 3.8+ (for backend build)
Docker & Docker Compose (for PostgreSQL)
Arduino IDE (for firmware flashing)
ngrok (for webhook callbacks during development)

Backend Setup

Clone the repository:

git clone https://github.com/SleepyStack/MindMirror.git
cd MindMirror

Set up PostgreSQL (via Docker Compose):

cd ai_mindmirror
docker-compose up -d
# Runs PostgreSQL on localhost:5432

Configure environment variables in ai_mindmirror/src/main/resources/application.properties:

# TRUGEN APItrugen.api.key=YOUR_TRUGEN_API_KEY
app.ngrok.url=https://YOUR_NGROK_SUBDOMAIN.ngrok.io
webhook.secret.token=YOUR_WEBHOOK_SECRET
# Databasespring.datasource.url=jdbc:postgresql://localhost:5432/mindmirror
spring.datasource.username=postgres
spring.datasource.password=postgres
# JWTapp.jwt.secret=YOUR_JWT_SECRET_KEY

Build and run the backend:

cd ai_mindmirror
mvn clean package
java -jar target/ai_mindmirror-0.0.1-SNAPSHOT.jar

Backend runs on http://localhost:8080

Set up ngrok for webhook callbacks:

ngrok http 8080
# Copy the HTTPS URL and set app.ngrok.url in application.properties

Frontend Setup

Install dependencies:

cd mindmirror_frontend
npm install

Create .env file:

VITE_API_BASE_URL=http://localhost:8080/api

Run development server:

npm run dev
# Runs on http://localhost:5173

Build for production:

npm run build
# Output in dist/

Arduino Setup

Install Arduino IDE and required libraries:
- Adafruit GFX Library
- Adafruit SH110X Library
- Adafruit NeoPixel Library
- Wire (included)
Configure pins in ArduinoScript.cpp:
- OLED I2C address: 0x3C
- NeoPixel pin: 2 (WS2812B data)
- Inhale motor pin: 3 (PWM output)
- Exhale motor pin: 4 (PWM output)
Flash firmware:
- Open ArduinoScript.cpp in Arduino IDE
- Select board (e.g., Arduino Uno, Nano)
- Select COM port
- Click Upload
Test serial communication:

# From backend logs or direct serial monitor# Send commands like: "happy", "calm", "breath"

Running Locally (Full Stack)

Terminal 1: PostgreSQL

cd ai_mindmirror
docker-compose up

Terminal 2: Backend

cd ai_mindmirror
mvn spring-boot:run

Terminal 3: ngrok (webhook tunneling)

ngrok http 8080
# Update app.ngrok.url in application.properties

Terminal 4: Frontend

cd mindmirror_frontend
npm run dev

Terminal 5: Arduino Serial Monitor

Open Arduino IDE → Tools → Serial Monitor
Set baud rate to 115200
Watch for emotion commands and breathing sequence logs

Access the application

Dashboard: http://localhost:5173
API: http://localhost:8080/api
PostgreSQL: localhost:5432

API Overview

Authentication

Register User

POST /api/auth/registerContent-Type: application/json
{
"email": "user@mindmirror.com",
"password": "secure_password"
}

Login

POST /api/auth/loginContent-Type: application/json
{
"email": "user@mindmirror.com",
"password": "secure_password"
}
Response:
{
"token": "eyJhbGciOiJIUzI1NiIs...",
"user": { "id": 1, "email": "user@mindmirror.com", "role": "USER" }
}

Session Management

Start New Session

POST /api/session/startAuthorization: Bearer <JWT_TOKEN>Response:
{
"url": "https://api.trugen.ai/ext/session/AGENT_ID?embed=true"
}

Get Session History

GET /api/session/historyAuthorization: Bearer <JWT_TOKEN>Response:[
{
"id": 1,
"conversationId": "conv_123",
"mainTopic": "Anxiety Management",
"summaryText": "User discussed work stress...",
"emotionStart": "anxious",
"emotionEnd": "calm",
"actionStep": "Practice breathing daily",
"status": "COMPLETED",
"createdAt": "2026-06-10T18:30:00Z"
}
]

Transcript Management

Get Session Transcript

GET /api/transcript/:conversationIdAuthorization: Bearer <JWT_TOKEN>Response:
{
"conversationId": "conv_123",
"payload": [
{ "role": "user", "message": "I'm feeling anxious", "timestamp": "2026-06-10T18:30:00Z" },
{ "role": "assistant", "message": "I hear you. Let's talk about it.", "timestamp": "2026-06-10T18:30:05Z" }
]
}

Webhook Endpoints (TRUGEN Callbacks)

Tool Execution (Session Summary)

POST /api/webhook/trugen/tool?userId=1&secret=WEBHOOK_SECRETContent-Type: application/json
{
"toolId": "tool_123",
"toolName": "save_session_summary",
"arguments": {
"summaryText": "User focused on anxiety management",
"mainTopic": "Anxiety",
"emotionStart": "anxious",
"emotionEnd": "calm",
"actionStep": "Practice deep breathing daily"
}
}

Emotion Update (Lighting Control)

POST /api/webhook/trugen/emotion?userId=1&secret=WEBHOOK_SECRETContent-Type: application/json
{
"toolName": "update_ambient_lighting",
"arguments": { "emotion": "calm" }
}

Breathing Exercise

POST /api/webhook/trugen/breathe?userId=1&secret=WEBHOOK_SECRETContent-Type: application/json
{
"toolName": "start_breathing_exercise"
}

Hardware Integration Details

Emotion → Lighting Mapping

Emotion	RGB Color	Brightness
Happy	Gold (255, 180, 0)	100%
Calm	Blue (0, 100, 255)	80%
Sad	Deep Blue (0, 30, 255)	60%
Anxious	Orange (255, 80, 0)	90%
Depressed	Purple (80, 0, 120)	50%
Neutral	Gray (80, 80, 80)	40%

Breathing Exercise Sequence

Duration: ~57 seconds per cycle (3 cycles recommended)

Inhale Phase (4 seconds)
- Motor: Inhale motor vibrates with increasing pulse
- Lights: NeoPixel ring fills progressively
- OLED: Shows "INHALE"
Hold Phase (7 seconds)
- Motor: Both motors engaged (gentle sustained vibration)
- Lights: Full ring illuminated
- OLED: Shows "HOLD"
Exhale Phase (8 seconds)
- Motor: Exhale motor vibrates with decreasing pulse
- Lights: NeoPixel ring depletes progressively
- OLED: Shows "EXHALE"

After 3 cycles:

Motors turn off
Ring stays lit
OLED displays: "GOOD JOB!"
User can return to conversation

Serial Protocol

Commands sent from backend → Arduino (via jSerialComm):

emotion:<emotion_name> # e.g., "emotion:calm" → Arduino updates lighting
breath # Triggers breathing exercise sequence
reset # Resets to neutral state

Arduino → Backend (via serial logger):

[BREATH_IN_COMPLETE] Cycle 1/3
[BREATH_HOLD_COMPLETE] Cycle 1/3
[BREATH_OUT_COMPLETE] Cycle 1/3
[BREATHING_FINISHED] All cycles complete

Database Schema

Users Table

CREATETABLEusers (
id SERIALPRIMARY KEY,
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
role VARCHAR(50) DEFAULT 'USER',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

SessionHistory Table

CREATETABLEsession_history (
id SERIALPRIMARY KEY,
user_id BIGINTNOT NULLREFERENCES users(id),
trugen_agent_id VARCHAR(255),
conversation_id VARCHAR(255),
main_topic VARCHAR(255),
summary_text TEXT,
emotion_start VARCHAR(50),
emotion_end VARCHAR(50),
action_step TEXT,
status VARCHAR(50) DEFAULT 'PENDING',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
completed_at TIMESTAMP
);

Transcript Table

CREATETABLEtranscript (
id SERIALPRIMARY KEY,
conversation_id VARCHAR(255) NOT NULL,
user_id BIGINTNOT NULLREFERENCES users(id),
payload JSONB,
sync_status VARCHAR(50) DEFAULT 'PENDING',
last_synced_at TIMESTAMP,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Configuration & Environment Variables

Create ai_mindmirror/src/main/resources/application.properties:

# Applicationspring.application.name=ai_mindmirror
server.port=8080
server.servlet.context-path=/api
# Databasespring.datasource.url=jdbc:postgresql://localhost:5432/mindmirror
spring.datasource.username=postgres
spring.datasource.password=postgres
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.database-platform=org.hibernate.dialect.PostgreSQLDialect
# Flywayspring.flyway.enabled=true
spring.flyway.baselineOnMigrate=true
# JWTapp.jwt.secret=your_super_secret_jwt_key_here_at_least_32_chars
app.jwt.expiration=86400000
# CORScors.allowed-origins=http://localhost:5173,http://localhost:3000
# TRUGEN APItrugen.api.key=sk_test_YOUR_TRUGEN_API_KEY
app.ngrok.url=https://YOUR_NGROK_SUBDOMAIN.ngrok.io
webhook.secret.token=your_webhook_secret_key
# Logginglogging.level.root=INFO
logging.level.com.thedebugnaths.ai_mindmirror=DEBUG

Deployment

Docker Deployment (Production)

Build backend image:

cd ai_mindmirror
docker build -t mindmirror-backend:latest .

Build frontend image (requires multi-stage build):

cd mindmirror_frontend
docker build -t mindmirror-frontend:latest .

Deploy with Docker Compose:

version: '3.8'services:
postgres:
image: postgres:14-alpineenvironment:
POSTGRES_DB: mindmirrorPOSTGRES_PASSWORD: postgresvolumes:
- postgres_data:/var/lib/postgresql/databackend:
image: mindmirror-backend:latestports:
- "8080:8080"environment:
SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/mindmirrorTRUGEN_API_KEY: ${TRUGEN_API_KEY}APP_NGROK_URL: ${APP_NGROK_URL}depends_on:
- postgresfrontend:
image: mindmirror-frontend:latestports:
- "80:80"environment:
VITE_API_BASE_URL: https://your-domain.com/apivolumes:
postgres_data:

Deploy on Kubernetes (optional):

kubectl apply -f k8s/postgres-statefulset.yaml
kubectl apply -f k8s/backend-deployment.yaml
kubectl apply -f k8s/frontend-deployment.yaml
kubectl expose deployment mindmirror-backend --type=LoadBalancer

Future Roadmap

Phase 2: Enhanced Personalization

Multi-Modal Emotion Detection: Facial expression + voice tone + semantic analysis
Extended Session Context: Remember user preferences, triggers, coping strategies
Personalized Exercise Library: Yoga, meditation, grounding techniques based on user history

Phase 3: Community & Social

Peer Support Rooms: Guided group sessions with shared sessions & reflections
Therapist Integration: Optional integration with licensed therapists for escalation
Family Dashboard: Allow trusted contacts to view (with permission) session insights

Phase 4: Enterprise & Clinical

HL7/FHIR Compliance: Integration with EHR systems for clinical settings
Research APIs: Anonymized data export for wellness research
Behavioral Analytics: Dashboards for understanding population-level wellness trends
Multi-Language Support: Avatar conversations in 10+ languages

Phase 5: Advanced AI

Adaptive Persona: Conversation style evolves based on user response patterns
Predictive Interventions: Proactive check-ins before high-stress times
Real-Time Biometric Sync: Heart rate + skin conductance integration
Multi-Session Insights: Machine learning-driven mood prediction & early warning signals

Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository:

git clone https://github.com/YOUR_USERNAME/MindMirror.git
cd MindMirror
git checkout -b feature/your-feature-name

Make your changes:
- Backend: Follow Spring Boot conventions, add tests, update properties
- Frontend: Follow React/TypeScript best practices, test components
- Hardware: Update Arduino firmware with clear comments
Commit with clear messages:

git commit -m "feat: Add emotion detection via facial recognition"

Push and open a Pull Request:

git push origin feature/your-feature-name

Describe your changes in the PR with:
- What problem this solves
- How the solution works
- Testing performed
- Any breaking changes

License

MindMirror is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

What This Means

✅ You can use, modify, and distribute MindMirror
✅ Any derivative work must also be open-source under GPLv3
✅ You must provide source code to users of your modified version
✅ Include a copy of this license in any distribution

Authors & Contributors

Core Team:

**Chirag ** – Backend architecture, TRUGEN integration, agent orchestration
Rishi Kukreti – Arduino firmware, hardware integration, breathing mechanics
Mauli Kumari – Full-stack development, database design

Contributions from the open-source community are welcome!

Support & Community

Getting Help

Issues: Report bugs and feature requests on GitHub Issues
Discussions: Join conversations on GitHub Discussions
Documentation: Check docs/ for detailed guides

Code of Conduct

We're committed to providing a welcoming environment. Please see CODE_OF_CONDUCT.md.

Acknowledgments

MindMirror is built on the shoulders of giants:

TRUGEN for the powerful agent provisioning and avatar platform
Google Gemini 3.1 Pro for advanced LLM capabilities
Deepgram for real-time speech-to-text
ElevenLabs for natural voice synthesis
Spring Boot ecosystem for production-grade backend infrastructure
React community for the modern frontend foundation
Arduino community for open-source hardware

Special thanks to all contributors, testers, and the wellness community that inspired this project.

MindMirror: Notice. Reflect. Support. Act.

Built with ❤️ for emotional wellness and human-centered technology.

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
ai_mindmirror		ai_mindmirror
mindmirror_frontend		mindmirror_frontend
postman		postman
.gitignore		.gitignore
ArduinoScript.cpp		ArduinoScript.cpp
LICENSE		LICENSE
README.md		README.md
tatus		tatus

Folders and files

Latest commit

History

Repository files navigation