moto-adv-website/README.md

# Motorcycle Adventure Community 🏍️

A modern Flask-based web application for motorcycle enthusiasts featuring adventure stories, interactive GPS route sharing, and community engagement.

## ✨ Features

### 🎨 Modern UI/UX Design
- **Tailwind CSS Integration**: Complete redesign with modern gradient backgrounds and glass morphism effects
- **Responsive Design**: Mobile-first approach with optimized layouts for all screen sizes
- **Interactive Components**: Smooth animations, hover effects, and modern card-based layouts
- **Consistent Design Language**: Unified color scheme and component patterns throughout the app

### 🗺️ Advanced GPS & Route Features
- **Interactive Maps**: Leaflet.js integration with OpenStreetMap tiles
- **GPX File Support**: Upload, download, and visualize GPS tracks
- **Route Statistics**: Distance, elevation gain, max elevation, and track points
- **Start/End Markers**: Visual indicators with custom icons for route endpoints
- **Map Fitting**: Automatic zoom and centering to display complete routes

### 📸 Enhanced Media Management
- **Photo Gallery**: Grid-based layout with modal view and zoom functionality
- **Image Thumbnails**: Automatic thumbnail generation for optimized loading
- **Cover Image System**: Designated cover photos for adventure posts
- **Image Descriptions**: Support for photo captions and descriptions
- **Hover Effects**: Interactive image previews with smooth transitions

### 👥 Community & Social Features
- **Adventure Posts**: Rich content creation with titles, subtitles, and detailed stories
- **Comment System**: Community discussions on adventure posts
- **Like System**: Engagement tracking with real-time updates
- **Real-time Chat System**: Modern chat interface with room management
- **Post-linked Discussions**: Chat rooms connected to specific adventure posts
- **Chat Categories**: Organized rooms for different topics (general, technical, routes, etc.)
- **Mobile API Integration**: RESTful API for mobile app connectivity
- **User Profiles**: Personal dashboards with adventure statistics
- **Difficulty Ratings**: 5-star system for adventure difficulty assessment
- **Publication Workflow**: Admin approval system for content moderation

### 🔐 User Management & Authentication
- **Secure Authentication**: Flask-Login with session management
- **User Profiles**: Personal information and adventure history
- **Role-Based Access**: User and admin permissions
- **Adventure Statistics**: Published vs pending post counts
- **Registration System**: Email-based user registration

### 🛠️ Admin Panel & Analytics
- **Comprehensive Dashboard**: User and post management interface with statistics
- **Content Moderation**: Review and approve community posts
- **User Analytics**: User engagement and activity metrics with page view tracking
- **Post Management**: Bulk operations and detailed post information
- **Chat Management**: Full chat room administration with merge capabilities
- **Password Reset System**: Admin-controlled password reset with secure tokens
- **Mail System Configuration**: SMTP settings and email template management
- **System Configuration**: Admin-only settings and controls

### <20> Real-time Chat System
- **Modern Chat Interface**: App-style design with gradient backgrounds and card layouts
- **Room Management**: Create, join, and manage chat rooms with categories
- **Post Integration**: Link chat rooms to specific adventure posts for focused discussions
- **Admin Controls**: Comprehensive chat administration with room merging and moderation
- **Mobile API**: RESTful API endpoints for mobile app integration
- **Real-time Updates**: JavaScript polling for live message updates
- **Message Features**: Text messages with editing, deletion, and system notifications

### <20>📱 Mobile-Optimized Experience
- **Touch-Friendly Interface**: Optimized buttons and interactions for mobile devices
- **Responsive Grids**: Adaptive layouts that work perfectly on phones and tablets
- **Progressive Enhancement**: Graceful degradation for older browsers
- **Fast Loading**: Optimized images and efficient CSS delivery

## 🚀 Technology Stack

