Kobelly/README.md

# Kobelly Web Solutions

A professional Flask-based website for promoting small business web development services. Features multilanguage support (English, Dutch, French, German) with a simple JSON-based translation system and is fully dockerized for easy deployment.

## Features

- 🌐 **Multilanguage Support**: English (EN), Dutch (NL), French (FR), German (DE) with JSON-based translations
- 📱 **Responsive Design**: Modern, mobile-friendly interface
- 🎨 **Professional UI**: Clean, modern design with Bootstrap 5
- 🐳 **Docker Support**: Easy containerization and deployment
- ⚡ **Fast Performance**: Optimized for speed and performance with minified assets
- 🔧 **No Database Required**: Simple, lightweight setup
- 🚀 **Asset Optimization**: CSS/JS minification with cache busting
- 📧 **Contact Form**: Fully functional email contact form
- 🗺️ **SEO Optimized**: Sitemap generation and robots.txt

## Pages

- **Home**: Hero section, features, and service overview
- **Services**: Detailed service offerings with pricing information
- **About**: Company story, team, and values
- **Contact**: Contact form and business information
- **Portfolio**: Showcase of completed projects

## Quick Start

### Local Development (Recommended)

1. **Install Python dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

2. **Build assets (optional, for production-like experience):**
   ```bash
   make build
   ```

3. **Run the application:**
   ```bash
   python app.py
   ```

4. **Access the website:**
   Open your browser and go to `http://localhost:5000`

### Using Make Commands

The project includes a Makefile for common tasks:

```bash
make help          # Show all available commands
make install       # Install dependencies
make build         # Build minified assets
make clean         # Clean old assets
make run           # Run development server
make run-prod      # Run production server
make deploy        # Clean and build assets
make dev-setup     # Setup development environment

# Docker commands
make docker-run    # Run production Docker container
make docker-run-dev # Run development Docker container
make docker-stop   # Stop production container
make docker-stop-dev # Stop development container
make docker-logs   # View production logs
make docker-logs-dev # View development logs
```

### Docker Deployment

#### Production Mode (Default)
1. **Build and run with Docker Compose:**
   ```bash
   docker-compose up --build
   ```

2. **Or build and run manually:**
   ```bash
   docker build -t kobelly-website .
   docker run -p 5000:5000 kobelly-website
   ```

#### Development Mode
For local development with Docker (with live reload and debug mode):

1. **Build and run development container:**
   ```bash
   docker-compose -f docker-compose.dev.yml up --build
   ```

2. **Or use Make commands:**
   ```bash
   make docker-run-dev    # Start development container
   make docker-logs-dev   # View development logs
   make docker-stop-dev   # Stop development container
   ```

**Development vs Production:**
- **Development**: Debug mode enabled, live code reloading, unminified assets
- **Production**: Debug disabled, minified assets, optimized performance

## Project Structure

```
Kobelly/
├── app.py                 # Main Flask application
├── requirements.txt       # Python dependencies
├── Dockerfile            # Docker configuration
├── docker-compose.yml    # Docker Compose configuration
├── docker-compose.dev.yml # Development Docker Compose
├── Makefile              # Build and deployment commands
├── build_assets.py       # Asset minification script
├── translation_manager.py # JSON-based translation system
├── test_translations.py  # Translation testing script
├── robots.txt            # Search engine configuration
├── static/               # Static assets
│   ├── css/              # CSS files
│   │   ├── main.css      # Main stylesheet
│   │   └── main.min.css  # Minified CSS (generated)
│   ├── js/               # JavaScript files
│   │   ├── main.js       # Main script
│   │   └── main.min.js   # Minified JS (generated)
│   └── images/           # Images and icons
├── templates/            # HTML templates
│   ├── base.html         # Base template with navigation
│   ├── index.html        # Homepage
│   ├── services.html     # Services page
│   ├── about.html        # About page
│   ├── contact.html      # Contact page
│   ├── portfolio.html    # Portfolio page
│   └── components/       # Reusable template components
│       ├── hero_section.html
│       ├── cta_section.html
│       ├── stats_section.html
│       └── testimonials_section.html
└── translations/         # JSON translation files
    ├── en.json           # English translations
    ├── nl.json           # Dutch translations
    ├── fr.json           # French translations
    └── de.json           # German translations
```

## Multilanguage Support

The website supports four languages using a simple JSON-based translation system:
- 🇺🇸 **English** (EN) - Default
- 🇳🇱 **Dutch** (NL)
- 🇫🇷 **French** (FR)
- 🇩🇪 **German** (DE)

Users can switch languages using the language selector in the navigation bar or URL parameters (`?lang=de`). The language preference is stored in the session.

### Translation System

The project uses a custom JSON-based translation system that:
- **No compilation needed** - Just edit JSON files directly
- **Real-time updates** - Changes appear immediately after restart
- **Simple maintenance** - Clear JSON structure
- **Independent languages** - Edit English without breaking translations

### Adding New Translations

1. **Add the string to your template:**
   ```html
   <h2>{{ t('New Section Title') }}</h2>
   ```

