Unified-Development-2/README.md

UD2 Project

A multi-module IntelliJ IDEA project that manages several interconnected applications including a Java web server, frontend dashboards, and database management tools.

Quick Start

Prerequisites

• IntelliJ IDEA (Community or Ultimate Edition)
• Java Development Kit (JDK 24 or compatible)
• Node.js (for frontend development)
• Maven (for Java project management)
• Git (for version control)

Getting Started

1. Clone the repository:

   git clone <repository-url>
   cd UD2
   

2. Open in IntelliJ IDEA:

   • Launch IntelliJ IDEA
   • Select "Open" from the welcome screen
   • Navigate to the UD2 directory
   • Select the UD2.iml file or the entire UD2 folder
   • Click "OK"

3. Configure Project Settings:

   • IntelliJ will automatically detect the project structure
   • Ensure the correct JDK is selected (JDK 24 recommended)
   • Maven dependencies will be automatically resolved

4. Set up the development environment:

   • Ensure all parent directories (../Kof22/, ../QRun-IO/) exist
   • Run the ServerAndFrontend configuration to start development

Repository Structure

This git repository serves as a coordination point for multiple related applications:

UD2/
├── README.md              # This file
├── UD2.iml               # IntelliJ IDEA project file
└── log/                  # Log files
    └── qqq.log

Related Projects

The UD2 project coordinates with several external applications:

• Kof22 Website: Java-based web server (../Kof22/Website/)
• QQQ Frontend Dashboard: React-based frontend (../QRun-IO/qqq-frontend-material-dashboard/)
• QQQ Backend: Java middleware (../QRun-IO/qqq/)

Note

: These external projects should be located in the parent directories as shown above for the IntelliJ run configurations to work properly.

Run Configurations

The project includes several pre-configured run targets accessible through the IntelliJ run configuration dropdown:

Java Application Configurations

ServerOnly

• Purpose: Runs only the Java web server
• Environment: Development mode (QQQ_DEPLOYMENT=dev)
• Main Class: com.kof22.website.Server
• Working Directory: ../Kof22/Website
• Access URL: http://localhost:8000/admin/

ServerAndFrontend

• Purpose: Runs both server and frontend with automatic browser launch
• Environment: Development mode
• Prerequisites:
  • Kills existing Chrome processes
  • Builds frontend assets before server start
• Access URL: http://localhost:8000/admin/
• JDK: OpenJDK 24

Frontend Development Configurations

FrontDev

• Purpose: Frontend development server with hot reload
• Type: NPM script runner
• Script: dev
• Access URL: http://localhost:5173
• Features: Auto-opens browser with debugger

Start QQQ Dashboard

• Purpose: Starts the QQQ Material Dashboard
• Type: NPM script runner
• Script: start
• Access URL: http://localhost:3000/

Build and Deployment Configurations

clean-and-install

• Purpose: Cleans and installs frontend dependencies
• Type: NPM script runner
• Script: clean-and-install

build-and-publish

• Purpose: Builds and publishes frontend assets
• Type: NPM script runner
• Script: build-and-publish

qqq-install-locally

• Purpose: Maven clean, package, and install for QQQ backend
• Type: Maven configuration
• Goals: clean package install -Dmaven.test.skip=true
• Working Directory: ../QRun-IO/qqq

Database Management Configurations

dbupdate

• Purpose: Updates database schema using Liquibase
• Type: Maven configuration
• Goals: liquibase:update -Dliquibase.contexts=dev
• Working Directory: ../Kof22/Website

dbdropAndUpdate

• Purpose: Drops and recreates database schema
• Type: Maven configuration

dbdropall

• Purpose: Drops all database tables
• Type: Maven configuration

Utility Configurations

Kill Chrome

• Purpose: Terminates all Chrome browser processes
• Type: Shell script

Generate QQQ API (openapi.json)

• Purpose: Generates OpenAPI specification
• Type: Shell script

Usage Instructions

Development Workflow

1. Start Development Environment:

   • Run ServerAndFrontend for full-stack development
   • Or run ServerOnly + FrontDev separately for more control

2. Frontend Development:

   • Use FrontDev for hot-reload development
   • Use Start QQQ Dashboard for the Material Dashboard

3. Database Management:

   • Run dbupdate to apply schema changes
   • Use dbdropAndUpdate for fresh database setup

4. Build and Deploy:

   • Run qqq-install-locally to build backend
   • Use build-and-publish for frontend deployment

Running Configurations

1. Via IntelliJ UI:

   • Click the run configuration dropdown in the toolbar
   • Select desired configuration
   • Click the green "Run" button or press Ctrl+F10 (Windows/Linux) / Cmd+R (Mac)

2. Via Run Menu:

   • Go to Run → Edit Configurations...
   • Select and modify configurations as needed
   • Use Run → Run '[Configuration Name]'

Environment Variables

• QQQ_DEPLOYMENT: Set to dev for development mode
• QFMD_APP_BASE_PATH: Set to /admin for application base path

Git Workflow

Branch Management

• develop: Main development branch
• main: Production-ready releases
• Feature branches: Create from develop for new features

Common Git Commands

# Check status
git status

# Switch to develop branch
git checkout develop

# Pull latest changes
git pull origin develop

# Create a new feature branch
git checkout -b feature/your-feature-name

# Commit changes
git add .
git commit -m "Your commit message"

# Push changes
git push origin your-branch-name

Troubleshooting

Project Setup Issues

• Module not found: Ensure all parent directories (../Kof22/, ../QRun-IO/) exist
• JDK issues: Verify JDK 24 is installed and selected in project settings
• Maven issues: Check Maven settings and ensure all dependencies are resolved
• Node.js issues: Verify Node.js is installed and accessible from IntelliJ

Git Issues

• Repository not found: Ensure you've cloned the repository correctly
• Permission denied: Check your git credentials and repository access
• Merge conflicts: Resolve conflicts in IntelliJ or use git status to identify conflicted files

Contributing

1. Fork the repository (if you don't have write access)
2. Create a feature branch from develop
3. Make your changes and test thoroughly
4. Commit your changes with descriptive messages
5. Push to your branch and create a pull request
6. Request review from team members

Commit Message Guidelines

• Use clear, descriptive commit messages
• Start with a verb in imperative mood (e.g., "Add", "Fix", "Update")
• Include context when necessary
• Keep the first line under 50 characters

Additional Notes

• The project uses Maven for Java dependency management
• Frontend projects use npm for package management
• Database migrations are handled by Liquibase
• The project supports both development and production configurations
• This repository serves as a coordination point for multiple related projects