Puddle - Classified Marketplace Platform

A Django-based peer-to-peer classified marketplace platform where users can list items for sale, browse products, and communicate directly with sellers.

📋 Features

• User Authentication: Sign up, login, and account management
• Item Management: Create, edit, and delete product listings
• Categories: Organize items by categories
• Image Support: Upload product images with Pillow
• Direct Messaging: In-app conversations between buyers and sellers
• User Dashboard: Personal dashboard for managing listings
• Contact Form: Get in touch functionality

🏗️ Project Structure

puddle/
├── core/                 # Core functionality (auth, landing page, contact)
├── item/                 # Item/Product management system
├── conversation/         # Direct messaging between users
├── dashboard/            # User dashboard and profiles
├── puddle/              # Main project settings and configuration
├── media/               # User uploaded content (images)
├── requirements.txt     # Python dependencies
├── manage.py            # Django management script
├── db.sqlite3           # Local development database
└── .gitignore           # Git ignore rules

🛠️ Tech Stack

• Backend: Django 5.2.9
• Database: SQLite (development), PostgreSQL (production recommended)
• Image Processing: Pillow 12.0.0
• Python: 3.10+

📦 Dependencies

Django==5.2.9
Pillow==12.0.0
asgiref==3.11.0
sqlparse==0.5.4
python-dotenv==1.0.1

🚀 Quick Start

Prerequisites

• Python 3.10 or higher
• pip (Python package manager)
• Virtual environment (recommended)

Installation

1. Clone the repository

   git clone https://github.com/sharma-sugurthi/puddle.git
   cd puddle

2. Create and activate virtual environment

   # On Linux/Mac
   python3 -m venv env
   source env/bin/activate
   
   # On Windows
   python -m venv env
   env\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Set up environment variables

   cp .env.example .env
   # Edit .env and add your SECRET_KEY and other configuration

5. Run migrations

   python manage.py migrate

6. Create a superuser (admin account)

   python manage.py createsuperuser

7. Collect static files (production)

   python manage.py collectstatic

8. Run the development server

   python manage.py runserver

   The application will be available at http://localhost:8000

📝 Environment Variables

Create a .env file in the project root (copy from .env.example):

# Django Configuration
SECRET_KEY=your-secret-key-here-change-in-production
DEBUG=True

# Database (optional - defaults to SQLite)
# DATABASE_URL=sqlite:///db.sqlite3

# Allowed Hosts (comma-separated)
ALLOWED_HOSTS=localhost,127.0.0.1

# Environment
ENVIRONMENT=development

🗄️ Database Models

Item App

• Category: Product categories
• Item: Product listings with images, price, and seller information

Conversation App

• Conversation: Messaging thread between buyers and sellers
• ConversationMessage: Individual messages in a conversation

Core App

• User authentication and landing pages

Dashboard App

• User dashboard and profile management

🔧 Common Commands

# Run development server
python manage.py runserver

# Create migrations
python manage.py makemigrations

# Apply migrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser

# Run tests
python manage.py test

# Access admin panel
# Visit http://localhost:8000/admin after creating superuser

📚 API Endpoints

Core App

• / - Home page
• /login/ - User login
• /signup/ - User registration
• /logout/ - User logout
• /contact/ - Contact form

Item App

• /items/ - Browse all items
• /items/<id>/ - Item detail view
• /items/new/ - Create new item
• /items/<id>/edit/ - Edit item
• /items/<id>/delete/ - Delete item

Conversation App

• /inbox/ - Message inbox
• /conversations/<id>/ - Conversation detail
• /conversations/new/<item_id>/ - Start new conversation

Dashboard

• /dashboard/ - User dashboard

🔐 Security Notes

⚠️ Important: Never commit the following to version control:

• .env files with real credentials
• Virtual environment directories (env/, venv/)
• Local database (db.sqlite3)
• __pycache__/ directories
• Sensitive configuration files

These are already covered in .gitignore.

Production Checklist

• Set DEBUG=False in .env
• Generate a secure SECRET_KEY
• Configure ALLOWED_HOSTS properly
• Set up database (PostgreSQL recommended)
• Configure email backend
• Enable HTTPS/SSL
• Set up static file serving (whitenoise or CDN)
• Configure CSRF and security middleware
• Set up error logging
• Use environment-specific settings

🐛 Troubleshooting

Module not found errors

pip install -r requirements.txt

Database errors

python manage.py migrate

Missing static files

python manage.py collectstatic --noinput

Permission issues on Linux/Mac

chmod +x manage.py

📖 Django Admin

Access the Django admin panel at /admin/ with your superuser credentials to:

• Manage users
• Manage items and categories
• Manage conversations
• View messages

🤝 Contributing

1. Create a feature branch: git checkout -b feature/your-feature
2. Commit your changes: git commit -m 'Add feature'
3. Push to the branch: git push origin feature/your-feature
4. Submit a pull request

📄 License

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

👥 Author

• Sugurthi Manisharma - GitHub Profile

📞 Support

For issues, questions, or suggestions, please:

1. Check existing issues on GitHub
2. Create a new issue with detailed information
3. Submit a pull request with fixes

---

Last Updated: December 2025