TaskFlow

TaskFlow is a modern project and task-management SaaS application built as a classroom project for a Full-Stack Development + AI course.

The application will be fully functional as a conventional project-management product before the AI lesson begins. The future AI lesson is intentionally out of scope for the initial phases.

Creative Hub Kosovo — Phase 7

TaskFlow is the classroom starter for Creative Hub Kosovo, Full-Stack Development + AI, Phase 7 — OpenAI Integration. It is already a functional React and Django application: students will add the OpenAI functionality during the lecture without rebuilding the normal project-management product.

Requirements

• Python 3.9 or later
• Node.js 22 or later, including npm
• Git

Local development uses SQLite. PostgreSQL, Docker, Redis, and other infrastructure are not required.

Student quick start

Clone the canonical classroom repository and enter the project:

git clone https://github.com/arditcurri6/creative-hub-taskflow.git
cd creative-hub-taskflow

Backend

cd backend
python -m venv .venv

Activate the environment:

# macOS/Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

Install dependencies, create the local environment file, prepare the database, seed the demo workspace, and start Django:

pip install -r requirements.txt

# macOS/Linux
cp .env.example .env

# Windows
copy .env.example .env

python manage.py migrate
python manage.py seed_demo
python manage.py runserver

Frontend

Open a second terminal from the repository root:

cd frontend
npm install

# macOS/Linux
cp .env.example .env

# Windows
copy .env.example .env

npm run dev

Open the frontend at http://localhost:5173. The backend runs at http://localhost:8000.

Demo login

Use the primary local classroom account after running python manage.py seed_demo:

Email	Password
ardit@taskflow.local	TaskFlow123!

These credentials are local demo data only. They still use the normal TaskFlow login endpoint and are never a production authentication shortcut.

Foundation status

TaskFlow now provides a complete Django REST API and React/Vite productivity application: JWT authentication, projects, memberships, task workflow, dashboard metrics, Kanban board, and responsive workspace views. The five future AI entry points are visible in the UI, but they are intentionally non-functional until the dedicated Phase 7 lesson.

Technology stack

Layer	Technology
Frontend	React, Vite, JavaScript, React Router
Backend	Python, Django, Django REST Framework
Authentication	JWT
Local database	SQLite
Architecture	React single-page application consuming a Django REST API

Repository layout

taskflow/
├── backend/
│   ├── config/                 # Django project configuration
│   └── apps/
│       ├── accounts/           # Custom user model and JWT-facing auth flows
│       ├── common/             # Health endpoint and future shared utilities
│       ├── projects/           # Projects and owner/member authorization
│       ├── tasks/              # Task workflow, status, priority, and assignees
│       ├── comments/           # Future task discussion
│       └── activity/           # Future append-only task activity history
└── frontend/
    └── src/
        ├── app/                # App shell, providers, routing, route guards
        ├── features/           # Product areas organized by user workflow, including UI-only AI preparation
        ├── components/         # Shared layout and reusable UI components
        ├── services/           # REST API client and auth token handling
        ├── hooks/              # Reusable frontend hooks
        └── styles/             # Global styles, tokens, and responsive foundations

The backend, frontend application shell, project workspace, Kanban board, dashboard, and My Tasks views are implemented. Comments and activity remain intentional future domains.

Backend development

Prerequisite: Python 3.9 or later.

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python manage.py migrate
python manage.py seed_demo
python manage.py runserver

On Windows, use the equivalent commands:

.venv\Scripts\activate
copy .env.example .env

The development configuration uses SQLite at backend/db.sqlite3. Copy .env.example to .env to set a unique local Django secret key and adjust local CORS origins if needed. The .env file is ignored by Git.

Classroom demo data

python manage.py seed_demo creates a local, repeatable classroom workspace. It is safe to run again: it updates the same demo projects and tasks instead of creating duplicates, and restores the known demo password for the explicitly local demo accounts.

Name	Email	Classroom role
Ardit Curri	ardit@taskflow.local	Lecturer and project owner
Sara Krasniqi	sara@taskflow.local	Frontend developer
Leon Berisha	leon@taskflow.local	Backend developer
Era Hoxha	era@taskflow.local	UI/UX designer

All demo accounts use the local-only password TaskFlow123!. These accounts and this password are for classroom development only; they are not an authentication shortcut and students still sign in through the normal login form.

The command creates two projects:

• Rina Commerce Platform — the primary, 20-task software-development board with work across every status, varied priorities, assignees, due dates, and an overdue task.
• TaskFlow Mobile Experience — a smaller six-task project that makes the dashboard, project list, and My Tasks view feel like a real multi-project workspace.

Available API endpoints

Method	Endpoint	Access
GET	/api/health/	Public
POST	/api/auth/register/	Public
POST	/api/auth/login/	Public
POST	/api/auth/refresh/	Public
GET	/api/auth/me/	JWT required
GET / POST	/api/projects/	JWT required
GET / PATCH / DELETE	/api/projects/{id}/	Accessible users; owner-only writes
GET / POST	/api/projects/{id}/members/	Accessible users; owner-only adds
DELETE	/api/projects/{id}/members/{user_id}/	Owner only
GET / POST	/api/projects/{project_id}/tasks/	Project owners and members
GET / PATCH / DELETE	/api/projects/{project_id}/tasks/{task_id}/	Project owners and members; delete rules apply

Send access tokens as Authorization: Bearer <access-token>.

Frontend development

Prerequisite: Node.js 22 or later.

cd frontend
cp .env.example .env
npm install
npm run dev

On Windows, use copy .env.example .env to create the local environment file.

The frontend runs at http://localhost:5173 by default. Its VITE_API_BASE_URL environment variable defaults to http://localhost:8000/api in .env.example.

For local development, run the backend and frontend in separate terminals:

# Terminal 1
cd backend
source .venv/bin/activate
python manage.py runserver

# Terminal 2
cd frontend
cp .env.example .env
npm run dev

On Windows, use copy .env.example .env in the frontend directory.

Project authorization

• The project owner is stored only in Project.owner; the owner does not have a membership row.
• Owners can read, edit, delete, and manage project membership.
• Normal members can read the project and its member list, and will participate in future task work.
• Unrelated authenticated users receive no project or membership data.
• Adding a member accepts the existing user's email address; invitations and ownership transfer are intentionally not implemented.

Task authorization and filters

• Owners and members can list, view, create, update, set status/priority, and assign tasks within an accessible project.
• Owners can delete any project task. Members can delete only tasks they created.
• Assignees must be the project owner or a current normal member. Assignments can be cleared.
• Task project and creator are controlled by the URL and authenticated user, and cannot be supplied by the client.
• Task lists support status, priority, and assignee query parameters. Filters can be combined.

Primary domain model

Entity	Main responsibility	Key relationships
User	Authenticated account and core identity	Owns projects; participates in project memberships; authors comments and activity
Project	A workspace for planning and delivering work	Owned by one User; has many memberships and tasks
ProjectMembership	Membership and authorization within a project	Links one non-owner User to one Project; has no role field
Task	A unit of work	Belongs to one Project; has a creator, an optional owner-or-member assignee, workflow status, priority, and optional due date
Comment	Discussion attached to a task	Belongs to one Task and has one author (User)
Activity	Immutable history of meaningful task changes	Belongs to one Task; records the actor (User) when applicable

Task.status is one of BACKLOG, TODO, IN_PROGRESS, REVIEW, or DONE.

Task.priority is one of LOW, MEDIUM, HIGH, or URGENT.

Important relationship rules:

• A project owner is represented exclusively by Project.owner, not by a duplicate membership row.
• Project membership is the source of authorization for project, task, comment, and activity access.
• A task assignee must be either the owner or a normal member of the task's project.
• The server creates activity entries for significant changes such as task creation, status changes, reassignment, and due-date updates.

Planned Django apps

App	Responsibility
accounts	Custom user model, registration/login, and JWT integration
projects	Projects, non-owner membership records, and project-level authorization
tasks	Task CRUD, statuses, priorities, assignees, due dates, and Kanban-ready filters
comments	Task comments and comment permissions
activity	Append-only activity/history records and serializers
common	Minimal shared permissions, pagination, constants, or utilities that genuinely serve multiple apps

Planned React feature areas and pages

Feature area	Planned pages or views
Authentication	Sign in, sign up, session recovery, and protected-route handling
Dashboard	Personal overview of recent projects, assigned work, deadlines, and progress
Projects	Project list, project creation, project settings, and member management
Project board	Kanban board grouped by the five task statuses, with filtering and search
Task detail	Task description, priority, assignee, due date, comments, and activity timeline
Profile	Profile details and account settings
Shared application shell	Responsive navigation, page headers, dialogs, forms, feedback states, and reusable UI

Implementation phases

1. Repository foundation — Create the documentation, conventions, and directory layout. (Complete.)
2. Backend foundation — Initialize Django and DRF, configure SQLite, create the custom user model, add JWT authentication, and establish API conventions. (Complete.)
3. Project domain — Implement projects, non-owner memberships, permissions, and tests. (Complete.)
4. Task workflow backend — Implement tasks, statuses, priorities, assignees, due dates, project-scoped authorization, and Kanban-ready filtering. (Complete.)
5. Frontend foundation — Initialize Vite/React, configure routing, API transport, authentication state, global styles, and the responsive application shell. (Complete.)
6. Product UI and quality — Build the dashboard, project pages, Kanban board, task detail flows, profile pages, polished responsive states, integration-focused tests, accessibility checks, API documentation, and classroom setup instructions. (Complete for the normal product.)
7. Dedicated AI lesson — Only after the normal product is complete, design and implement the explicitly requested OpenAI-powered features.

Intentional AI boundary

The UI presents five deliberately inactive classroom touchpoints—Generate Tasks, Improve Description, Suggest Priority, Project Summary, and Generate Standup. They communicate that integration is pending, but do not send requests, generate content, use fake results, or have backend endpoints. Do not install an LLM SDK or add an OPENAI_API_KEY requirement until Phase 7 is explicitly started.

Phase 7 Classroom Starter

TaskFlow is intentionally complete as a traditional full-stack application before the AI lesson begins. Projects, tasks, Kanban workflow, memberships, dashboard metrics, and responsive views all work with the normal Django REST API.

The following controls are visually prepared but intentionally unimplemented:

• Generate Tasks
• Improve Description
• Suggest Priority
• Project Summary
• Generate Standup

Students will implement these capabilities during the OpenAI API lesson. This repository intentionally does not include the future solution, an AI provider, prompt code, provider SDK, mock results, or AI API routes.

Classroom distribution and instructor workflow

phase-7-starter is the immutable tag for the reusable pre-integration starter. Keep it unchanged for future cohorts. main is instructor-controlled; when the lesson begins, future implementation work can start on phase-7-ai-integration without altering the starter tag.

For distribution, prefer students generating their own repository from the GitHub template. If templates are not available, students should fork or clone the starter into their own repository. Students should not all push directly to the lecturer repository's main branch.

Verification commands

Run these checks after setup or before handing the project to a class:

# Backend
cd backend
source .venv/bin/activate
python manage.py makemigrations --check --dry-run
python manage.py migrate
python manage.py check
python manage.py test
python manage.py seed_demo
python manage.py seed_demo

# Frontend
cd ../frontend
npm run lint
npm test
npm run build

Architectural decisions

• A single Django REST API and React SPA keep full-stack concepts visible and approachable for students.
• Domain-based Django apps make the model easy to trace without introducing microservices.
• A custom user model is established before migrations to avoid a costly later migration.
• Project membership is explicit so authorization is correct and extensible from the first collaboration feature, while ownership remains the single source of truth.
• Tasks stay project-scoped in the API, so future Kanban views can group a single task list by its canonical status value.
• SQLite keeps local classroom setup simple; model and API design should remain portable to PostgreSQL later.
• Feature-based React organization scales the UI while preserving an easy mapping from user workflows to code.
• Activity history is server-generated to preserve trustworthy project history.

Recommended next task

GitHub repository and classroom starter preparation