A modern, scalable SaaS platform for team collaboration and project management
Features • Demo • Tech Stack • Getting Started • Documentation • Contributing
- Overview
- Features
- Demo
- Tech Stack
- Architecture
- Getting Started
- Environment Variables
- API Documentation
- Testing
- Deployment
- Project Structure
- Contributing
- License
- Contact
TaskFlow is a production-ready, multi-tenant SaaS application designed for modern teams to manage projects efficiently. Built with Django and Next.js, it provides real-time collaboration, secure authentication, and scalable architecture suitable for teams of any size.
- 🏢 Multi-Tenant Architecture - Support unlimited organizations with complete data isolation
- ⚡ Real-Time Collaboration - WebSocket-powered live updates across all connected users
- 🔒 Enterprise Security - JWT authentication with HTTP-only cookies, CSRF/XSS protection
- 📊 Interactive Kanban Boards - Drag-and-drop task management with smooth animations
- ☁️ Cloud-Native - AWS-ready with Terraform IaC for one-command deployment
- 🎨 Modern UI/UX - Responsive design with Tailwind CSS and Shadcn UI components
- ✅ Secure JWT authentication with HTTP-only cookies
- ✅ User registration with email verification
- ✅ Password reset functionality
- ✅ Role-based access control (Owner, Admin, Member)
- ✅ Organization-level permissions
- ✅ Create and manage multiple organizations
- ✅ Invite members via email with tokenized links
- ✅ Role assignment (Owner, Admin, Member)
- ✅ Member management (add, remove, update roles)
- ✅ Organization settings and branding
- ✅ Create unlimited projects per organization
- ✅ Customizable project colors and descriptions
- ✅ Project members with granular permissions
- ✅ Archive/restore projects
- ✅ Project activity logging
- ✅ Interactive Kanban boards with drag-and-drop
- ✅ Default board lists (To Do, In Progress, In Review, Done)
- ✅ Custom list creation and ordering
- ✅ Task creation with rich descriptions
- ✅ Task assignments (multiple assignees)
- ✅ Priority levels (Low, Medium, High, Urgent)
- ✅ Due dates with overdue detection
- ✅ Labels/tags for categorization
- ✅ Task filtering (search, priority, assignee, overdue)
- ✅ Task position management within lists
- ✅ Threaded comments on tasks
- ✅ Real-time updates via WebSockets
- ✅ User presence indicators
- ✅ @mentions in comments (coming soon)
- ✅ Activity feed with comprehensive audit log
- ✅ File attachments on tasks
- ✅ AWS S3 integration with pre-signed URLs
- ✅ Support for images, documents, PDFs
- ✅ File metadata tracking
- ✅ Secure, time-limited file access
- ✅ Live task updates across all users
- ✅ Real-time position changes during drag-and-drop
- ✅ Instant comment notifications
- ✅ Online user presence
- ✅ WebSocket reconnection with exponential backoff
- ✅ Responsive design (mobile, tablet, desktop)
- ✅ Dark mode support (coming soon)
- ✅ Keyboard shortcuts
- ✅ Loading states and optimistic updates
- ✅ Error handling with user-friendly messages
- ✅ Accessibility (WCAG 2.1 AA compliant)
🚀 Try TaskFlow Demo (Coming Soon)
Demo Credentials:
- Email:
demo@taskflow.com - Password:
demo123456
- Python 3.14+ - Core programming language
- Django 5.0 - Web framework
- Django REST Framework - RESTful API
- Django Channels - WebSocket support
- PostgreSQL - Primary database
- Redis - Cache & WebSocket message broker
- Celery - Background task processing
- Boto3 - AWS SDK
- Next.js 14 - React framework (App Router)
- React 18 - UI library
- TypeScript - Type safety
- Tailwind CSS - Styling
- Shadcn UI - Component library
- DnD Kit - Drag-and-drop functionality
- Zustand - State management
- Axios - HTTP client
- Docker - Containerization
- AWS - Cloud platform
- ECS Fargate - Container orchestration
- RDS PostgreSQL - Managed database
- ElastiCache Redis - Managed cache
- S3 - Object storage
- CloudFront - CDN
- ALB - Load balancing
- Terraform - Infrastructure as Code
- GitHub Actions - CI/CD
- Git - Version control
- ESLint - JavaScript linting
- Prettier - Code formatting
- Black - Python formatting
- pytest - Python testing
- Jest - JavaScript testing
┌─────────────────────────────────────────────────────────────┐
│ Client Browser │
│ (React + Next.js) │
└────────────────────────┬────────────────────────────────────┘
│ HTTPS
↓
┌─────────────────────────────────────────────────────────────┐
│ CloudFront (CDN) │
│ (Static Assets + Caching) │
└────────────────────────┬────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────┐
│ Application Load Balancer (ALB) │
│ (HTTP/HTTPS + WebSocket Support) │
└────────────────────────┬────────────────────────────────────┘
│
┌────────────────┴────────────────┐
↓ ↓
┌───────────────┐ ┌───────────────┐
│ ECS Task 1 │ │ ECS Task 2 │
│ Django + Daphne│ │ Django + Daphne│
│ (ASGI Server) │ │ (ASGI Server) │
└───────┬───────┘ └───────┬───────┘
│ │
└────────────────┬────────────────┘
│
┌────────────────┼────────────────┐
↓ ↓ ↓
┌──────────────┐ ┌─────────────┐ ┌────────────┐
│ RDS │ │ ElastiCache │ │ S3 │
│ PostgreSQL │ │ Redis │ │ (Media) │
│ (Primary │ │ (Cache & │ │ │
│ Database) │ │ WebSocket) │ │ │
└──────────────┘ └─────────────┘ └────────────┘
# Every request includes organization context
request.organization → Organization Model
↓
All database queries filter by organization
↓
User only sees data from their organization(s)User Action (e.g., move task)
↓
Frontend sends WebSocket message
↓
Django Channels Consumer receives message
↓
Broadcast to all users in project group (Redis)
↓
All connected clients receive update
↓
Frontend updates UI optimistically
Before you begin, ensure you have the following installed:
- Python 3.14+ - Download
- Node.js 18+ - Download
- PostgreSQL 15+ - Download
- Redis 7+ - Download
- Git - Download
Optional (for production):
- Docker - Download
- AWS CLI - Install Guide
- Terraform - Install Guide
git clone https://github.com/kusiLaw/taskflow.git
cd taskflow# Navigate to backend directory
cd taskflow-backend
# Create virtual environment
python -m venv venv
# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Create .env file
cp .env.example .env
# Generate Django secret key
python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'
# Edit .env and add the generated secret key
nano .envBackend .env configuration:
# Django
SECRET_KEY=your-generated-secret-key-here
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1
# Database
DB_NAME=taskflow
DB_USER=postgres
DB_PASSWORD=your-db-password
DB_HOST=localhost
DB_PORT=5432
# Redis
REDIS_URL=redis://localhost:6379/0
# CORS
FRONTEND_URL=http://localhost:3000
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
# AWS (Optional - for file uploads)
AWS_ACCESS_KEY_ID=your-aws-access-key
AWS_SECRET_ACCESS_KEY=your-aws-secret-key
AWS_STORAGE_BUCKET_NAME=taskflow-media
AWS_S3_REGION_NAME=us-east-1
# Email (Optional - for invitations)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password
DEFAULT_FROM_EMAIL=noreply@taskflow.comCreate PostgreSQL database:
# Connect to PostgreSQL
psql -U postgres
# Create database
CREATE DATABASE taskflow;
# Create user (optional)
CREATE USER taskflow_user WITH PASSWORD 'your-password';
GRANT ALL PRIVILEGES ON DATABASE taskflow TO taskflow_user;
# Exit
\qRun migrations:
python manage.py makemigrations
python manage.py migrateCreate superuser:
python manage.py createsuperuserLoad initial data (optional):
python manage.py loaddata initial_data# Navigate to frontend directory (from root)
cd ../taskflow-frontend
# Install dependencies
npm install
# Create .env.local file
cp .env.example .env.local
# Edit .env.local
nano .env.localFrontend .env.local configuration:
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_WS_URL=ws://localhost:8000Start Backend (Terminal 1):
cd taskflow-backend
# Activate virtual environment
source venv/bin/activate # or venv\Scripts\activate on Windows
# Start Django server
python manage.py runserver 0.0.0.0:8000
# The backend will be available at http://localhost:8000Start Redis (Terminal 2):
redis-server
# Or if installed via Homebrew on macOS:
brew services start redisStart Frontend (Terminal 3):
cd taskflow-frontend
# Start Next.js development server
npm run dev
# The frontend will be available at http://localhost:3000Access the Application:
- Open your browser and navigate to
http://localhost:3000 - Register a new account or login with superuser credentials
- Create an organization and start managing projects!
See Deployment Guide for production setup.
| Variable | Description | Required | Default |
|---|---|---|---|
SECRET_KEY |
Django secret key | ✅ Yes | - |
DEBUG |
Debug mode | No | False |
ALLOWED_HOSTS |
Allowed host headers | ✅ Yes | - |
DB_NAME |
Database name | ✅ Yes | - |
DB_USER |
Database user | ✅ Yes | - |
DB_PASSWORD |
Database password | ✅ Yes | - |
DB_HOST |
Database host | ✅ Yes | localhost |
DB_PORT |
Database port | No | 5432 |
REDIS_URL |
Redis connection URL | ✅ Yes | - |
FRONTEND_URL |
Frontend URL | ✅ Yes | - |
CORS_ALLOWED_ORIGINS |
Allowed CORS origins | ✅ Yes | - |
AWS_ACCESS_KEY_ID |
AWS access key | No | - |
AWS_SECRET_ACCESS_KEY |
AWS secret key | No | - |
AWS_STORAGE_BUCKET_NAME |
S3 bucket name | No | - |
EMAIL_HOST |
SMTP host | No | - |
EMAIL_PORT |
SMTP port | No | 587 |
EMAIL_HOST_USER |
SMTP username | No | - |
EMAIL_HOST_PASSWORD |
SMTP password | No | - |
| Variable | Description | Required | Default |
|---|---|---|---|
NEXT_PUBLIC_API_URL |
Backend API URL | ✅ Yes | - |
NEXT_PUBLIC_WS_URL |
WebSocket URL | ✅ Yes | - |
POST /api/auth/register/
Content-Type: application/json
{
"email": "user@example.com",
"password": "SecurePass123!",
"first_name": "John",
"last_name": "Doe"
}
Response: 201 Created
{
"user": {
"id": "uuid",
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe",
"full_name": "John Doe"
},
"message": "Registration successful"
}POST /api/auth/login/
Content-Type: application/json
{
"email": "user@example.com",
"password": "SecurePass123!"
}
Response: 200 OK
Set-Cookie: access_token=...; HttpOnly
Set-Cookie: refresh_token=...; HttpOnly
{
"user": {
"id": "uuid",
"email": "user@example.com",
"full_name": "John Doe"
},
"message": "Login successful"
}GET /api/auth/me/
Cookie: access_token=...
Response: 200 OK
{
"id": "uuid",
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe",
"full_name": "John Doe",
"avatar": null
}POST /api/auth/logout/
Cookie: access_token=...
Response: 200 OK
{
"message": "Logout successful"
}GET /api/organizations/
Cookie: access_token=...
Response: 200 OK
[
{
"id": "uuid",
"name": "My Organization",
"description": "Our awesome company",
"owner": {
"id": "uuid",
"full_name": "John Doe",
"email": "john@example.com"
},
"member_count": 5,
"user_role": "owner",
"created_at": "2025-01-01T00:00:00Z"
}
]POST /api/organizations/
Cookie: access_token=...
Content-Type: application/json
{
"name": "New Organization",
"description": "Our new venture"
}
Response: 201 Created
{
"id": "uuid",
"name": "New Organization",
"description": "Our new venture",
"owner": {...},
"member_count": 1,
"user_role": "owner"
}POST /api/organizations/{org_id}/invite/
Cookie: access_token=...
X-Organization-ID: {org_id}
Content-Type: application/json
{
"email": "newmember@example.com",
"role": "member"
}
Response: 201 Created
{
"message": "Invitation sent to newmember@example.com",
"invitation": {...},
"invite_url": "http://localhost:3000/invite/token-here"
}GET /api/projects/?organization={org_id}
Cookie: access_token=...
X-Organization-ID: {org_id}
Response: 200 OK
[
{
"id": "uuid",
"name": "Website Redesign",
"description": "Redesign company website",
"color": "#3B82F6",
"organization": "uuid",
"members": [...],
"created_at": "2025-01-15T00:00:00Z"
}
]POST /api/projects/
Cookie: access_token=...
X-Organization-ID: {org_id}
Content-Type: application/json
{
"name": "Mobile App Development",
"description": "Build iOS and Android apps",
"color": "#10B981"
}
Response: 201 Created
{
"id": "uuid",
"name": "Mobile App Development",
"description": "Build iOS and Android apps",
"color": "#10B981",
"boards": [
{
"id": "uuid",
"name": "Main Board",
"lists": [
{"id": "uuid", "name": "To Do", "position": 0},
{"id": "uuid", "name": "In Progress", "position": 1},
{"id": "uuid", "name": "In Review", "position": 2},
{"id": "uuid", "name": "Done", "position": 3}
]
}
]
}GET /api/boards/?project={project_id}
Cookie: access_token=...
X-Organization-ID: {org_id}
Response: 200 OK
[
{
"id": "uuid",
"name": "Main Board",
"project": "uuid",
"lists": [
{
"id": "uuid",
"name": "To Do",
"position": 0,
"tasks": [
{
"id": "uuid",
"title": "Design homepage",
"description": "Create mockups for new homepage",
"priority": "high",
"due_date": "2025-02-01",
"assignees": [...],
"labels": [...],
"position": 0
}
]
}
]
}
]POST /api/tasks/
Cookie: access_token=...
X-Organization-ID: {org_id}
Content-Type: application/json
{
"title": "Implement user authentication",
"description": "Add JWT authentication system",
"priority": "high",
"due_date": "2025-02-15",
"board_list": "list-uuid",
"project": "project-uuid"
}
Response: 201 Created
{
"id": "uuid",
"title": "Implement user authentication",
"description": "Add JWT authentication system",
"priority": "high",
"due_date": "2025-02-15",
"position": 0,
"created_by": {...},
"assignees": [],
"labels": []
}PATCH /api/tasks/{task_id}/move/
Cookie: access_token=...
X-Organization-ID: {org_id}
Content-Type: application/json
{
"board_list_id": "new-list-uuid",
"position": 2
}
Response: 200 OK
{
"id": "uuid",
"title": "Implement user authentication",
"board_list": "new-list-uuid",
"position": 2
}For complete API documentation, see API_DOCS.md or visit /api/docs/ when running the backend.
cd taskflow-backend
# Run all tests
python manage.py test
# Run with coverage
pip install coverage
coverage run --source='.' manage.py test
coverage report
# Run specific test file
python manage.py test apps.accounts.tests
# Run with pytest (recommended)
pip install pytest pytest-django
pytest
# Run with verbose output
pytest -v
# Run with coverage
pytest --cov=apps --cov-report=htmlcd taskflow-frontend
# Run all tests
npm test
# Run in watch mode
npm test -- --watch
# Run with coverage
npm test -- --coverage
# Run specific test file
npm test -- TaskCard.test.tsx
# E2E tests with Playwright (if configured)
npm run test:e2eTaskFlow includes complete Infrastructure as Code (IaC) using Terraform for AWS deployment.
Quick Start:
cd aws-deployment
# 1. Install prerequisites
brew install awscli terraform
# 2. Configure AWS
aws configure
# 3. Setup Terraform
cd terraform
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your values
# 4. Deploy infrastructure
terraform init
terraform plan
terraform apply
# 5. Build and deploy application
cd ../scripts
./build-and-push.sh
./deploy.shFull deployment guide: aws-deployment/DEPLOYMENT_GUIDE.md
What gets deployed:
- ✅ ECS Fargate cluster (2-4 auto-scaled tasks)
- ✅ RDS PostgreSQL (Multi-AZ for production)
- ✅ ElastiCache Redis
- ✅ Application Load Balancer
- ✅ S3 bucket for media files
- ✅ CloudWatch logging
- ✅ Auto-scaling policies
- ✅ Security groups and VPC
Estimated monthly cost:
- Development: $67/month
- Production: $165/month
# Build images
docker-compose build
# Start services
docker-compose up -d
# View logs
docker-compose logs -f
# Stop services
docker-compose downFor manual deployment to other platforms (DigitalOcean, Heroku, etc.), see DEPLOYMENT.md.
taskflow/
├── taskflow-backend/ # Django backend
│ ├── apps/ # Django apps
│ │ ├── accounts/ # User authentication
│ │ ├── organizations/ # Multi-tenant organizations
│ │ └── projects/ # Projects, tasks, boards
│ ├── config/ # Django configuration
│ │ ├── settings/
│ │ │ ├── base.py # Base settings
│ │ │ ├── development.py # Dev settings
│ │ │ └── production.py # Prod settings
│ │ ├── urls.py # URL routing
│ │ ├── asgi.py # ASGI config (WebSockets)
│ │ └── wsgi.py # WSGI config
│ ├── core/ # Core utilities
│ │ └── middleware/ # Custom middleware
│ ├── manage.py
│ └── requirements.txt
│
├── taskflow-frontend/ # Next.js frontend
│ ├── app/ # Next.js 14 App Router
│ │ ├── (auth)/ # Auth pages (login, register)
│ │ ├── (dashboard)/ # Protected pages
│ │ │ └── dashboard/ # Main dashboard
│ │ │ ├── projects/ # Projects pages
│ │ │ └── organizations/ # Org settings
│ │ └── layout.tsx # Root layout
│ ├── components/ # React components
│ │ ├── ui/ # Shadcn UI components
│ │ ├── kanban/ # Kanban board components
│ │ ├── projects/ # Project components
│ │ └── organizations/ # Organization components
│ ├── lib/ # Utilities
│ │ ├── api/ # API client
│ │ ├── hooks/ # Custom React hooks
│ │ └── utils.ts # Helper functions
│ ├── store/ # Zustand state management
│ ├── types/ # TypeScript types
│ ├── public/ # Static assets
│ └── package.json
│
├── aws-deployment/ # AWS Infrastructure as Code
│ ├── terraform/ # Terraform configs
│ ├── docker/ # Production Dockerfiles
│ ├── scripts/ # Deployment scripts
│ └── DEPLOYMENT_GUIDE.md
│
├── docs/ # Documentation
│ ├── API_DOCS.md # API documentation
│ ├── ARCHITECTURE.md # Architecture details
│ └── CONTRIBUTING.md # Contributing guide
│
├── .github/ # GitHub configuration
│ └── workflows/ # GitHub Actions
│ └── deploy.yml # CI/CD pipeline
│
├── docker-compose.yml # Docker Compose config
├── .gitignore
├── LICENSE
└── README.md
We welcome contributions! Please follow these guidelines:
- Fork the repository
- Clone your fork:
git clone https://github.com/kusiLaw/taskflow.git cd taskflow - Create a feature branch:
git checkout -b feature/amazing-feature
- Make your changes
- Commit your changes:
git commit -m 'Add some amazing feature' - Push to your branch:
git push origin feature/amazing-feature
- Open a Pull Request
Backend (Python):
- Follow PEP 8
- Use Black for formatting
- Use isort for import sorting
- Maximum line length: 100 characters
# Format code
black .
isort .
# Lint
flake8Frontend (TypeScript):
- Follow Airbnb Style Guide
- Use Prettier for formatting
- Use ESLint for linting
# Format code
npm run format
# Lint
npm run lintFollow Conventional Commits:
feat: add user profile page
fix: resolve WebSocket reconnection issue
docs: update API documentation
style: format code with prettier
refactor: simplify authentication logic
test: add tests for task API
chore: update dependencies
- Update README.md with details of changes if needed
- Update documentation if you changed APIs
- Add tests for new features
- Ensure all tests pass
- Update CHANGELOG.md
- Request review from maintainers
Use GitHub Issues and include:
- Clear description
- Steps to reproduce
- Expected vs actual behavior
- Screenshots if applicable
- Environment details (OS, browser, versions)
Use GitHub Issues with enhancement label and describe:
- Problem you're trying to solve
- Proposed solution
- Alternative solutions considered
- Impact on existing features
This project is licensed under the MIT License - see the LICENSE file for details.
MIT License
Copyright (c) 2025 TaskFlow
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
- Django - The web framework for perfectionists with deadlines
- Next.js - The React framework for production
- Shadcn UI - Beautifully designed components
- Vercel - For Next.js and inspiration
- Tailwind CSS - For utility-first CSS
- All our contributors
Project Maintainer: Lawrence Kusi
- Email: lawrence.kusi.addai@gmail.com
- GitHub: @lawrencekusi
- LinkedIn: Lawrence Kusi
- Website: lawrencekusi.site
Project Link: https://github.com/kusiLaw/taskflow
Live Demo: https://taskflow-demo.com (Coming Soon)
If you find this project useful, please consider:
- ⭐ Starring the repository
- 🐛 Reporting bugs
- 💡 Suggesting new features
- 🔀 Submitting pull requests
- 📢 Sharing with others
Current Version: 1.0.0
Status: ✅ Production Ready
- User authentication
- Organization management
- Project management
- Kanban boards
- Real-time collaboration
- File attachments
- Dark mode
- Gantt chart view
- Time tracking
- Advanced search
- Bulk operations
- Keyboard shortcuts
- Slack integration
- GitHub integration
- Google Drive integration
- Email notifications
- Calendar sync
- Webhooks API
- iOS app (React Native)
- Android app (React Native)
- Progressive Web App (PWA)
- Single Sign-On (SSO)
- Advanced analytics
- Custom workflows
- API rate limiting
- White-labeling
- Audit logs
Built with ❤️ by Lawrence Kusi
⭐ Star this repo if you find it useful! ⭐