Comprehensive resource management system built with Ballerina

A modular backend system for managing organizational resources including assets, meals, maintenance, users, and reporting with role-based access control and comprehensive analytics.

• Features
• Architecture
• Quick Start
• API Documentation
• Modules
• Configuration
• Development
• Deployment
• Contributing

• Asset Management - Complete asset lifecycle and allocation tracking
• User Management - Role-based user accounts and authentication
• Meal Services - Comprehensive meal planning and request system
• Maintenance - Facility maintenance request and tracking system
• Notifications - Real-time notification system for pending requests
• Organizations - Multi-tenant organization management
• Dashboard Analytics - Real-time system monitoring and reporting

• JWT Authentication - Secure token-based authentication
• Role-Based Access Control - Admin, SuperAdmin, User, Manager roles
• CORS Support - Cross-origin resource sharing configuration
• Data Privacy - Secure data handling and user privacy protection

• Automated Reports - Scheduled PDF report generation
• Email Distribution - Automatic report delivery
• Multi-Module Analytics - Comprehensive system insights
• Real-time Dashboards - Live system metrics and KPIs

graph TB
    A[Frontend Applications] --> B[ResourceHub Backend]
    B --> C[Authentication Module]
    B --> D[Asset Module]
    B --> E[User Module]
    B --> F[Meal Module]
    B --> G[Maintenance Module]
    B --> H[Dashboard Module]
    B --> I[Notification Module]
    B --> J[Report Module]
    B --> K[Organization Module]
    B --> L[Common Module]
    
    C --> M[Database Module]
    D --> M
    E --> M
    F --> M
    G --> M
    H --> M
    I --> M
    J --> M
    K --> M
    L --> M
    
    M --> N[MySQL Database]
    J --> O[Report Service :9091]
    H --> P[Dashboard Service :9092]
    I --> Q[Notification Service :9093]
    C --> R[Auth Service :9094]
    M --> S[Main Services :9090]

• Independent Modules - Each feature as a separate module
• Shared Dependencies - Common utilities and database access
• Scalable Architecture - Easy to extend and maintain
• RESTful APIs - Standard HTTP REST endpoints

• Ballerina 2201.12.0 or later
• MySQL 8.0 or later
• Java 17 or later

git clone https://github.com/FiveStackDev/Resource_Hub-Backend-.git
cd Resource_Hub-Backend-/Ballerina

-- Create database
CREATE DATABASE resourcehub;

-- Run SQL scripts (in order)
mysql -u username -p resourcehub < resources/sql/create_database.sql
mysql -u username -p resourcehub < resources/sql/create_tables.sql

Create Config.toml file in the project root:

# Database configuration
[ResourceHub.database]
USER = "your_db_user"
PASSWORD = "your_db_password" 
HOST = "localhost"
PORT = 3306
DATABASE = "resourcehub"

# SMTP server configuration
[ResourceHub.common]
SMTP_HOST = "smtp.gmail.com"
SMTP_USER = "your_email@gmail.com"
SMTP_PASSWORD = "your_app_password"

# API keys
[ResourceHub.report]
PDFSHIFT_API_KEY = "your_pdfshift_api_key"

# Run directly (recommended for development)
bal run

# Run with observability enabled
bal run --observability-included

# Build the project
bal build

# Run the built JAR file
java -jar target/bin/ResourceHub.jar

# Run with custom config file
bal run -Cconfig=path/to/your/Config.toml

The services will be available at:

• Main Services: http://localhost:9090
• Report Services: http://localhost:9091
• Dashboard Services: http://localhost:9092
• Notification Services: http://localhost:9093
• Auth Services: http://localhost:9094

# Test if services are running
curl http://localhost:9090/user
curl http://localhost:9094/auth
curl http://localhost:9092/dashboard/admin
curl http://localhost:9093/notification
curl http://localhost:9091/report

When running successfully, you should see:

Database connected successfully...
User management service started on port 9090
Account settings service started on port 9090
Auth service started on port 9094
Dashboard services started on port 9092
Notification service started on port 9093
Report service started on port 9091

All protected endpoints require JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

• 👤 User - Basic access to own data and resources
• 🛡️ Admin - Administrative access to most system functions
• 🚀 SuperAdmin - Full system access and configuration

# Database configuration
[ResourceHub.database]
USER = "username"           # Database username
PASSWORD = "password"       # Database password  
HOST = "localhost"          # Database host
PORT = 3306                 # Database port
DATABASE = "resourcehub"    # Database name

# SMTP server configuration
[ResourceHub.common]
SMTP_HOST = "smtp.gmail.com"        # SMTP server
SMTP_USER = "email@domain.com"      # Email username
SMTP_PASSWORD = "app_password"      # Email password

# API keys
[ResourceHub.report]
PDFSHIFT_API_KEY = "your_api_key"   # PDF generation service

Place SSL certificates in resources/certificates/:

• certificate.crt - Public certificate
• certificate.key - Private key
• certificate.csr - Certificate signing request

# Build the project
bal build

