Reflectra

Intelligent Self-Reflection Through AI-Powered Conversation

Reflectra is an advanced self-reflection platform that combines dynamic personality modeling with AI-driven mirroring to help you understand yourself better. Through continuous conversation analysis, it learns your behavioral patterns, traits, and communication style—then reflects them back to you in meaningful, personalized interactions.

✨ Key Features

• Dynamic Persona System — Learns and adapts to your unique behavioral patterns with weighted confidence tracking
• AI Mirror Mode — Reflective responses that authentically mirror your communication style and personality traits
• Conversation Intelligence — Deep analysis of past conversations to extract behavioral insights and patterns
• Confidence-Based Learning — Continuously refines understanding through statistically-sound trait modeling
• Memory & Context — Maintains rich conversation history with contextual awareness for meaningful follow-ups
• User-Controlled Privacy — Full control over your data with granular settings and digital twin controls

🏗️ Architecture

Reflectra
├── Backend (FastAPI)
│   ├── Persona Engine      - Trait extraction, snapshots, mirroring
│   ├── Conversation Store  - Rich history with context preservation  
│   ├── Analytics Service   - Behavioral insights and pattern detection
│   └── Database (SQLAlchemy) - Persistent persona & conversation storage
│
├── Frontend (React + TypeScript)
│   ├── Chat Interface      - Intuitive conversation UI
│   ├── Analytics Dashboard - Visualization of behavioral insights
│   └── Settings Panel      - Control over persona learning & privacy
│
└── AI Integration
    └── Mistral AI API      - Advanced language understanding & generation

🚀 Getting Started

Prerequisites

• Python 3.12 or higher
• Node.js 18 or higher
• Git for version control

Installation

1. Clone the repository

git clone https://github.com/vaishnav1906/reflectra.git
cd reflectra

2. Set up Python environment

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r backend/requirements.txt

3. Install frontend dependencies

cd frontend
npm install
cd ..

4. Configure environment variables

Create backend/.env with your configuration:

# AI Provider
MISTRAL_API_KEY=your_mistral_api_key_here

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/reflectra

# (Optional) Other configurations
DEBUG=false

Running the Application

Quick Start (All-in-one)

./scripts/restart-all.sh
./scripts/check-status.sh

Manual Start

# Terminal 1: Backend
source .venv/bin/activate
cd backend
python -m uvicorn app.main:app --reload --port 8000

# Terminal 2: Frontend
cd frontend
npm run dev

Visit http://localhost:5173 to access the application.

📚 Documentation

Comprehensive documentation is available in the /docs directory:

• Persona System — Deep dive into dynamic personality modeling
• Mirror Mode — How the AI learns and reflects your style
• Architecture — System design and component interactions
• API Reference — Complete API documentation

🧪 Testing

Run the test suite to ensure everything is working correctly:

# Backend tests
pytest tests/backend/

# Frontend tests
cd frontend && npm run test

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

💬 Questions & Support

Have questions or need help? Feel free to:

• Open an issue
• Check existing documentation
• Review past discussions

---

Built with ❤️ for better self-understanding through AI cd backend alembic upgrade head uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

In another terminal:

```bash
cd frontend
npm run dev

Repository Layout

.
├── backend/
├── frontend/
├── scripts/
├── tests/
├── docs/
├── data/
├── README.md
└── .gitignore

Key Scripts

• scripts/restart-all.sh - restart backend and frontend
• scripts/restart-backend-with-conversations.sh - restart backend only
• scripts/check-status.sh - health and dependency checks
• scripts/test-conversations.sh - conversation endpoint checks

Tests

Backend and integration-style tests are centralized under tests/backend.

Examples:

python tests/backend/test_conversations.py
python tests/backend/test_past_conversations.py
python tests/backend/test_mirror_confidence_updates.py

Documentation

Canonical docs are in docs/.

• architecture-fix.md
• conversation-history.md
• past-conversations.md
• persona-quickstart.md
• persona-system.md
• error-handling-improvements.md
• backend-cors-fix.md

License

MIT