- **Backend**: Python Flask 3.0.0 with Blueprint architecture
- **Database**: SQLAlchemy with PostgreSQL/SQLite support
- **Authentication**: Flask-Login with secure session management
- **Email**: Flask-Mail for notifications and verification
- **Forms**: WTForms with comprehensive validation
- **Frontend**: Tailwind CSS 3.x with custom components
- **Maps**: Leaflet.js with OpenStreetMap integration
- **File Handling**: Secure media uploads with thumbnail generation
- **Chat System**: Real-time messaging with WebSocket-ready architecture
- **API**: RESTful endpoints for mobile app integration
- **Deployment**: Docker with Gunicorn WSGI server

## 📁 Project Structure

```
/
├── app/
│   ├── __init__.py              # Flask app factory with extensions
│   ├── models.py                # Database models (User, Post, Image, GPX, Comment, Like)
│   ├── forms.py                 # WTForm definitions for all features
│   ├── extensions.py            # Flask extensions configuration
│   ├── media_config.py          # Media handling and upload configuration
│   ├── routes/                  # Route blueprints
│   │   ├── main.py              # Landing page and general routes
│   │   ├── auth.py              # Authentication and user management
│   │   ├── community.py         # Community features and post management
│   │   └── admin.py             # Admin panel and analytics
│   ├── templates/               # Jinja2 templates
│   │   ├── base.html            # Base template with navigation
│   │   ├── index.html           # Landing page with hero section
│   │   ├── auth/                # Authentication templates
│   │   ├── community/           # Community feature templates
│   │   │   ├── index.html       # Community homepage
│   │   │   ├── new_post.html    # Adventure creation form
│   │   │   ├── edit_post.html   # Adventure editing interface
│   │   │   ├── post_detail.html # Detailed adventure view with maps
│   │   │   └── profile.html     # User profile dashboard
│   │   ├── admin/               # Admin panel templates
│   │   │   ├── dashboard.html   # Analytics dashboard
│   │   │   ├── posts.html       # Post management
│   │   │   └── users.html       # User management
│   │   └── errors/              # Error pages (404, 500)
│   └── static/                  # Static assets and media
│       ├── favicon.ico
│       ├── images/              # App images and logos
│       └── media/               # User-uploaded content
│           └── posts/           # Post media organized by ID
├── instance/                    # Instance-specific files
│   ├── uploads/                 # Legacy upload directory
│   └── *.db                     # SQLite database files
├── migrations/                  # Database migration scripts
├── config.py                    # Multi-environment configuration
├── requirements.txt             # Python dependencies
├── run.py                       # Application entry point
├── manage_media.py              # Media management utilities
├── test_media.py                # Media system tests
├── Dockerfile                   # Docker configuration
└── docker-compose.yml          # Docker Compose setup
```

## <20> API Documentation

The platform provides a comprehensive RESTful API for mobile app integration and third-party services.

### Base URL
```
https://your-domain.com/api/v1
```

### Authentication
All API endpoints use session-based authentication. Mobile apps can authenticate using:

```http
POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password"
}
```

### Chat API Endpoints

#### Get Chat Rooms
```http
GET /api/v1/chat/rooms
```
Response:
```json
{
  "rooms": [
    {
      "id": 1,
      "name": "General Discussion",
      "category": "general",
      "post_id": null,
      "created_at": "2024-01-01T10:00:00Z"
    }
  ]
}
```

#### Join Chat Room
```http
POST /api/v1/chat/rooms/{room_id}/join
```

#### Send Message
```http
POST /api/v1/chat/rooms/{room_id}/messages
Content-Type: application/json

{
  "content": "Hello, world!"
}
```

#### Get Messages
```http
GET /api/v1/chat/rooms/{room_id}/messages?page=1&per_page=50
```

### Posts API Endpoints

#### Get Posts
```http
GET /api/v1/posts?page=1&per_page=20
```

#### Create Post
```http
POST /api/v1/posts
Content-Type: multipart/form-data

title: "Adventure Title"
content: "Post content"
images: [file uploads]
gpx_file: [GPX file upload]
```

### User API Endpoints

#### Get User Profile
```http
GET /api/v1/users/{user_id}
```

