📊 ProjectFlow - Project Management Application

A full-stack application with Spring AI, Real-time Notification System, Data Engineering pipeline (Kafka + Spring Batch), real-time analytics, team collaboration, OAuth2 (Google/GitHub login), and task tracking.

Built with Spring Boot 3.2.0 and React 18 + TypeScript

Author

Mahmoud Najmeh

---

📋 Table of Contents

• 🏗️ Project Architecture
• 🖥️ System Architecture Diagram
• 🗄️ Database Structure
• 🔐 Authentication Flow Diagram
• 📡 Real-time Pipeline Diagram
• ✨ Features
• 🛠️ Tech Stack
• 📁 Project Structure
• 🚀 Quick Start
• 📡 API Endpoints
• 🐳 Docker Deployment
• 🤝 Contributing

---

🏗️ Project Architecture

Diagram shows the overall architecture of the ProjectFlow application including frontend, backend, database, and external services.

---

🖥️ System Architecture Diagram

Complete system architecture showing all components and their interactions.

---

🗄️ Database Structure

Complete database schema showing all tables and their relationships.

Entity Relationship Diagram

---

Database Tables Detail

Detailed view of all database tables with column names and data types.

---

🔐 Authentication Flow Diagram

Sequence diagram showing the complete authentication process including login, registration, and password reset.

---

📡 Real-time Pipeline Diagram

Event-driven architecture showing Kafka pipeline for real-time metrics processing.

---

Event Flow Description

Step	Component	Description
1	ActivityEventPublisher	Captures user actions (task creation, completion, login)
2	Kafka Producer	Serializes events and sends to Kafka topic
3	Kafka Broker	Stores events partitioned by user_id for scalability
4	Kafka Consumer	Consumes events in real-time from project-metrics-group
5	RealTimeMetricsService	Updates in-memory counters (tasks created/completed today)
6	WebSocket Push	Pushes real-time updates to connected clients
7	Metrics Scheduler	Triggers daily batch job at 1 AM
8	Spring Batch	Calculates and stores daily metrics in database

---

✨ Features

🤖 Spring AI Integration (⭐ Core Focus)

• AI-powered assistant for project management
• Intelligent task recommendations
• Automated responses and smart suggestions

📊 Data Engineering & Analytics (⭐ Core Focus)

• Apache Kafka Event Streaming - Real-time capture and processing of user activities
• Spring Batch Processing - Daily metrics calculation and trend analysis
• Real-time Metrics Dashboard - Live task completion rates and team velocity
• User Activity Pipeline - Event-driven architecture for performance tracking

🔔 Real-time Notification System (⭐ Core Focus)

• WebSocket-based notifications - Instant alerts for task assignments and project updates
• Database-persisted notifications - Never miss important updates
• Unread count tracking - Bell icon with badge showing pending notifications
• Read/Unread status - Mark notifications as read individually or all at once
• Entity-based notifications - Click to navigate directly to tasks, projects, or calendar events
• Real-time WebSocket push - No page refresh needed for new notifications
• Notification types: TASK_ASSIGNED, TASK_COMPLETED, PROJECT_CREATED, MESSAGE_RECEIVED, CALENDAR_EVENT

🔐 Authentication & Security

• JWT-based authentication with refresh tokens
• OAuth2 Integration (Google + GitHub) - Single sign-on with social providers
• Password reset via email
• Role-based access control (USER, ADMIN)

👥 Team Collaboration

• Create and manage teams
• Add/remove team members
• Team profile pictures
• Real-time team chat with WebSocket

📋 Project Management

• Create, update, delete projects
• Project status tracking (PLANNED, IN_PROGRESS, COMPLETED)
• Assign projects to teams
• Project-level task organization

✅ Task Tracking

• Task assignment with priorities (HIGH, MEDIUM, LOW)
• Due date tracking
• Task status (TODO, IN_PROGRESS, DONE)
• Real-time task updates via WebSocket

📅 Calendar Integration

• Visual timeline of tasks and events
• Drag-and-drop event creation
• Color-coded event types

📈 Analytics & Reporting

• Real-time metrics dashboard
• Kafka event streaming for user activities
• Spring Batch daily metrics calculation
• Team velocity and productivity scores

💬 Real-time Features

• WebSocket chat between team members
• Live notifications for task assignments
• Activity feed
• Unread message indicators

🎨 UI/UX

• Dark/Light mode toggle
• Fully responsive design
• Profile picture upload
• Global search (projects, tasks, teams, users)
• Toast notifications

---

🛠️ Tech Stack

Backend

Technology	Version	Purpose
Spring Boot	3.2.0	Core framework
Spring Security	6.2.0	Authentication & authorization
Spring Data JPA	3.2.0	Database ORM
Spring WebSocket	3.2.0	Real-time communication
Spring Kafka	3.1.0	Event streaming
Spring Batch	5.1.0	Batch processing
MySQL	8.0+	Relational database
JWT	0.11.5	Token-based authentication
Lombok	1.18.30	Boilerplate reduction

Frontend

