Skip to content
BranchesTags

Repository files navigation

🏋️ GRIND - Sports Social Platform

A modern, production-ready sports social media platform (Twitter/Threads clone) built with pure Django, featuring real athlete data, responsive design, and all core social features.

Built for the IIM Digital School Django Formation (26h30)
Complete example of Django architecture, ORM, templates, API, authentication, and deployment.

🎯 What is GRIND?

GRIND is a Twitter/Threads-like social platform for sports athletes:

  • 📱 Post sports updates and achievements
  • ❤️ Like, retweet, and reply to posts
  • 👥 Follow other athletes
  • 💬 Direct messaging system
  • 🔔 Notifications and activity tracking
  • 📊 Trending topics and hashtags
  • 🎨 Modern, responsive UI (red & white theme)
  • ⚡ Real-time AJAX interactions
  • 📊 Real athlete data (no mocks)

✨ Key Features

🏠 Home Timeline

  • Two-feed system: Everyone's posts & Friends-only posts
  • Real-time like/retweet/bookmark updates
  • Hover tooltips for action hints
  • Live counter updates without page reload

👤 User Profiles

  • Profile stats (followers, following, posts count)
  • Follow/Unfollow buttons
  • Direct message button
  • User activity timeline

💬 Messaging System

  • One-on-one conversations
  • Filtered by followed users
  • Direct messaging from any profile
  • Unread message badges
  • Real-time conversation threads

🔔 Notifications & Discovery

  • Activity notifications
  • Trending hashtags
  • Bookmarked posts
  • Tweet replies and threads

🎨 UI/UX Excellence

  • ✅ Professional red & white design
  • ✅ Full responsive (mobile/tablet/desktop)
  • ✅ Smooth AJAX interactions
  • ✅ Hover tooltips (Like, Retweet, Reply, Bookmark, Share)
  • ✅ Bottom navigation for mobile
  • ✅ Custom scrollbars
  • ✅ Gradient avatars

🗄️ Database & Backend

  • ✅ PostgreSQL (production-ready)
  • ✅ Redis caching
  • ✅ Django ORM with proper indexing
  • ✅ Signals for auto-profile creation
  • ✅ 30+ API endpoints (DRF)
  • ✅ JWT Authentication
  • ✅ Fine-grained permissions

⚽ Real Sports Data

  • 6 real athletes: Messi, Ronaldo, Mbappé, Haaland, Neymar, Benzema
  • 10+ authentic sports posts
  • 40+ real interactions
  • Hashtag tracking and trending

🧪 Quality Assurance

  • ✅ Comprehensive test suite
  • ✅ 100% passing tests
  • ✅ Functional testing
  • ✅ Security-focused

🚀 Quick Start (5 minutes)

Prerequisites

✓ Docker & Docker Compose
✓ Python 3.8+
✓ Git

Installation

# 1. Clone & enter repo
cd /path/to/Django

# 2. Start Docker services (PostgreSQL + Redis)
docker-compose up -d

# 3. Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Run migrations
python manage.py migrate

# 6. Load sports data
python manage.py seed_sports_data

# 7. Create superuser (optional)
python manage.py createsuperuser

# 8. Start development server
python manage.py runserver

Open http://localhost:8000 🎉

Demo Credentials

Username: messi    Password: messi123
Username: ronaldo  Password: ronaldo123
Username: neymar   Password: neymar123

📍 Accessing the Application

Component URL Purpose
🏠 Web App http://localhost:8000 Main social platform
🔧 Django Admin http://localhost:8000/admin Database management
🔌 API http://localhost:8000/api REST endpoints
📖 API Docs http://localhost:8000/api Browsable API

🗂️ Project Structure

Django/
├── manage.py                          # Django entry point
├── docker-compose.yml                 # PostgreSQL + Redis setup
├── requirements.txt                   # Python dependencies
├── .env                               # Environment variables
├── .gitignore                         # Git ignore rules
│
├── qa_platform/                       # Django project config
│   ├── settings.py                    # DB, cache, apps config
│   ├── urls.py                        # Main routing
│   ├── wsgi.py
│   └── asgi.py
│
├── core/                              # Main app (social features)
│   ├── models.py                      # Tweet, Like, Follow, Message, etc.
│   ├── views.py                       # Timeline, profile, messaging views
│   ├── urls.py                        # Web routes
│   ├── admin.py                       # Admin interface
│   ├── signals.py                     # Auto-profile creation
│   ├── migrations/                    # Database schema
│   ├── management/
│   │   └── commands/
│   │       └── seed_sports_data.py    # Load 6 athletes + posts
│   └── templates/
│       ├── base.html                  # Base template (nav, AJAX handlers)
│       └── core/
│           ├── timeline.html          # Home feed (2 tabs)
│           ├── profile.html           # User profiles
│           ├── post_tweet.html        # Create post
│           ├── reply_tweet.html       # Reply composer
│           ├── tweet_detail.html      # Post detail + replies
│           ├── messages.html          # Messaging inbox
│           ├── message_thread.html    # Chat thread
│           ├── new_message.html       # Start conversation
│           ├── notifications.html     # Activity feed
│           ├── trending.html          # Trending hashtags
│           └── bookmarks.html         # Saved posts
│
├── api/                               # REST API (DRF)
│   ├── serializers.py                 # JSON serialization
│   ├── viewsets.py                    # API endpoints
│   ├── permissions.py                 # Fine-grained auth
│   ├── urls.py                        # API routes
│   └── migrations/
│
├── tests.py                           # Test suite
├── README.md                          # This file
├── GETTING_STARTED.md                 # Detailed setup guide
└── ARCHITECTURE.md                    # Technical architecture

