README.md

---
title: Chatty - Ethics Chat
emoji: 💬
colorFrom: yellow
colorTo: purple
sdk: gradio
sdk_version: 5.0.1
app_file: app.py
pinned: false
license: mit
---

A secure web-based chat interface with user authentication that connects to the [findEthics-Atlas](https://findEthics-Atlas.hf.space/chat) API for ethical discussions and guidance.

## Features

- **User Authentication**: Secure registration and login system
- **Personalized Chat History**: Each user's conversations are saved and restored
- **Minimal and clean UI**: Simple, responsive chat interface
- **Real-time chat**: Instant messaging with the ethics AI
- **Security Features**: CSRF protection, rate limiting, secure sessions
- **Error handling**: Robust error handling for API failures
- **Mobile-friendly**: Responsive design that works on all devices
- **Loading states**: Visual feedback during API calls

## Technology Stack

- **Backend**: Flask web framework with Flask-Login
- **Database**: MongoDB for user accounts and chat history
- **Authentication**: Secure password hashing with Werkzeug
- **Security**: CSRF protection, rate limiting, secure sessions
- **Frontend**: HTML, CSS, JavaScript (ES6)
- **API Integration**: HTTP requests to findEthics-Atlas endpoint
- **Deployment**: Hugging Face Spaces, Docker, or traditional servers

## Usage

### First Time Setup
1. **Open the application** in your web browser
2. **Register an account** with your email and password
3. **Log in** with your credentials

### Using the Chat
1. **Access the chat interface** (automatically redirected after login)
2. **Type your message** in the chat input field
3. **Press Enter** or click the Send button
4. **Wait for the response** from the ethics AI
5. **Continue the conversation** - your history is automatically saved

### Account Management
- **Logout**: Click the logout button to securely end your session
- **Session Management**: Sessions automatically expire after 24 hours for security
- **Chat History**: Your conversations are preserved across sessions

The application connects to the findEthics-Atlas API to provide ethical guidance and responses to your questions, while maintaining your personal conversation history.

## API Integration

This application uses the `https://findEthics-Atlas.hf.space/chat` API for generating responses.

### Request Format
```json
{
  "prompt": "Your question here",
  "history": []
}
```

### Response Format
```json
{
  "response": "AI response text",
  "search_results": []
}
```

## Setup and Installation

### Prerequisites
- Python 3.8 or higher
- MongoDB database (MongoDB Atlas recommended)
- Git

### Local Development Setup

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd chatty
   ```

2. **Create virtual environment**
   ```bash
   python -m venv atlas_env
   source atlas_env/bin/activate  # On Windows: atlas_env\Scripts\activate
   ```

3. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

4. **Set up environment configuration**
   ```bash
   python deploy.py setup-dev
   ```
   This creates a `.env` file from the template.

5. **Configure environment variables**
   Edit `.env` file and set:
   ```env
   SECRET_KEY=your-secret-key-here
   MONGODB_URL=mongodb+srv://username:password@cluster.mongodb.net/database
   MONGODB_DATABASE=Atlas
   ```

6. **Run the application**
   ```bash
   ./start.sh
   ```
   Or directly: `python app.py`

7. **Open in browser**
   Navigate to http://localhost:7860

### MongoDB Setup

#### Option 1: MongoDB Atlas (Recommended)
1. Create account at [MongoDB Atlas](https://www.mongodb.com/atlas)
2. Create a new cluster
3. Create database user with read/write permissions
4. Get connection string from Atlas dashboard
5. Add connection string to `.env` as `MONGODB_URL`

#### Option 2: Local MongoDB
1. Install MongoDB locally
2. Start MongoDB service
3. Set `MONGODB_URL=mongodb://localhost:27017/chatty` in `.env`

### Project Structure
```
Chatty/
├── app.py                 # Main Flask application
├── config.py              # Configuration management
├── auth.py                # Authentication utilities
├── models.py              # Database models (User, ChatSession)
├── database.py            # MongoDB connection utilities
├── deploy.py              # Deployment and configuration tools
├── requirements.txt       # Python dependencies
├── .env.example           # Environment variables template
├── start.sh               # Application startup script
├── templates/
│   ├── base.html         # Base template with navigation
│   ├── login.html        # Login form
│   ├── register.html     # Registration form
│   ├── index.html        # Chat interface
│   └── errors/           # Error page templates
├── static/
│   ├── css/
│   │   ├── style.css     # Main stylesheet
│   │   └── auth.css      # Authentication form styles
│   └── js/
│       └── chat.js       # Frontend JavaScript
├── Test/                  # Test suite
└── docs/
    └── PRODUCTION_DEPLOYMENT.md  # Production deployment guide
```

### Key Components

#### Backend Components
- **Flask Routes**: Authentication (`/login`, `/register`, `/logout`) and chat (`/`, `/chat`, `/api/chat`)
- **User Management**: Registration, login, session management
- **Database Models**: User accounts and chat session storage
- **Security**: CSRF protection, rate limiting, secure password hashing
- **Configuration**: Environment-based configuration management

#### Frontend Components
- **Authentication UI**: Login and registration forms
- **Chat Interface**: Real-time messaging with history
- **Responsive Design**: Mobile-first CSS architecture
- **Error Handling**: User-friendly error messages and validation

#### Security Features
- **Password Security**: Werkzeug password hashing (PBKDF2)
- **Session Management**: Flask-Login with secure cookies
- **CSRF Protection**: Form-based CSRF tokens
- **Rate Limiting**: Login attempt limiting
- **Input Validation**: Server and client-side validation

## Configuration

### Environment Variables

The application uses environment variables for configuration. Copy `.env.example` to `.env` and configure:

#### Required Variables
- `SECRET_KEY`: Flask secret key (generate with `python deploy.py gen-secret`)
- `MONGODB_URL`: MongoDB connection string
- `MONGODB_DATABASE`: Database name (default: Atlas)

#### Optional Variables
- `FLASK_ENV`: Environment mode (`development`, `production`, `testing`)
- `SESSION_LIFETIME_HOURS`: Session duration (default: 24)
- `MAX_LOGIN_ATTEMPTS`: Failed login limit (default: 5)
- `API_TIMEOUT`: External API timeout (default: 30)
- `LOG_LEVEL`: Logging level (default: INFO)

### Configuration Management

Use the deployment script for configuration tasks:

```bash
# Generate secure secret key
python deploy.py gen-secret

# Set up development environment
python deploy.py setup-dev

# Check production readiness
python deploy.py check-prod

# Generate production environment template
python deploy.py gen-prod-env
```

## Testing

### Running Tests

```bash
# Install test dependencies
pip install -r Test/test_requirements.txt

# Run all tests
python Test/run_tests.py

# Run specific test categories
python -m pytest Test/test_auth_unit.py      # Unit tests
python -m pytest Test/test_auth_integration.py  # Integration tests
```

### Test Categories
- **Unit Tests**: Individual component testing
- **Integration Tests**: Full authentication flow testing
- **API Tests**: External API integration testing

## Deployment

### Development Deployment
```bash
export FLASK_ENV=development
./start.sh
```

### Production Deployment

For production deployment, see [PRODUCTION_DEPLOYMENT.md](docs/PRODUCTION_DEPLOYMENT.md) for comprehensive instructions including:

- Security configuration
- Database setup
- HTTPS configuration
- Environment validation
- Monitoring and logging

#### Quick Production Setup
```bash
# Generate production configuration
python deploy.py gen-prod-env

# Edit .env.production with your values
# Then deploy:
export FLASK_ENV=production
./start.sh
```

#### Deployment Platforms
- **Hugging Face Spaces**: Direct deployment with environment variables
- **Docker**: Use provided Dockerfile
- **Traditional Servers**: systemd service configuration
- **Cloud Platforms**: AWS, GCP, Azure compatible

## Troubleshooting

### Common Issues

1. **Database Connection Errors**
   ```bash
   # Test database connection
   python -c "from database import test_connection; test_connection()"
   ```

2. **Configuration Issues**
   ```bash
   # Validate configuration
   python config.py
   ```

3. **Authentication Problems**
   - Check `SECRET_KEY` is set and secure
   - Verify MongoDB connection
   - Ensure HTTPS in production

4. **Session Issues**
   - Check cookie settings for your domain
   - Verify session configuration
   - Clear browser cookies

### Getting Help

- Check application logs for detailed error messages
- Review configuration with `python deploy.py check-prod`
- Test individual components with provided test scripts
- Consult [PRODUCTION_DEPLOYMENT.md](docs/PRODUCTION_DEPLOYMENT.md) for deployment issues

## Security

### Security Features
- **Password Hashing**: Secure PBKDF2 password storage
- **Session Security**: HTTPOnly, Secure, SameSite cookies
- **CSRF Protection**: Form-based CSRF tokens
- **Rate Limiting**: Brute force protection
- **Input Validation**: Server and client-side validation
- **SQL Injection Prevention**: MongoDB parameterized queries

### Security Best Practices
- Use HTTPS in production
- Set strong `SECRET_KEY`
- Configure MongoDB authentication
- Regular security updates
- Monitor authentication logs
- Implement proper firewall rules

## API Integration

This application integrates with the findEthics-Atlas API for AI responses.

### Request Format
```json
{
  "prompt": "Your question here",
  "history": [
    {"message": "Previous message", "response": "Previous response"}
  ]
}
```

### Response Format
```json
{
  "response": "AI response text",
  "search_results": []
}
```

### Authentication Integration
- User ID is tracked with each API request
- Chat history is maintained per user
- Session context is preserved across requests

## License

MIT License - see LICENSE file for details.