A modern, full-stack project management application built with Django and Reflex
- Overview
- Features
- Tech Stack
- Architecture
- Getting Started
- Installation
- Configuration
- Usage
- API Documentation
- Project Structure
- Authentication
- Development
- Testing
- Deployment
- Contributing
TeamHub is a comprehensive project management platform designed to streamline team collaboration, project organization, and task tracking. Built with modern technologies, it combines the power of Django's robust backend with Reflex's reactive frontend to deliver a seamless user experience.
- 🔐 Secure Authentication: Google OAuth 2.0 integration with JWT token-based authentication
- 👥 Team Management: Create and manage teams with role-based permissions
- 📊 Project Organization: Organize work into projects with automatic team member synchronization
- ✅ Task Tracking: Create, assign, and track tasks with status workflows (Todo → Doing → Done)
- 🎨 Beautiful UI: Modern, gradient-based interface with responsive design
- ⚡ Real-time Updates: Instant synchronization across teams, projects, and tasks
- 🔗 Project Joining: Unique join codes for easy project access
- ✅ Create teams (staff-only privilege)
- ✅ Add/remove team members
- ✅ Automatic team synchronization to projects
- ✅ Owner and member role distinction
- ✅ Real-time member count display
- ✅ Create projects linked to teams
- ✅ Automatic team member assignment to projects
- ✅ Unique join codes for external collaboration
- ✅ Project member listing and management
- ✅ Team-based project filtering
- ✅ Create tasks within projects
- ✅ Assign tasks to project members
- ✅ Three-stage status workflow: Todo, Doing, Done
- ✅ Task filtering by project
- ✅ Color-coded status badges
- ✅ Task detail modal with status updates
- ✅ Google OAuth 2.0 integration
- ✅ JWT (JSON Web Token) authentication
- ✅ Session-based token storage
- ✅ CORS-enabled API
- ✅ Permission-based access control
- ✅ Staff-only administrative features
- ✅ Responsive design for all devices
- ✅ Modal-based forms for creation workflows
- ✅ Tab-based navigation (Tasks, Projects, Teams)
- ✅ Beautiful gradient themes
- ✅ Loading states and error handling
- ✅ Jazzmin-powered Django admin interface
| Technology | Version | Purpose |
|---|---|---|
| Django | 5.2.10 | Web framework and ORM |
| Django REST Framework | 3.16.1 | RESTful API development |
| djangorestframework-simplejwt | 5.5.1 | JWT authentication |
| django-allauth | 65.13.1 | Social authentication |
| django-cors-headers | 4.6.0 | CORS support |
| django-jazzmin | 3.0.1 | Modern admin UI |
| google-auth | 2.37.0 | Google OAuth integration |
| SQLite | 3.x | Database (development) |
| Technology | Version | Purpose |
|---|---|---|
| Reflex | 0.8.26 | Python-based web framework |
| Tailwind CSS | V4 Plugin | Styling |
| Python | 3.10+ | Programming language |
- PowerShell - Server startup automation
- Requests - HTTP library for API calls
- python-dotenv - Environment variable management
TeamHub follows a modern full-stack architecture with clear separation of concerns:
┌─────────────────────────────────────────────────────────────┐
│ Frontend Layer │
│ (Reflex - Port 3000) │
│ ┌────────────┬─────────────┬─────────────┬──────────────┐ │
│ │ Login Page │ Tasks View │ Projects │ Teams View │ │
│ │ │ │ View │ │ │
│ └────────────┴─────────────┴─────────────┴──────────────┘ │
└─────────────────────┬───────────────────────────────────────┘
│ HTTP/HTTPS + JWT
│ (CORS Enabled)
┌─────────────────────▼───────────────────────────────────────┐
│ API Layer (REST) │
│ (Django - Port 8000) │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ /api/auth/google/ │ /api/tasks/ │ /api/projects/ │ │
│ │ /api/teams/ │ /api/users/ │ /api/token/ │ │
│ └────────────────────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────────────────┘
│ Django ORM
┌─────────────────────▼───────────────────────────────────────┐
│ Data Layer │
│ (SQLite Database) │
│ ┌──────────┬──────────┬──────────┬──────────┬──────────┐ │
│ │ User │ Profile │ Team │ Project │ Task │ │
│ └──────────┴──────────┴──────────┴──────────┴──────────┘ │
└─────────────────────────────────────────────────────────────┘
- Frontend (Reflex): Handles UI rendering, user interactions, and state management
- API Layer (Django REST Framework): Exposes RESTful endpoints with JWT authentication
- Business Logic: Django models with signals for automatic synchronization
- Database: SQLite for development (PostgreSQL recommended for production)
Before you begin, ensure you have the following installed:
- Python 3.10 or higher (Download)
- pip (Python package installer)
- Virtual environment (recommended)
- Git (for version control)
- PowerShell (Windows) or Bash (Linux/Mac)
- OS: Windows 10+, macOS 10.14+, or Linux
- RAM: 4GB minimum, 8GB recommended
- Disk Space: 500MB for dependencies
git clone https://github.com/yourusername/teamhub.git
cd teamhubWindows:
python -m venv venv
.\venv\Scripts\Activate.ps1Linux/Mac:
python3 -m venv venv
source venv/bin/activateInstall root-level dependencies (Reflex):
pip install -r requirements.txtInstall backend dependencies:
cd backend
pip install -r requirements.txt
cd ..Create a .env file in the backend/ directory:
# Django Settings
SECRET_KEY=your-secret-key-here
DEBUG=True
# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secretGenerate a Django secret key:
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"cd backend
python manage.py makemigrations
python manage.py migrate
python manage.py createsuperuser # Create admin account
cd ..Follow the guide in GOOGLE_LOGIN_SETUP.md to set up Google OAuth authentication.
- Go to Google Cloud Console
- Create a new project or select existing
- Enable Google+ API
- Create OAuth 2.0 credentials
- Add authorized origins:
http://localhost:3000http://127.0.0.1:3000
- Add authorized redirect URIs:
http://localhost:3000http://127.0.0.1:3000
- Copy Client ID and Secret to
.env
CORS is pre-configured in backend/teamhub/settings.py:
CORS_ALLOWED_ORIGINS = [
"http://localhost:3000",
"http://127.0.0.1:3000",
]
CORS_ALLOW_CREDENTIALS = TrueWindows:
.\start_servers.ps1This script automatically starts both Django and Reflex servers.
Terminal 1 - Django Backend:
cd backend
python manage.py runserver 8000Terminal 2 - Reflex Frontend:
python -m reflex run
or
reflex run| Service | URL | Description |
|---|---|---|
| Frontend | http://localhost:3000 | Main application UI |
| Backend API | http://localhost:8000/api/ | RESTful API endpoints |
| Django Admin | http://localhost:8000/admin/ | Admin dashboard |
- Login with Google OAuth or create a user account
- Create a Team (staff users only)
- Create a Project and select a team
- Create Tasks within projects
- Assign and Track tasks through completion
All API endpoints (except login) require JWT authentication via the Authorization header:
Authorization: Bearer <your-jwt-token>
POST /api/token/
POST /api/token/refresh
POST /api/auth/google/login/
GET /api/auth/google/callback/custom/GET /api/users/GET /api/teams/
POST /api/teams/create/GET /api/projects/
POST /api/projects/create/
POST /api/projects/join/GET /api/tasks/
POST /api/tasks/
PATCH /api/tasks/<task_id>/For complete API documentation with request/response examples, see API_DOCUMENTATION.md.
teamhub/
├── assets/ # Static assets
│ └── favicon.ico
├── backend/ # Django backend
│ ├── accounts/ # User accounts & profiles
│ │ ├── migrations/
│ │ ├── models.py # Profile, Email_verification
│ │ ├── views.py
│ │ └── urls.py
│ ├── api/ # REST API
│ │ ├── serializers.py # DRF serializers
│ │ ├── views.py # API views
│ │ ├── google_oauth_views.py
│ │ └── urls.py
│ ├── core/ # Core functionality
│ │ ├── permission.py
│ │ └── views.py
│ ├── projects/ # Project management
│ │ ├── models.py # Project model with signals
│ │ ├── views.py
│ │ └── forms.py
│ ├── task/ # Task management
│ │ ├── models.py # Task model
│ │ ├── views.py
│ │ └── forms.py
│ ├── teams/ # Team management
│ │ ├── models.py # Team model with signals
│ │ ├── views.py
│ │ └── forms.py
│ ├── teamhub/ # Django settings
│ │ ├── settings.py # Main configuration
│ │ ├── urls.py # URL routing
│ │ └── wsgi.py
│ ├── templates/ # Django templates
│ ├── manage.py
│ └── requirements.txt
├── teamhub/ # Reflex frontend
│ ├── __init__.py
│ └── teamhub.py # Main Reflex app (1200+ lines)
├── .gitignore
├── rxconfig.py # Reflex configuration
├── requirements.txt # Root dependencies
├── start_servers.ps1 # Server startup script
├── GOOGLE_LOGIN_SETUP.md # OAuth setup guide
├── TESTING_GUIDE.md # Testing instructions
└── README.md # This file
┌─────────┐ ┌─────────┐
│ Client │ │ Server │
└────┬────┘ └────┬────┘
│ │
│ 1. POST /api/token/ │
│ {username, password} │
│─────────────────────────────────────────────>│
│ │
│ 2. {access_token, refresh_token} │
│<─────────────────────────────────────────────│
│ │
│ 3. Store tokens in sessionStorage │
│ │
│ 4. GET /api/tasks/ │
│ Authorization: Bearer <access_token> │
│─────────────────────────────────────────────>│
│ │
│ 5. Task data │
│<─────────────────────────────────────────────│
│ │
- User clicks "Sign in with Google"
- Redirected to Google OAuth consent screen
- Google returns authorization code
- Backend exchanges code for access token
- Backend retrieves user info from Google
- User created/retrieved in database
- JWT token generated and returned
- Frontend stores token and redirects
The application uses hot-reload for both frontend and backend:
- Reflex: Automatically reloads on file changes
- Django: Use
--reloadflag (default withrunserver)
- Python: Follow PEP 8 guidelines
- Django: Follow Django's coding style
- Reflex: Follow Reflex best practices
User (Django built-in)
- Extended with Profile model for email verification
Team
- name: CharField
- owner: ForeignKey(User)
- members: ManyToManyField(User)
- created_at: DateTimeFieldProject
- name: CharField
- team: ForeignKey(Team)
- members: ManyToManyField(User)
- join_code: CharField (unique, auto-generated)
- created_at: DateTimeFieldTask
- title: CharField
- description: TextField
- project: ForeignKey(Project)
- assigned_to: ForeignKey(User, nullable)
- status: CharField (todo/doing/done)
- created_at: DateTimeFieldAutomatic Team Synchronization:
@receiver(post_save, sender=Project)
def add_team_members_to_project(sender, instance, created, **kwargs):
# Automatically adds team members to newly created projectsAutomatic Member Updates:
@receiver(m2m_changed, sender=Team.members.through)
def sync_team_members_to_projects(sender, instance, action, pk_set, **kwargs):
# Syncs team member changes to all team projectsFollow the comprehensive guide in TESTING_GUIDE.md.
- User registration and login
- Google OAuth authentication
- Team creation (staff only)
- Project creation with team selection
- Task creation and assignment
- Task status updates (todo → doing → done)
- Project joining via code
- Automatic team member sync to projects
Via Django Admin:
# Access admin at http://localhost:8000/admin/
1. Create users (mark one as staff)
2. Create a team
3. Add members to team
4. Projects are created via frontendVia Frontend:
- Login as staff user
- Navigate to Teams tab
- Click "Create Team"
- Add members and save
- Set
DEBUG = Falsein settings.py - Use PostgreSQL or MySQL instead of SQLite
- Configure proper
ALLOWED_HOSTS - Set up HTTPS/SSL certificates
- Use environment variables for secrets
- Configure static file serving (WhiteNoise or CDN)
- Set up proper logging
- Enable CSRF protection
- Configure secure cookies
- Set up monitoring and error tracking
SECRET_KEY=<strong-secret-key>
DEBUG=False
ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com
DATABASE_URL=postgres://user:pass@host:port/dbname
GOOGLE_CLIENT_ID=<production-client-id>
GOOGLE_CLIENT_SECRET=<production-client-secret>
CORS_ALLOWED_ORIGINS=https://yourdomain.com- Backend: Heroku, Railway, DigitalOcean, AWS
- Frontend: Vercel, Netlify, Reflex Hosting
- Database: PostgreSQL on Heroku, AWS RDS, or Supabase
- Static Files: AWS S3, Cloudflare
Contributions are welcome! Please follow these guidelines:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Write clear commit messages
- Add tests for new features
- Update documentation
- Follow existing code style
- Ensure all tests pass
For questions, issues, or feature requests:
- 📧 Email: cprazwal@gmail.com
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- Real-time notifications with WebSockets
- Task comments and attachments
- Advanced task filtering and search
- Team activity timeline
- Email notifications
- Task due dates and reminders
- Project templates
- Export functionality (PDF, CSV)
- Mobile app (React Native)
- Advanced analytics and reporting
- Time tracking integration
- Calendar integration (Google Calendar, Outlook)
- File storage and sharing
- Advanced permissions (custom roles)
- API webhooks
- Third-party integrations (Slack, Discord)