🐢 Turtle Photo Gallery

A full-stack web application for storing and displaying turtle photos, built with Next.js frontend, Flask API backend, and PostgreSQL database.

Features

• Photo Upload: Upload turtle photos with titles and descriptions
• Photo Gallery: View all uploaded photos in a responsive grid layout
• Photo Management: Delete photos with confirmation
• Image Processing: Automatic image resizing and optimization
• Responsive Design: Works on desktop and mobile devices
• File Validation: Supports JPEG, PNG, and GIF files up to 16MB
• Type Safety: Flask backend uses type hints, frontend uses JavaScript

Technology Stack

Backend

• Flask - Python web framework
• PostgreSQL - Database
• SQLAlchemy - ORM
• Pillow - Image processing
• pytest - Testing framework

Frontend

• Next.js - React framework
• React - UI library
• Jest - Testing framework
• React Testing Library - Component testing

Infrastructure

• Docker & Docker Compose - Containerization
• CORS - Cross-origin resource sharing

Project Structure

turtle-app/
├── backend/                 # Flask API
│   ├── app.py              # Main Flask application
│   ├── requirements.txt    # Python dependencies
│   ├── conftest.py        # Test configuration
│   ├── test_app.py        # API tests
│   ├── uploads/           # Uploaded photos storage
│   ├── .env.example       # Environment variables template
│   └── Dockerfile         # Backend container config
├── frontend/               # Next.js application
│   ├── pages/             # Next.js pages
│   ├── components/        # React components
│   ├── utils/             # Utility functions
│   ├── __tests__/         # Test files
│   ├── styles/            # CSS styles
│   ├── package.json       # Node.js dependencies
│   └── Dockerfile         # Frontend container config
└── docker-compose.yml     # Multi-container orchestration

Development Setup

Prerequisites

• Python 3.11+
• Node.js 18+
• PostgreSQL 15+
• Docker & Docker Compose (optional)

Option 1: Docker Development (Recommended)

1. Clone and navigate to the project:

   cd turtle-app

2. Start all services with Docker Compose:

   docker-compose up --build

3. Access the application:

   • Frontend: http://localhost:8089
   • Backend API: http://localhost:8090
   • Database: localhost:5432

Option 2: Local Development

Backend Setup

1. Navigate to backend directory:

   cd turtle-app/backend

2. Create and activate virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\\Scripts\\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Set up environment variables:

   cp .env.example .env
   # Edit .env with your database configuration

5. Set up PostgreSQL database:

   # Create database
   createdb turtle_db

6. Run the Flask application:

   python app.py

Frontend Setup

1. Navigate to frontend directory:

   cd turtle-app/frontend

2. Install dependencies:

   npm install

3. Start the development server:

   npm run dev

Testing

Backend Tests

cd backend
python -m pytest

Frontend Tests

cd frontend
npm test

API Endpoints

Photos

• GET /api/photos - Get all photos
• GET /api/photos/{id} - Get specific photo details
• POST /api/photos - Upload new photo
• DELETE /api/photos/{id} - Delete photo
• GET /api/photos/{id}/file - Get photo file

Health Check

• GET /api/health - API health status

Environment Variables

Backend (.env)

DATABASE_URL=postgresql://postgres:password@localhost:5432/turtle_db
FLASK_ENV=development
UPLOAD_FOLDER=uploads

Production Deployment

Environment Setup

1. Update DATABASE_URL with production database credentials
2. Set FLASK_ENV=production
3. Configure proper CORS origins
4. Set up file storage (AWS S3, etc.)
5. Update frontend API base URL

Docker Production

docker-compose -f docker-compose.prod.yml up --build

File Upload Specifications

• Supported formats: JPEG, PNG, GIF
• Maximum file size: 16MB
• Image processing: Automatic resize to 800x600 max dimensions
• Storage: Local filesystem (uploads directory)

Database Schema

turtle_photos table

• id (INTEGER, PRIMARY KEY)
• filename (VARCHAR(255)) - Generated unique filename
• original_filename (VARCHAR(255)) - Original uploaded filename
• title (VARCHAR(255)) - Photo title
• description (TEXT) - Photo description
• upload_date (DATETIME) - Upload timestamp
• file_size (INTEGER) - File size in bytes

Development Commands

Backend

# Run tests
python -m pytest

# Run with auto-reload
python app.py

# Install new dependency
pip install package_name
pip freeze > requirements.txt

Frontend

# Development server
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Lint code
npm run lint

Troubleshooting

Common Issues

1. Database connection errors

   • Ensure PostgreSQL is running
   • Check DATABASE_URL in .env file
   • Verify database exists

2. File upload errors

   • Check uploads directory permissions
   • Verify file size limits
   • Check allowed file types

3. CORS errors

   • Ensure CORS is properly configured
   • Check frontend API URLs

4. Docker issues

   • Run docker-compose down -v to reset volumes
   • Check Docker logs: docker-compose logs service_name

Port Conflicts

If ports 3000, 5000, or 5432 are in use:

• Update port mappings in docker-compose.yml
• Update API URLs in frontend configuration

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Ensure all tests pass
5. Submit a pull request

License

This project is open source and available under the MIT License.