# Clean and build
bal clean && bal build

# Build with tests
bal build --with-tests

# Run with hot reload (development mode)
bal run --observability-included

# Generate documentation
bal doc

# Run tests
bal test

# Check for compilation errors
bal check

# Quick start (recommended for development)
bal run

# With observability and debugging enabled
bal run --observability-included

# 1. Build the application
bal build

# 2. Run the JAR file
java -jar target/bin/ResourceHub.jar

# Or run with custom config
java -jar target/bin/ResourceHub.jar -Cconfig=path/to/Config.toml

# Build Docker image
docker build -t resourcehub-backend .

# Run container
docker run -p 9090-9094:9090-9094 resourcehub-backend

ResourceHub-Backend/
├── 📄 Ballerina.toml          # Project configuration
├── 📄 Config.toml             # Runtime configuration (create this)
├── 📄 Dependencies.toml       # Dependency management (auto-generated)
├── 📄 main.bal               # Application entry point
├── 📁 modules/               # Feature modules
│   ├── 📁 asset/            # Asset management & requests
│   ├── 📁 auth/             # Authentication & JWT
│   ├── 📁 user/             # User management & settings
│   ├── 📁 meal/             # Meal services (types, times, calendar)
│   ├── 📁 maintenance/      # Maintenance request system
│   ├── 📁 notification/     # Real-time notifications
│   ├── 📁 dashboard/        # Analytics dashboard (admin & user)
│   ├── 📁 organizations/    # Organization settings
│   ├── 📁 report/           # Report generation & scheduling
│   ├── 📁 database/         # Database connectivity & listeners
│   └── 📁 common/           # Shared utilities & email service
├── 📁 resources/            # Static resources
│   ├── 📁 certificates/     # SSL certificates
│   └── 📁 sql/             # Database scripts
├── 📁 target/              # Build artifacts (generated)
│   ├── 📁 bin/             # Executable JAR files
│   └── 📁 cache/           # Build cache
└── 📁 tests/               # Test files

1. Create new module in modules/ directory
2. Define service endpoints and data models
3. Implement business logic
4. Add authentication and authorization
5. Update main.bal to include new service
6. Write comprehensive tests
7. Update documentation

FROM ballerina/ballerina:2201.12.0

COPY . /app
WORKDIR /app

RUN bal build
CMD ["java", "-jar", "target/bin/ResourceHub.jar"]

EXPOSE 9090 9091 9092 9093 9094

# Build Docker image
docker build -t resourcehub-backend .

# Run container
docker run -d -p 9090:9090 -p 9091:9091 -p 9092:9092 -p 9093:9093 -p 9094:9094 resourcehub-backend

# Run with volume for config
docker run -d -v $(pwd)/Config.toml:/app/Config.toml -p 9090-9094:9090-9094 resourcehub-backend

1. Environment Variables

   export RESOURCEHUB_USER="prod_user"
   export RESOURCEHUB_PASSWORD="secure_password"
   export RESOURCEHUB_HOST="db.production.com"

2. SSL Configuration

   • Use production SSL certificates
   • Configure HTTPS listeners
   • Enable security headers

3. Database

   • Use production MySQL instance
   • Configure connection pooling
   • Set up database backups

4. Monitoring

   • Enable Ballerina observability
   • Configure logging levels
   • Set up health checks

1. Fork the repository
2. Create a feature branch
3. Follow coding standards
4. Write comprehensive tests
5. Update documentation
6. Submit a pull request

• Follow Ballerina best practices
• Use meaningful variable names
• Write comprehensive comments
• Include error handling
• Maintain consistent formatting

# Run all tests
bal test

# Run specific module tests
bal test modules/asset

# Generate test coverage
bal test --code-coverage

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

FiveStackDev - Development Team

• GitHub: @FiveStackDev

• Minul Chathumal - @Minulck
• Theekshana Udara - @th33k
• Piumini Tishani - @PiuminiTishani
• Nethminiwelgama - @nethminiwelgama
• Sineth Nimhan - @SinethNimhan

# Check if MySQL is running
mysql -u username -p -e "SELECT 1"

# Verify database exists
mysql -u username -p -e "SHOW DATABASES LIKE 'resourcehub'"

# Test connection with config values
mysql -u <USER> -p<PASSWORD> -h <HOST> -P <PORT> <DATABASE>

# Check what's using the ports
netstat -tulpn | grep :909

# Kill processes using the ports (Linux/Mac)
sudo lsof -ti:9090 | xargs kill -9

# For Windows
netstat -ano | findstr :9090
taskkill /PID <PID> /F

# Clear cache and rebuild
bal clean
bal build

# Check Ballerina version
bal version

# Update dependencies
bal pull

• Ensure Config.toml is in the project root directory
• Verify all configuration sections are properly formatted
• Check that database credentials are correct
• Ensure SMTP settings are valid for email functionality

For support and questions:

• 📧 Email: minulck@gmail.com
• 📚 Documentation: Project Wiki
• 🐛 Issues: GitHub Issues