athletiqs

AthletiQ - Sports Management System

A comprehensive digital platform for managing sports participation, athlete verification, and inter-institutional sports coordination. AthletiQ streamlines the process of athlete registration, document verification, and participation card generation for educational institutions.

🏆 Features

For Sports Administrators

Athlete Verification: Review and verify participant registrations and documents
Institution Management: Oversee multiple institutions and their sports heads
Reports & Analytics: Generate comprehensive reports on participation and verification status
System Administration: Manage users, games, and system-wide settings
Activity Monitoring: Track all system activities and user actions

For Sports Heads (Institutional Level)

Participant Registration: Register athletes from their institution
Document Management: Upload and manage required athlete documents
Dashboard Overview: Monitor institution-specific statistics and pending verifications
Game Management: View and manage available sports/games
Institutional Reports: Generate reports for their specific institution

For Participants

Digital Participation Cards: Automatically generated upon verification
Document Upload: Submit required verification documents
Status Tracking: Monitor registration and verification progress

📸 Screenshots

Admin Dashboard

Admin Dashboard Main administrative interface showing system overview, user management, and key metrics

Sports Head Portal - Dashboard

Sports Head Dashboard Institution-specific dashboard with participant statistics and pending verifications

Participant Registration

Comprehensive participant registration form with document upload functionality

Document Management

Document Management Document upload and verification interface for participant documents

Reports & Analytics

Reports Dashboard Advanced reporting interface with charts and data visualization

Verification Status

Verification Status Real-time tracking of participant verification progress

User Management

User Management Administrative interface for managing sports heads and system users

🏗️ System Architecture

Applications

Admin Dashboard (Port 5174): For sports administrators and system admins
Sports Head Portal (Port 5173): For institutional sports heads
Backend API (Port 5000): RESTful API server

User Roles

System Admin: Full system access and configuration
Sports Admin: Athlete verification, reports, and institutional oversight
Sports Head: Institution-specific participant management

🚀 Quick Start

Prerequisites

Node.js (v18 or higher)
MongoDB
Git

Installation

Clone the repository

git clone https://gitlab.com/mactimothy07/athletiq.git
cd athletiq

Install dependencies

# Install root dependencies
npm install

# Install backend dependencies
cd backend
npm install

# Install admin dashboard dependencies
cd ../admin
npm install

# Install sports head portal dependencies
cd ../frontend
npm install

Environment Setup

Create a .env file in the backend directory:

PORT=5000
MONGODB_URI=your_mongodb_connection_string
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRES_IN=1d
SESSION_SECRET=your_session_secret
   
# Cloudinary Configuration
CLOUDINARY_CLOUD_NAME=your_cloudinary_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret
   
# Email Configuration
EMAIL_USER=your_email@gmail.com
EMAIL_PASS=your_app_password
EMAIL_FROM=noreply@athletiq.com
FRONTEND_URL=http://localhost:5173

Start the application

Terminal 1 - Backend Server:
```
cd backend
npm start
```
Terminal 2 - Admin Dashboard:
```
cd admin
npm run dev
```
Terminal 3 - Sports Head Portal:
```
cd frontend
npm run dev
```

Sports Administrator Access

Email: codestorm.devi@gmail.com
Password: @Test2024
Access URL: http://localhost:5174
Permissions: Full system administration, athlete verification, reports generation

Note: Change these credentials after first login for security purposes.

📱 Application Access

User Type	Application	URL	Description
Sports Admin/System Admin	Admin Dashboard	http://localhost:5174	Full administrative interface
Sports Head	Sports Portal	http://localhost:5173	Institution-specific management
API	Backend Server	http://localhost:5000	RESTful API endpoints

🛠️ Technology Stack

Frontend

React 18 with TypeScript
Vite for build tooling
Tailwind CSS for styling
React Router for navigation
Axios for API communication
React Hook Form for form management

Backend

Node.js with Express.js
MongoDB with Mongoose ODM
JWT for authentication
Cloudinary for file storage
Nodemailer for email services
bcrypt for password hashing

Features

Email Verification system
Two-Factor Authentication (2FA)
Activity Logging and audit trails
File Upload with Cloudinary integration
Real-time Notifications
Responsive Design for all devices

📖 API Documentation

Authentication Endpoints

POST /api/auth/register          - User registration
POST /api/auth/login            - User login
POST /api/auth/verify-email     - Email verification
POST /api/auth/forgot-password  - Password reset request
POST /api/auth/reset-password   - Password reset

Admin Endpoints

GET  /api/admin/users           - List all users
GET  /api/admin/sports-heads    - List sports heads
POST /api/admin/verify-participant/:id - Verify participant
GET  /api/admin/dashboard-stats - Dashboard statistics
GET  /api/admin/reports         - Generate reports

Participant Management

GET  /api/participants          - List participants
POST /api/participants          - Create participant
GET  /api/participants/:id      - Get participant details
PUT  /api/participants/:id      - Update participant
DELETE /api/participants/:id    - Delete participant

🗄️ Database Schema

Core Collections

Users: System users (admins, sports heads)
Participants: Registered athletes
Institutions: Educational institutions
Games: Available sports/games
Documents: Uploaded verification documents
ParticipationCards: Generated athlete cards
ActivityLogs: System activity tracking
Notifications: User notifications

🔧 Development

Project Structure

athletiq/
├── backend/           # Node.js API server
│   ├── controllers/   # Request handlers
│   ├── models/        # Database models
│   ├── routes/        # API routes
│   ├── middleware/    # Custom middleware
│   └── utils/         # Utility functions
├── admin/             # Admin dashboard (React)
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── contexts/
│   │   └── services/
├── frontend/          # Sports head portal (React)
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   └── services/
└── README.md

Development Commands

# Backend development
cd backend && npm run dev

# Admin dashboard development
cd admin && npm run dev

# Sports portal development
cd frontend && npm run dev

# Build for production
npm run build

# Run tests
npm test

🚀 Deployment

Environment Variables (Production)

Ensure all environment variables are properly configured for production:

Database connection strings
JWT secrets (use strong, unique keys)
Email service credentials
Cloudinary configuration
Frontend URLs

Build Commands

# Build admin dashboard
cd admin && npm run build

# Build sports portal
cd frontend && npm run build

# Start production backend
cd backend && npm start

🤝 Contributing

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

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Authors

Development Team - Initial work and ongoing development

📞 Support

For support and questions:

Create an issue on GitLab
Contact the development team
Check the documentation

🗺️ Roadmap

Mobile application development
Advanced analytics dashboard
Integration with external sports databases
Multi-language support
Enhanced reporting features
API rate limiting and caching

AthletiQ - Streamlining sports management for educational institutions.