2. **Add it to the translation files:**
   ```json
   // translations/en.json
   {
     "New Section Title": "New Section Title"
   }
   
   // translations/de.json  
   {
     "New Section Title": "Neuer Abschnittstitel"
   }
   ```

3. **Restart your Flask app** - Changes appear immediately!

## Customization

### Content Updates

1. **Text Content**: Edit the HTML templates in the `templates/` directory
2. **Translations**: Update the `.json` files in the `translations/` directory
3. **Styling**: Modify the CSS in `static/css/main.css`

### Adding New Pages

1. Add a new route in `app.py`
2. Create a new template file in `templates/`
3. Add navigation link in `templates/base.html`

### Updating Translations

The JSON-based system makes translation updates simple:

1. **Edit translation files directly:**
   ```bash
   # Open and edit the JSON files
   nano translations/en.json
   nano translations/de.json
   # etc.
   ```

2. **Restart the application:**
   ```bash
   python app.py
   ```

3. **Test translations:**
   ```bash
   python test_translations.py
   ```

## Asset Optimization

The project includes automatic CSS and JavaScript minification with cache busting for optimal performance.

### Asset Building

**Development Mode:**
- Uses unminified assets for easier debugging
- Assets are served directly from source files

**Production Mode:**
- Automatically serves minified assets
- Cache busting prevents browser caching issues
- Assets are optimized for faster loading

### Building Assets

```bash
# Build minified assets
make build

# Clean old cache-busted assets
make clean

# Full deployment (clean + build)
make deploy
```

### Asset Files

- **CSS**: `static/css/main.css` → `static/css/main.min.css`
- **JavaScript**: `static/js/main.js` → `static/js/main.min.js`

The build process creates cache-busted versions with MD5 hashes in the filename to ensure browsers always load the latest version.

## Contact Form Setup

The website includes a fully functional contact form that sends email notifications. To set up email functionality:

### 1. Email Configuration

The application uses environment variables for email configuration. You can set these in your environment or create a `.env` file:

```bash
# For Gmail (recommended)
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_USE_TLS=True
MAIL_USERNAME=contact@kobelly.be
MAIL_PASSWORD=your-app-password-here
MAIL_DEFAULT_SENDER=contact@kobelly.be
```

### 2. For Gmail users:
- Enable 2-factor authentication on your Google account
- Generate an "App Password" in Google Account settings
- Use the app password as `MAIL_PASSWORD`

### 3. Alternative Email Providers

**For other SMTP providers, update the settings accordingly:**
```bash
# Example for Outlook/Hotmail
MAIL_SERVER=smtp-mail.outlook.com
MAIL_PORT=587
MAIL_USE_TLS=True

# Example for custom SMTP server
MAIL_SERVER=your-smtp-server.com
MAIL_PORT=587
MAIL_USE_TLS=True
```

### 4. Testing the Contact Form

1. Start the application
2. Navigate to the Contact page
3. Fill out and submit the form
4. Check your email for the notification

The form includes:
- **Form validation** (required fields, email format, phone format)
- **Loading states** (button shows spinner during submission)
- **Success/error notifications** (toast notifications)
- **Email notifications** (HTML and plain text formats)

## Configuration

### Environment Variables

- `SECRET_KEY`: Secret key for Flask sessions (default: 'your-secret-key-change-in-production')
- `FLASK_ENV`: Flask environment (development/production)
- `FLASK_DEBUG`: Debug mode (0=disabled, 1=enabled, defaults to 1 in development)
- `MAIL_SERVER`: SMTP server for email (default: smtp.gmail.com)
- `MAIL_PORT`: SMTP port (default: 587)
- `MAIL_USE_TLS`: Use TLS encryption (default: True)
- `MAIL_USERNAME`: Email username
- `MAIL_PASSWORD`: Email password
- `MAIL_DEFAULT_SENDER`: Default sender email

**Environment Modes:**

**Development (Local):**
```bash
FLASK_ENV=development
FLASK_DEBUG=1
```

**Production (Docker):**
```bash
FLASK_ENV=production
FLASK_DEBUG=0
```

### Production Deployment

For production deployment:

1. Set a strong `SECRET_KEY`
2. Disable debug mode
3. Use a production WSGI server (e.g., Gunicorn)
4. Set up proper SSL/TLS certificates
5. Configure a reverse proxy (e.g., Nginx)

## Technologies Used

- **Backend**: Flask 2.3.3
- **Frontend**: Bootstrap 5, Font Awesome
- **Translation**: Custom JSON-based system
- **Containerization**: Docker, Docker Compose
- **Styling**: Custom CSS with CSS variables
- **Asset Management**: Custom build script with CSS/JS minification
- **Email**: Flask-Mail

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- Mobile browsers (iOS Safari, Chrome Mobile)

## License

This project is created for demonstration purposes. Feel free to use and modify for your own business needs.

## Support

For questions or support, please contact:
- Email: contact@kobelly.be
- Phone: +32 486 21 07 07
- Address: Blijkheerstraat 92, 1755 Pajottegem, Belgium

---

**Kobelly Web Solutions** - Professional web development for small businesses and entrepreneurs.