🎯 Core Pages & Routes

Timeline (/)

  • Everyone tab: All posts from all users
  • Friends tab: Only posts from followed users
  • Composer: Create new posts (280 chars)
  • Actions: Like, retweet, reply, bookmark (AJAX)

Profile (/profile/<username>/)

  • User info: name, handle, bio, location, join date
  • Stats: followers, following, posts count
  • Follow/Unfollow button
  • Message button for DMs
  • User's posts timeline

Messaging (/messages/)

  • Inbox: conversations with followed users
  • Unread badges
  • Last message preview
  • Sorted by recency

Message Thread (/messages/<username>/)

  • One-on-one chat
  • Sender/receiver distinction
  • Real-time message sending
  • Auto-mark as read

New Conversation (/messages/new/)

  • List of followed users
  • Search filter
  • Click to start DM

Tweet Detail (/tweets/<id>/)

  • Full post content
  • Reply section
  • All actions (like, retweet, bookmark)

Notifications (/notifications/)

  • Activity from followed users
  • Unread count
  • Auto-mark as read

Trending (/trending/)

  • Top hashtags by usage
  • Real-time trending data

Bookmarks (/bookmarks/)

  • Saved posts
  • Personal collection

🔌 API Endpoints (30+)

Timeline & Posts

GET    /api/tweets/                    # List all tweets
POST   /api/tweets/                    # Create tweet (auth)
GET    /api/tweets/{id}/               # Tweet detail
DELETE /api/tweets/{id}/               # Delete (author)

Interactions

POST   /api/tweets/{id}/like/          # Like tweet
POST   /api/tweets/{id}/unlike/        # Unlike tweet
POST   /api/tweets/{id}/retweet/       # Retweet
POST   /api/tweets/{id}/unretweet/     # Unretweet
POST   /api/tweets/{id}/bookmark/      # Bookmark
POST   /api/tweets/{id}/unbookmark/    # Remove bookmark

Follows & Relationships

POST   /api/users/{id}/follow/         # Follow user
POST   /api/users/{id}/unfollow/       # Unfollow
GET    /api/users/{id}/followers/      # Get followers
GET    /api/users/{id}/following/      # Get following

Messaging

GET    /api/messages/                  # List conversations
POST   /api/messages/                  # Create message
GET    /api/messages/{username}/       # Get thread

Discovery

GET    /api/hashtags/                  # List hashtags
GET    /api/hashtags/{name}/           # Hashtag detail
GET    /api/notifications/             # Get notifications

Authentication

POST   /api/auth/token/                # Get JWT token
POST   /api/auth/token/refresh/        # Refresh token

🗄️ Database Models

Core Models

  • User (Django auth) - Extended with Profile
  • Profile - User metadata, counts, bio
  • Tweet - Posts with parent_tweet for replies
  • Like - Favorites system
  • Retweet - Share/forward system
  • Reply - Comments on tweets
  • Follow - User relationships
  • Message - DM conversations
  • Bookmark - Saved posts
  • Notification - Activity feed
  • Hashtag - Trending topics
  • TweetHashtag - Many-to-many tags

Key Indexes

-- Fast lookups
CREATE INDEX ON tweets(author_id, created_at)
CREATE INDEX ON follows(follower_id, following_id)
CREATE INDEX ON messages(sender_id, recipient_id, created_at)
CREATE INDEX ON likes(user_id, tweet_id)
CREATE UNIQUE INDEX ON hashtags(name)

🔐 Security Features

  • ✅ Django Authentication - Session-based + JWT
  • ✅ Permissions - @login_required, IsAuthenticated, custom perms
  • ✅ CSRF Protection - Built-in Django CSRF middleware
  • ✅ XSS Prevention - Template auto-escaping ({{ content }})
  • ✅ SQL Injection Safe - Django ORM parameterized queries
  • ✅ Password Hashing - Django password validators (PBKDF2)
  • ✅ Rate Limiting - Ready for integration
  • ✅ HTTPS Ready - Production settings available

🐳 Docker Setup

PostgreSQL

Image: postgres:15-alpine
Port: 5432
Database: qa_platform
User: qa_user
Volume: postgres_data (persistent)

Redis

Image: redis:7-alpine
Port: 6379
Volume: redis_data (persistent)

Commands