#### Update Profile
```http
PUT /api/v1/users/profile
Content-Type: application/json

{
  "bio": "Updated bio",
  "location": "New location"
}
```

## <20>🚀 Quick Start

### Local Development

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd motorcycle-adventure-community
   ```

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

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

4. **Set environment variables**
   ```bash
   export FLASK_APP=run.py
   export FLASK_ENV=development
   export SECRET_KEY="your-secret-key-here"
   export DATABASE_URL="sqlite:///instance/moto_adventure_dev.db"
   ```

5. **Initialize database**
   ```bash
   flask db init
   flask db migrate -m "Initial migration"
   flask db upgrade
   ```

6. **Create media directories**
   ```bash
   mkdir -p app/static/media/posts
   mkdir -p instance/uploads
   ```

7. **Run the application**
   ```bash
   python run.py
   ```

8. **Access the application**
   - Open http://localhost:5000 in your browser
   - Register a new account to start sharing adventures
   - Upload GPX files and photos to test the full functionality

### 🐳 Docker Deployment

1. **Build and run with Docker Compose**
   ```bash
   docker-compose up --build
   ```

2. **Access the application**
   - Web application: http://localhost:8100
   - PostgreSQL database: localhost:5432
   - API endpoints: http://localhost:8100/api/v1

3. **Production deployment**
   ```bash
   # Set production environment variables
   export FLASK_ENV=production
   export SECRET_KEY="your-secure-production-key"
   export DATABASE_URL="postgresql://user:password@localhost:5432/moto_adventure"
   export MAIL_SERVER="your-smtp-server.com"
   export MAIL_USERNAME="your-email@domain.com"
   export MAIL_PASSWORD="your-email-password"
   
   # Run in production mode
   docker-compose -f docker-compose.prod.yml up -d
   ```

### 🔧 Configuration

#### Environment Variables
- `SECRET_KEY`: Flask secret key for session management
- `DATABASE_URL`: Database connection string
- `MAIL_SERVER`: SMTP server for email notifications
- `MAIL_PORT`: SMTP port (default: 587)
- `MAIL_USE_TLS`: Enable TLS for email (default: True)
- `MAIL_USERNAME`: Email account username
- `MAIL_PASSWORD`: Email account password
- `UPLOAD_PATH`: Custom upload directory path
- `MAX_CONTENT_LENGTH`: Maximum file upload size

#### Admin Configuration
To create an admin user:
```bash
# Access the container
docker exec -it moto-adventure-app bash

# Run Python shell
python
>>> from app import create_app, db
>>> from app.models import User
>>> app = create_app()
>>> with app.app_context():
...     admin = User(email='admin@example.com', is_admin=True)
...     admin.set_password('secure_password')
...     db.session.add(admin)
...     db.session.commit()
```

### 📱 Testing Features

1. **Create an Adventure Post**
   - Register and login to your account
   - Click "Share New Adventure" 
   - Upload photos and GPX files
   - Add title, subtitle, and adventure story

2. **Explore Interactive Maps**
   - View adventure posts with GPS tracks
   - See route statistics and elevation data
   - Download GPX files for your own use

3. **Admin Panel Access**
   - Create admin user in database
   - Access /admin for content management
   - Review and approve community posts
   - PostgreSQL database: localhost:5432

## ⚙️ Configuration

The application supports multiple environments through environment variables:

### Core Settings
- `FLASK_ENV`: development, testing, production
- `SECRET_KEY`: Flask secret key for sessions and CSRF protection
- `DATABASE_URL`: Database connection string (SQLite/PostgreSQL)

### Media & Upload Settings
- `UPLOAD_FOLDER`: Directory for user uploads (default: instance/uploads)
- `MEDIA_FOLDER`: Directory for processed media (default: app/static/media)
- `MAX_CONTENT_LENGTH`: Maximum file upload size (default: 16MB)

### Email Configuration
- `MAIL_SERVER`: SMTP server for email notifications
- `MAIL_USERNAME`: Email username for authentication
- `MAIL_PASSWORD`: Email password or app-specific password
- `MAIL_USE_TLS`: Enable TLS encryption (default: True)

### Development Settings
- `FLASK_DEBUG`: Enable debug mode (development only)
- `WTF_CSRF_ENABLED`: Enable CSRF protection (default: True)

## 🌟 Features Overview

### 🏠 Enhanced Landing Page
- **Hero Section**: Stunning Transalpina panorama background with glass morphism overlay
- **Featured Adventures**: Carousel showcasing community highlights
- **Statistics Dashboard**: Live counters for users, adventures, and community engagement
- **Call-to-Action**: Prominent registration and exploration prompts
- **Pensiune BuonGusto**: Integrated accommodation promotion

### 🔐 Advanced Authentication System
- **Secure Registration**: Email validation with password strength requirements
- **Session Management**: Persistent login with "Remember Me" functionality
- **Password Security**: Bcrypt hashing with salt for maximum security
- **User Profiles**: Comprehensive profile management with statistics
- **Role-Based Access**: Granular permissions for users and administrators

### 🗺️ Interactive Community Features
- **Rich Post Creation**: Multi-step form with media upload and GPS integration
- **Adventure Gallery**: Beautiful grid layout with filtering and search
- **Real-time Engagement**: Like system with instant feedback
- **Threaded Comments**: Nested discussion system for each adventure
- **Social Sharing**: Easy sharing of favorite adventures
- **Content Moderation**: Admin approval workflow for quality control

### 📊 Comprehensive Admin Panel
- **Analytics Dashboard**: User growth, post statistics, and engagement metrics
- **User Management**: Detailed user profiles with activity tracking
- **Content Review**: Streamlined post approval and moderation tools
- **System Health**: Monitoring and configuration management
- **Bulk Operations**: Efficient management of multiple users or posts

### 🎨 Modern Design System
- **Tailwind CSS**: Utility-first CSS framework with custom components
- **Glass Morphism**: Modern translucent effects and backdrop blur
- **Gradient Backgrounds**: Beautiful color transitions throughout the app
- **Micro-interactions**: Smooth animations and hover effects
- **Accessibility**: WCAG compliant design with keyboard navigation support

## 🤝 Contributing

We welcome contributions from the motorcycle community! Here's how you can help:

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

### Development Guidelines
- Follow PEP 8 style guidelines for Python code
- Use semantic commit messages
- Add tests for new features
- Update documentation for any changes
- Ensure mobile responsiveness for UI changes

### Reporting Issues
- Use the GitHub issue tracker
- Include steps to reproduce the problem
- Provide browser and device information
- Include screenshots for UI issues

## 📄 License

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

## 🙏 Acknowledgments

- **Beautiful Transalpina Panorama**: Stunning background image showcasing Romania's scenic highway
- **Tailwind CSS**: For providing an excellent utility-first CSS framework
- **Leaflet.js**: For powerful and flexible mapping capabilities
- **Flask Community**: For comprehensive documentation and support
- **OpenStreetMap**: For providing free and open map data
- **Font Awesome**: For beautiful and consistent iconography
- **Motorcycle Community**: For inspiration and feedback during development

## 🚧 Roadmap

### Upcoming Features
- [ ] **Real-time Chat**: Live messaging between community members
- [ ] **Event System**: Motorcycle meetups and group ride organization
- [ ] **Weather Integration**: Route weather conditions and forecasts
- [ ] **Mobile App**: Native iOS and Android applications
- [ ] **Advanced Search**: Filter adventures by location, difficulty, and tags
- [ ] **Social Features**: Follow users and curated adventure feeds
- [ ] **Offline Support**: PWA capabilities for offline map viewing

### Performance Improvements
- [ ] **Image Optimization**: WebP conversion and lazy loading
- [ ] **Caching**: Redis integration for improved performance
- [ ] **CDN Integration**: Asset delivery optimization
- [ ] **Database Optimization**: Query optimization and indexing

---

**Built with ❤️ for the motorcycle adventure community**

For support or questions, please open an issue or contact the development team.