Technology	Version	Purpose
React	18.3.1	UI framework
TypeScript	5.6.2	Type safety
Tailwind CSS	3.4.17	Styling
React Router DOM	6.28.0	Routing
React Hook Form	7.54.2	Form management
Zod	3.24.1	Validation
Axios	1.7.9	HTTP client
STOMPjs	2.3.3	WebSocket protocol
SockJS-client	1.5.1	WebSocket fallback
Lucide React	0.468.0	Icons
Vite	5.4.11	Build tool

DevOps

• Docker & Docker Compose
• GitHub Actions / GitLab CI
• Jenkins pipeline

---

📁 Project Structure

project-management-app/
│
├── backend/
│   ├── src/main/java/.../project_management_app/
│   │   ├── config/           # Security, WebSocket, Kafka config
│   │   ├── controller/       # REST API controllers
│   │   ├── dto/              # Data Transfer Objects
│   │   ├── entity/           # JPA entities
│   │   ├── pipeline/         # Kafka event pipeline
│   │   │   ├── event/        # Event publishers
│   │   │   ├── kafka/        # Producers & Consumers
│   │   │   ├── model/        # Event models
│   │   │   └── scheduler/    # Batch job scheduler
│   │   ├── repository/       # JPA repositories
│   │   ├── service/          # Business logic
│   │   └── util/             # Utilities (JWT)
│   ├── src/main/resources/
│   │   └── application.properties
│   ├── uploads/              # File storage
│   │   ├── chat/
│   │   ├── profile-pictures/
│   │   └── team-photos/
│   └── pom.xml
│
├── frontend/
│   ├── src/
│   │   ├── api/              # API service layer
│   │   ├── assets/           # Static assets
│   │   ├── components/       # React components
│   │   │   ├── ai/           # AI Assistant
│   │   │   ├── auth/         # Login/Register
│   │   │   ├── calendar/     # Calendar
│   │   │   ├── common/       # Reusable UI
│   │   │   ├── dashboard/    # Dashboard
│   │   │   ├── layout/       # Layout, Header
│   │   │   ├── profile/      # Profile settings
│   │   │   ├── projects/     # Projects
│   │   │   ├── tasks/        # Tasks
│   │   │   └── team/         # Team & chat
│   │   ├── context/          # React Context
│   │   ├── hooks/            # Custom hooks
│   │   ├── pages/            # Page components
│   │   ├── styles/           # Global styles
│   │   ├── types/            # TypeScript definitions
│   │   ├── utils/            # Helper functions
│   │   ├── App.tsx
│   │   └── main.tsx
│   ├── public/
│   ├── .env
│   ├── package.json
│   ├── tailwind.config.js
│   ├── tsconfig.json
│   └── vite.config.ts
│
├── .github/workflows/
├── docker-compose.yml
├── Dockerfile
└── README.md

---

🚀 Quick Start

Prerequisites

• Java 21+
• Node.js 18+
• MySQL 8.0+
• Maven 3.8+

1. Clone & Setup Backend

git clone https://github.com/mahmoudnajmeh/project-management-app.git
cd project-management-app

mysql -u root -p
CREATE DATABASE project_management_app;

2. Configure application.properties

spring.datasource.url=jdbc:mysql://localhost:3306/project_management_app
spring.datasource.username=root
spring.datasource.password=yourpassword
jwt.secret=your_jwt_secret_key_here

3. Run Backend

mvn clean install
mvn spring-boot:run

# Backend: http://localhost:8080

4. Run Frontend

cd frontend
npm install
npm run dev

# Frontend: http://localhost:3000

---

📡 API Endpoints

Category	Method	Endpoint	Description
Auth	POST	/api/auth/login	User login
Auth	POST	/api/auth/register	User registration
Auth	POST	/api/auth/forgot-password	Request password reset
Auth	POST	/api/auth/reset-password	Reset password
Users	GET	/api/users/me	Get current user
Users	PUT	/api/users/me	Update profile
Users	POST	/api/users/me/profile-picture	Upload avatar
Users	POST	/api/users/me/change-password	Change password
Teams	GET	/api/teams/my-teams	Get my teams
Teams	POST	/api/teams	Create team
Teams	GET	/api/teams/{id}/members	Get team members
Projects	GET	/api/projects/my-projects	Get my projects
Projects	POST	/api/projects	Create project
Tasks	GET	/api/tasks/my-tasks	Get my tasks
Tasks	POST	/api/tasks	Create task
Search	GET	/api/search?q={query}	Global search

---

🐳 Docker Deployment

# Build and run
docker-compose up -d

# Stop containers
docker-compose down

# View logs
docker-compose logs -f

---

📄 Image Placeholders Reference

When adding your images to the documentation, use these exact filenames:

Placeholder	Description	Recommended Content
./project-architecture.png	Project Architecture Diagram	High-level architecture overview
./system-architecture.png	System Architecture Diagram	Detailed component interaction
./database-structure.png	Database Structure	Complete database schema
./database-tables-detail.png	Database Tables Detail	All tables with columns
./authentication-flow.png	Authentication Flow Diagram	Login/register/password reset sequence
./realtime-pipeline.png	Real-time Pipeline Diagram	Kafka event flow diagram

---

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push branch (git push origin feature/amazing)
5. Open Pull Request

---

📄 License

This project is licensed under the MIT License.

---

Built with ❤️ using Spring Boot, React, and TypeScript