docker-compose up -d       # Start services
docker-compose ps          # View status
docker-compose logs -f     # Stream logs
docker-compose down        # Stop services
docker-compose down -v     # Remove volumes (reset DB)

📊 Tech Stack

Backend

  • Django 6.0.6 - Web framework
  • Django REST Framework 3.17.1 - API framework
  • Simple JWT - Token authentication
  • PostgreSQL 15 - Production database
  • Redis 7 - Caching & sessions
  • Python 3.9+ - Programming language

Frontend

  • HTML5 - Semantic markup
  • Tailwind CSS 3.4 - Styling (CDN)
  • FontAwesome 6.4 - Icons (CDN)
  • Vanilla JavaScript - No build step

DevOps & Testing

  • Docker & Docker Compose - Containerization
  • Git - Version control
  • Python unittest - Testing framework
  • Pytest - Advanced testing (optional)

🧪 Testing

Run All Tests

python manage.py test -v 2

Run Specific Test

python manage.py test core.tests.TimelineViewTests

Run with Coverage

coverage run --source='.' manage.py test
coverage report
coverage html  # Generate HTML report

Test Categories

  • ✅ Model tests (ORM, validation)
  • ✅ View tests (templates, context)
  • ✅ API tests (DRF endpoints, auth)
  • ✅ Functional tests (user workflows)
  • ✅ Security tests (permissions)

🚀 Deployment

Production Checklist

□ Change DEBUG = False
□ Set SECRET_KEY to random value
□ Configure ALLOWED_HOSTS
□ Use strong database password
□ Setup HTTPS/SSL certificates
□ Configure email backend
□ Setup database backups
□ Enable security middleware
□ Configure CORS for APIs
□ Setup logging & monitoring
□ Use Gunicorn/uWSGI
□ Setup Nginx reverse proxy

Deployment Options

  • Heroku - Easy cloud (git push deploy)
  • DigitalOcean - Droplets + App Platform
  • AWS - EC2 + RDS + ElastiCache
  • Railway - Modern cloud platform
  • PythonAnywhere - Python-specific hosting
  • VPS - Full control (Linode, Vultr)

Production Settings

DEBUG = False
SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_HSTS_SECONDS = 31536000
SECURE_BROWSER_XSS_FILTER = True
SECURE_CONTENT_SECURITY_POLICY = {...}

📚 Documentation

Document Purpose
README.md Project overview & quick start (this file)
GETTING_STARTED.md Detailed setup & troubleshooting
ARCHITECTURE.md Technical deep dive & design decisions

External Resources

🎓 Learning Goals (IIM Formation)

This project demonstrates:

✅ Django Fundamentals

  • Project structure & apps architecture
  • Models, views, URLs (MVT pattern)
  • Django ORM & migrations
  • Admin interface
  • Middleware & signals

✅ API Development

  • Django REST Framework setup
  • Serializers & viewsets
  • Permissions & authentication
  • Browsable API
  • Token auth (JWT)

✅ Frontend Integration

  • Template rendering
  • AJAX requests (fetch API)
  • Form handling & validation
  • Responsive design (Tailwind)
  • Real-time updates

✅ Database Design

  • Model relationships (FK, M2M)
  • Indexing & optimization
  • Query optimization (select_related, prefetch_related)
  • Data integrity with signals
  • PostgreSQL features

✅ Authentication & Security

  • User authentication
  • Permissions & access control
  • CSRF protection
  • XSS prevention
  • SQL injection safety
  • Password hashing

✅ Testing & Quality

  • Unit tests
  • Integration tests
  • Test fixtures
  • Test organization
  • Coverage analysis

✅ Deployment & DevOps

  • Docker containerization
  • Environment configuration
  • Production settings
  • Security hardening
  • CI/CD readiness

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Write tests for new features
  5. Commit with clear messages
  6. Push to your fork
  7. Submit a pull request

Code Style

  • Follow PEP 8
  • Use type hints where helpful
  • Write descriptive commit messages
  • Add docstrings to functions

📄 License

MIT License - See LICENSE file for details

📞 Support

  • 📖 Check GETTING_STARTED.md for setup issues
  • 🏗️ See ARCHITECTURE.md for technical details
  • 🐛 Create an issue for bugs
  • 💡 Suggest features via discussions

🎉 Summary

GRIND is a complete, production-ready Django application that demonstrates:

Feature Status
Pure Django architecture ✅ 100%
Responsive design ✅ Mobile/Tablet/Desktop
Real data ✅ 6 athletes, 40+ posts
All features working ✅ Posts, follows, DMs, notifications
API endpoints ✅ 30+ DRF endpoints
Security ✅ Auth, permissions, CSRF
Testing ✅ Comprehensive test suite
Documentation ✅ README, ARCHITECTURE, GETTING_STARTED
Docker ready ✅ PostgreSQL + Redis
Production ready ✅ WSGI, settings, security

Built for learning, designed for production! 🚀

Made with ❤️ for the IIM Digital School Django Formation
Last updated: June 16, 2026

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages