A full-stack, real-time, type-safe Task Management System built with a modern TypeScript monorepo architecture.
Developed as part of INTE 21323 β Web Application Development Group Project.
- Overview
- Live Demo
- Tech Stack
- Architecture & Request Flows
- Features
- Project Structure
- Prerequisites
- Setup & Installation
- Environment Variables
- Running the Application
- Docker Orchestration
- API Usage & Swagger Documentation
- Database Design
- Security Model
- Testing Suite
- CI/CD Pipeline
- Project Deliverables & Documentation
nexTask is a professional, full-stack, real-time task management platform designed for teams to plan, organize, track, and complete work collaboratively. It features secure Role-Based Access Control (RBAC), real-time WebSocket-driven notifications, a live project chat system, and cloud-based file attachments β all assembled inside a pnpm monorepo workspace with a fully type-safe TypeScript codebase shared across the frontend and backend.
- Shared Type Contracts via a
@nextask/typesworkspace package β ensuring zero duplication of schemas and interfaces between the client and server. - TSOA Integration to automatically generate OpenAPI/Swagger routing and documentation directly from controller TypeScript decorators.
- Prisma ORM with PostgreSQL for a strongly-typed, migrateable, and secure data access layer.
- Socket.IO for low-latency task updates, live chat, and push notifications.
- AWS S3 Presigned URLs allowing secure, direct-to-storage file uploads from the browser.
| Service | URL |
|---|---|
| Frontend Application | https://nextask.sasivarnasarma.me/login |
| Technology | Purpose |
|---|---|
| React 19 | UI library for building responsive interfaces |
| Vite 8 | Fast build tool and development server |
| TypeScript 6 | Type-safety and compilation checks |
| Tailwind CSS 4 | Utility-first CSS framework for clean, modern styling |
| Radix UI | Accessible, headless UI primitives (Dialog, Dropdown, ScrollArea) |
| TanStack React Query | Server state management, caching, and optimistic UI updates |
| Zustand | Lightweight client-side global state management |
| React Router 7 | Client-side routing with route protection guards |
| Axios | HTTP client with automatic JWT injection and error interceptors |
| Recharts | Interactive charting library for analytics dashboards |
| Lucide React | Clean and consistent modern vector icon set |
| @dnd-kit | Flexible drag-and-drop primitives for the Kanban board |
| Socket.IO Client | Real-time WebSocket connection to the server |
| Technology | Purpose |
|---|---|
| Node.js | JavaScript runtime environment |
| Express 5 | Web application framework for REST APIs |
| TypeScript 6 | Strong static typing for robust backend code |
| PostgreSQL | High-performance relational database |
| Prisma ORM | Type-safe database client and automated migration tool |
| TSOA | Controller-based routing and automatic Swagger/OpenAPI generation |
| Zod 4 | Runtime request body, query, and path parameter validation |
| JSON Web Tokens | Stateless, secure user authentication and authorization |
| Argon2 | Industry-standard password hashing algorithm |
| Socket.IO | WebSocket server for real-time notifications and chat messaging |
| Nodemailer | Transactional SMTP email delivery for onboarding and alerts |
| web-push | VAPID-based browser push notification delivery |
| AWS SDK (S3) | Secure S3-compatible cloud storage (AWS, R2, MinIO) via presigned URLs |
| Helmet | Security-related HTTP headers setup |
| Swagger UI Express | Embedded interactive API sandbox documentation |
| Technology | Purpose |
|---|---|
@nextask/types |
Monorepo-internal workspace package housing shared interfaces, enums, and validators |
| Technology | Purpose |
|---|---|
| pnpm Workspaces | High-performance monorepo dependency management |
| Docker & Docker Compose | Containerization and multi-service local environment orchestration |
| ESLint | Strict code linting and code quality checks |
| Prettier | Automated code formatter |
nexTask is built upon a clean, layered architecture ensuring strict separation of concerns across a modular monorepo.
Browser
β
β React UI Β· Zustand stores Β· React Query Β· Axios Interceptors
βΌ
Client API Layer βββββββββββββββββββββββββββββββ
β β
β HTTP REST Socket.IO β Web Push
βΌ βΌ βΌ
Express Server ββββ TSOA Routes ββββββββββββββββββββββ
β
βΌ
Controllers β Services β Prisma ORM β PostgreSQL
β
βββ MailService β SMTP Email
βββ S3Service β AWS S3 Bucket
βββ PushService β Web Push API
HTTP Request
β Express middleware (helmet, CORS, JSON parser)
β TSOA generated route mapping
β Authentication middleware (JWT decryption & RBAC check)
β Controller handler
β Service method (encapsulated business logic)
β Prisma query compilation
β PostgreSQL Database
β Standardized ApiResponse JSON
Business event (task assigned, status changed, comment added)
β NotificationService.createNotification()
β Writes Notification row to DB
β Emits Socket.IO event to target user's private socket room
β Triggers Web Push API for offline/unconnected users
| Feature | Description |
|---|---|
| Authentication & Onboarding | JWT-based auth with Argon2 password hashing, first-login forced password reset, and forgot-password email flow |
| Role-Based Access Control | Hybrid authorization with global roles (Admin/PM) and project-level membership roles |
| Project Management | Create, update, complete, archive, and delete projects with member management |
| Task Management | Full CRUD with priority levels (Low/Medium/High), status tracking (Todo/In Progress/Done), tags, and drag-and-drop positioning |
| Kanban Board | Interactive drag-and-drop board with real-time updates across connected clients |
| Multi-Assignee Tasks | Assign, unassign, and bulk-assign team members to tasks |
| Comments & Attachments | Threaded comment system with S3-based file upload/download (presigned URLs) |
| Real-Time Updates | Socket.IO integration with project-scoped rooms for live task/comment/assignment events |
| Email Notifications | SMTP-based templated HTML emails for onboarding, password resets, task assignments, and membership changes |
| Web Push Notifications | VAPID-based browser push notifications for task events |
| Admin Dashboard | User management, role assignment, user activation/deactivation, and audit activity logs |
| Analytics & Reporting | Project status charts, priority/status distribution metrics, and productivity insights |
| Search & Filtering | Full-text task search, filtering by status/priority/tags, and team member autocomplete |
| Calendar View | Visual calendar displaying tasks by due date |
| Validation | Dual-layer validation with Zod schemas (backend) and real-time form validation (frontend) |
- Secure email/password login using state-of-the-art Argon2 hashing.
- Stateless session management with dual-token JWT (Access Token & Refresh Token).
- Axios interceptors automatically inject access tokens and handle token refreshment or redirection upon expiry.
- First-login forced password reset ensuring newly onboarded users change temporary passwords.
- Secure, email-based password recovery flow (Forgot Password).
- Hybrid authorization model combining Global Roles (Admin, Project Manager, Collaborator) with Project-Specific Roles (Project Manager, Collaborator).
- Access control enforced at the controller layer via TSOA
@Securitydecorators and route guards on the frontend. - API endpoints respond with correct HTTP codes (
401 Unauthorizedor403 Forbidden) upon privilege violation.
- Dedicated Admin Dashboard to create, read, update, activate/deactivate, and delete users.
- New user onboarding via automated email containing their temporary password.
- Password complexity policy validation on both frontend and backend.
- Full system audit logs showing admin and user actions.
- Create, view, update, complete, archive, and delete projects.
- Manage project members and assign project-level roles dynamically.
- Full task CRUD (Title, Description, Assignees, Due Date, Priority, Status, Tags, Position).
- Multiple visual representations of tasks: Interactive Kanban Board, Filterable Data Table, and Due-Date Calendar.
- Fluid drag-and-drop card movement on the Kanban board (powered by
dnd-kit). - Task activity logs tracking history of modifications made to any given task.
- Project-scoped live chat rooms allowing team members to communicate in real-time.
- Socket.IO authenticated connections using JWTs.
- In-app notification panel displaying alerts for status changes, comments, and assignments.
- Integration with the browser's Web Push API allowing offline users to receive browser push notifications.
- S3-compatible cloud storage integration (AWS S3, Cloudflare R2, MinIO).
- Secure client-to-cloud file uploads via S3 Presigned URLs, preventing file streaming through the application server and optimizing backend performance.
- Attachment records tracked database-side and linked to tasks and chat messages.
nexTask/
βββ client/ # Frontend React application
β βββ public/ # Static assets (logo, icons, service worker)
β β βββ sw.js # Service worker for Web Push notifications
β βββ src/
β β βββ api/ # API client modules (one per resource)
β β β βββ client.ts # Axios instance with JWT & error interceptors
β β β βββ auth.api.ts # Login, reset password, forgot password
β β β βββ projects.api.ts # Project CRUD operations
β β β βββ tasks.api.ts # Task CRUD operations
β β β βββ comments.api.ts # Comment operations
β β β βββ attachments.api.ts # File upload/download
β β β βββ users.api.ts # User management (admin)
β β β βββ profile.api.ts # User profile operations
β β β βββ notifications.api.ts # Notification operations
β β β βββ messages.api.ts # Project chat messages
β β βββ components/ # Reusable UI components
β β β βββ auth/ # Authentication guards (RouteGuard)
β β β βββ tasks/ # Task views (Board, Table, Calendar)
β β β βββ ui/ # Base UI primitives (Button, Input, Toast, Dialog, etc.)
β β βββ hooks/ # Custom React hooks
β β β βββ usePasswordStrength.ts
β β β βββ useTheme.ts
β β β βββ useWebPush.ts
β β βββ lib/ # Utility functions
β β β βββ apiError.ts # API error message extraction
β β β βββ utils.ts # Class name utilities (cn)
β β βββ pages/ # Route-level page components
β β β βββ auth/ # Login, ForceReset, ForgotPassword, ResetPassword
β β β βββ admin/ # Admin dashboard, user management, reports
β β β βββ pm/ # Project Manager views (projects, tasks)
β β β βββ collaborator/ # Collaborator views (tasks, projects)
β β β βββ profile/ # User profile page
β β βββ store/ # Zustand state stores
β β β βββ auth.store.ts # Authentication state & JWT
β β β βββ project.store.ts # Active project context
β β β βββ toast.store.ts # Toast notification queue
β β βββ App.tsx # Root component with routing
β β βββ main.tsx # Application entry point
β β βββ index.css # Global styles & design tokens
β βββ index.html # HTML entry point
β βββ tailwind.config.js # Tailwind CSS configuration
β βββ vite.config.ts # Vite build configuration
β βββ package.json
β
βββ server/ # Backend Express API
β βββ prisma/
β β βββ schema.prisma # Database schema definition
β βββ src/
β β βββ controllers/ # TSOA route controllers (one per resource)
β β β βββ auth.controller.ts # Login, password reset, forgot password
β β β βββ project.controller.ts
β β β βββ project-member.controller.ts
β β β βββ task.controller.ts
β β β βββ task-assignment.controller.ts
β β β βββ comment.controller.ts
β β β βββ attachment.controller.ts
β β β βββ attachment-upload.controller.ts
β β β βββ user.controller.ts
β β β βββ notification.controller.ts
β β β βββ message.controller.ts
β β β βββ push.controller.ts
β β β βββ admin.controller.ts
β β β βββ system.controller.ts
β β βββ services/ # Business logic layer
β β β βββ auth.service.ts # Authentication & password management
β β β βββ project.service.ts
β β β βββ project-member.service.ts
β β β βββ task.service.ts
β β β βββ task-assignment.service.ts
β β β βββ comment.service.ts
β β β βββ attachment.service.ts
β β β βββ user.service.ts
β β β βββ notification.service.ts
β β β βββ message.service.ts
β β β βββ mail.service.ts # SMTP email delivery
β β β βββ push.service.ts # Web push notification delivery
β β β βββ s3.service.ts # S3-compatible object storage
β β β βββ permission.service.ts # RBAC permission checks
β β βββ schemas/ # Zod validation schemas
β β β βββ user.schema.ts
β β β βββ project.schema.ts
β β β βββ task.schema.ts
β β β βββ comment.schema.ts
β β β βββ attachment.schema.ts
β β β βββ membership.schema.ts
β β β βββ task-assignment.schema.ts
β β βββ middlewares/ # Express middleware
β β β βββ authentication.ts # JWT verification & RBAC scope checks
β β β βββ validate.middleware.ts # Zod request validation
β β βββ utils/ # Utility functions
β β β βββ apiError.util.ts # Custom ApiError class
β β β βββ response.util.ts # Standardized API response helpers
β β β βββ hash.util.ts # Argon2 password hashing
β β β βββ jwt.util.ts # JWT generation & verification
β β βββ lib/ # Core library modules
β β β βββ prisma.ts # Prisma client singleton
β β β βββ socket.ts # Socket.IO server & room management
β β βββ templates/ # HTML email templates
β β βββ scripts/ # Utility scripts
β β β βββ seed.ts # Database seeder (Admin, PM, Test users)
β β β βββ generate-vapid.ts # VAPID key pair generator
β β β βββ copy-templates.js # Build script for email templates
β β βββ index.ts # Server entry point & global error handler
β β βββ routes.ts # TSOA auto-generated routes
β β βββ swagger.json # TSOA auto-generated OpenAPI spec
β βββ tsoa.json # TSOA configuration
β βββ Dockerfile
β βββ package.json
β
βββ types/ # Shared TypeScript type definitions
β βββ index.ts # Interfaces, enums, API response wrappers
β
βββ _project-plan/ # Project planning documents
β βββ Project SRS.md # Software Requirements Specification
β βββ Project Tasks.md # Task distribution & roadmap
β βββ API Specification.md # API endpoint specification
β
βββ docker-compose.yml # Multi-service Docker orchestration
βββ pnpm-workspace.yaml # Monorepo workspace configuration
βββ package.json # Root scripts (dev, build, prod, lint, format)
βββ tsconfig.json # Root TypeScript configuration
βββ .prettierrc # Prettier formatting rules
βββ .editorconfig # Editor configuration
βββ CONTRIBUTING.md # Development & contribution guide
βββ README.md # Merged readme file
Before installing the application, ensure the following are installed:
- Node.js v18 or higher.
- pnpm (v8+) β install globally:
npm install -g pnpm. - PostgreSQL β running database instance (local, Docker container, or cloud database like Supabase).
- AWS S3-compatible bucket (for storing task and chat attachments).
- SMTP Credentials (Gmail App Password, Resend, Sendgrid, etc., for system emails).
git clone https://github.com/Sasivarnasarma/nexTask.git
cd nexTaskpnpm installCreate the server env file:
cp server/.env.sample server/.envOpen server/.env and edit with your custom settings (see the Environment Variables section below).
Tip: To generate your required VAPID keys for push notifications, run the key generator script:
pnpm --filter @nextask/server exec ts-node src/scripts/generate-vapid.ts
Create the client env file:
cp client/.env.sample client/.envEnsure the API endpoint points to your active backend instance:
VITE_API_URL="http://localhost:3000"Generate the Prisma client and push the migrations to your active database:
cd server
pnpm prisma generate
npx prisma db pushSeed the database with standard, out-of-the-box user accounts (Admin, PM, Collaborator):
# Run from the root directory
pnpm seed| Role | Temporary Password | |
|---|---|---|
| Admin | admin@example.com |
ChangeMe!123 |
| Project Manager | pm@example.com |
Password123! |
| Collaborator | test@example.com |
Temporary!1 |
Note: Seeded accounts are flagged with
mustResetPassword=trueand will trigger a forced password change upon their first successful login.
Create server/.env using the template below:
# Database Connection
DATABASE_URL="postgresql://username:password@localhost:5432/nextask?schema=public"
# Server Execution Config
PORT=3000
NODE_ENV="development"
CORS_ORIGIN="http://localhost:5173"
# JWT Auth Secrets
JWT_SECRET="your_jwt_access_secret_min_32_characters"
JWT_EXPIRES_IN="15m"
JWT_REFRESH_SECRET="your_jwt_refresh_secret_min_32_characters"
JWT_REFRESH_EXPIRES_IN="7d"
# SMTP Transactional Mail (Nodemailer)
SMTP_HOST="smtp.gmail.com"
SMTP_PORT=465
SMTP_USER="your-email@gmail.com"
SMTP_PASS="your-16-character-app-password"
SMTP_SECURE=true
MAIL_FROM="\"nexTask Notifications\" <your-email@gmail.com>"
# Frontend URL (for email links)
CLIENT_URL="http://localhost:5173"
# AWS S3 / Cloud Storage Config
AWS_REGION="us-east-1"
AWS_ACCESS_KEY_ID="your_aws_s3_access_key_id"
AWS_SECRET_ACCESS_KEY="your_aws_s3_secret_access_key"
S3_BUCKET_NAME="your-s3-bucket-name"
# VAPID Web Push Keys
VAPID_PUBLIC_KEY="your_generated_vapid_public_key"
VAPID_PRIVATE_KEY="your_generated_vapid_private_key"
VAPID_SUBJECT="mailto:your-email@gmail.com"All execution scripts should be run from the root directory of the monorepo.
Starts both the Vite frontend dev server and Express backend concurrently with hot-reloads:
pnpm dev- Frontend App: http://localhost:5173
- Backend API Server: http://localhost:3000
- Swagger Documentation Sandbox: http://localhost:3000/api-docs
Builds all packages and starts the production-ready build:
pnpm prod- Typecheck codebases:
pnpm typecheck - Lint files:
pnpm lint - Auto-format code:
pnpm format
The project uses a unified reverse-proxy Docker architecture. An outer Nginx container acts as the single public gateway on port 80, routing traffic internally to the isolated React frontend and Express API containers on a private bridge network.
# Build and launch the container stack locally
docker-compose up --build| Container | Service Name | Image Source (Production) / Context (Dev) | Exposed Port (Host) | Internal Port (Bridge) | Purpose |
|---|---|---|---|---|---|
nextask_nginx |
nginx |
nginx:alpine (local config) |
80:80 |
80 |
Reverse proxy gateway, SSL/HTTP router, and path dispatcher |
nextask_client |
client |
ghcr.io/sasivarnasarma/nextask-client:latest |
None | 80 |
Serves compiled React frontend static files via Nginx |
nextask_server |
server |
ghcr.io/sasivarnasarma/nextask-server:latest |
None | 3000 |
Exposes Express REST API and Socket.IO server |
- Frontend SPA: Routes
/to theclientcontainer on port80. - REST API: Routes
/api/to theservercontainer on port3000. - WebSockets: Routes
/socket.io/to theservercontainer on port3000, handling connection upgrades.
# Stop all containers
docker-compose down
# Stop and wipe PostgreSQL volumes
docker-compose down -vTSOA automatically generates the OpenAPI schema directly from the backend TypeScript controllers. The live, interactive Swagger UI sandbox is hosted at:
Every API endpoint responds using a unified JSON wrapper:
{
"success": true,
"message": "Operation completed successfully.",
"data": {
"id": "task-uuid",
"title": "Launch Website"
},
"errors": null
}When validation fails or an exception occurs, the response matches the following format:
{
"success": false,
"message": "Validation failed.",
"data": null,
"errors": {
"body.email": "Invalid email format.",
"body.password": "Password must be at least 8 characters."
}
}To query protected API endpoints, obtain a token via POST /auth/login and include it as a Bearer token in the request header:
Authorization: Bearer <your-jwt-token>| Group | Base Path | Description |
|---|---|---|
| Auth | /auth |
Handles logins, password resets, and forgot-password flows |
| Users | /users |
Profile updates, admin-level CRUD, and activity logs |
| Projects | /projects |
Project CRUD, members management, and status updates |
| Tasks | /tasks |
Task CRUD, Kanban drag-and-drop positions, and filtering |
| Comments | /tasks/:taskId/comments |
Task-specific comment threads |
| Attachments | /attachments |
Storage uploads, downloads, and presigned S3 URLs |
| Notifications | /notifications |
Query and mark in-app notifications as read |
| Messages | /messages |
Project-scoped live chat messaging |
| Push | /push |
VAPID push notification subscription registrations |
The relational PostgreSQL database is designed and maintained through Prisma.
| Table | Description |
|---|---|
User |
Houses user details, global system roles, and status fields. |
Project |
Represents top-level project containers. |
ProjectMember |
Many-to-many junction mapping users to projects with custom project-level roles. |
Task |
Individual task records belonging to projects. |
TaskAssignment |
Many-to-many junction mapping users to tasks. |
TaskActivity |
Read-only audit log capturing every edit, assignment, or movement of a task. |
Comment |
User comments left on tasks. |
Attachment |
S3 metadata records referencing uploaded files. |
Message |
Message records representing project-scoped chat. |
MessageAttachment |
S3 metadata records referencing files uploaded to chat. |
Notification |
System notifications pushed to users. |
PushSubscription |
Browser endpoints for Web Push notification delivery. |
The visual database schema is documented in ER_Diagram.png:
nexTask is built upon OWASP Top 10 security recommendations to prevent vulnerabilities:
| Threat Category | Mitigation Strategy |
|---|---|
| SQL Injection | Prisma ORM uses parameterized queries, neutralizing injection vectors. |
| XSS (Cross-Site Scripting) | Inputs are validated against Zod schemas and sanitized on both client and server. |
| Credential Hijacking | Argon2 password hashing; JWT tokens expire rapidly; forced reset on first login. |
| Sensitive Data Exposure | HTTPS enforced in production; WebSockets secure (WSS); secrets loaded via env variables. |
| Broken Access Control | Strictly guarded RBAC checks enforced via TSOA @Security and Express middlewares. |
| Security Misconfiguration | Helmet.js secures headers; custom, restricted CORS policies. |
| Insecure Dependencies | Strict dependency lockfiles; regular ESLint code audits. |
- Must contain at least 8 characters.
- Must contain at least one lowercase letter, one uppercase letter, one number, and one special character.
The testing suite contains:
- API Contract Testing: Verifies that JSON structures match types.
- Integration Testing: Confirms seamless flows across database, services, and controllers.
- Validation Suite: Asserts that Zod filters invalid schemas.
- Access Control Verification: Asserts that unauthorized roles are blocked.
- Real-Time Testing: Asserts that WebSocket connections and notifications function correctly.
Continuous Integration and Continuous Deployment (CI/CD) are fully automated using GitHub Actions, dividing deployment into two consecutive workflows:
Triggered automatically on a push to the main branch or manually via the GitHub Actions dashboard.
- Parallel Builds: Builds
clientandserverDocker containers concurrently using a matrix build strategy. - Container Registry: Publishes production-ready containers to GitHub Container Registry (
ghcr.io). - Image Tagging: Applies
latestand Git commit SHA (sha-<commit_hash>) tags for versioned rollbacks. - Build Caching: Leverages GitHub Actions cache backend (
cache-from/cache-towithtype=gha) to drastically speed up image layer construction. - Images Pushed:
ghcr.io/sasivarnasarma/nextask-client:latestghcr.io/sasivarnasarma/nextask-server:latest
Triggered automatically upon the successful completion of the Build and Publish workflow.
- SSH Deployment: Securely logs into the target AWS EC2 production host using repository SSH secrets.
- Production Pull: Fetches the pre-compiled images from GHCR using the dual compose file structure:
docker compose -f docker-compose.yml -f docker-compose.prod.yml pull
- Detached Launch: Launches the updated stack in detached mode with zero downtime:
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
- Resource Clean-up: Executes
docker image prune -afto delete dangling/unused build layers, preserving server storage.
All project deliverables and diagrams are organized across the repository:
| Deliverable | Location | Description |
|---|---|---|
| Source Code | /client, /server, /types |
Full-stack TypeScript monorepo source code |
| API Documentation (Swagger) | https://nextask.sasivarnasarma.me/api/api-docs/ | Live sandbox Swagger UI documentation |
| API Documentation (Offline) | /docs/api-documentation.md |
Complete endpoint and WebSocket events reference |
| ER Diagram & DB Design | /docs/database-design.md |
Database model schema, tables, indexes, and relations |
| Class Diagram | /docs/class-diagram.md |
UML class diagram of the backend system architecture |
| Deployment Diagram | /docs/deployment-diagram.md |
System deployment model, Docker configurations, security architecture |
| Prisma Schema | /server/prisma/schema.prisma |
Declarative Prisma schema model definitions |
| Project SRS | /_project-plan/Project SRS.md |
Software Requirements Specification document |
| API Specification Draft | /_project-plan/API Specification.md |
Pre-development endpoint design specification |
| Task Distribution Plan | /_project-plan/Project Tasks.md |
Project roadmap, phases, and task mapping |
| Contributing Guidelines | /CONTRIBUTING.md |
Development workflows and styling rules |
This project is developed solely for academic purposes as part of a web application development group project. All rights reserved.
