Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

56 Commits
.github/workflows
.github/workflows
 
 
api
api
 
 
client
client
 
 
docker
docker
 
 
docs
docs
 
 
server
server
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
pom.xml
pom.xml
 
 

Repository files navigation

Personal MicroManager

A comprehensive multi-module Maven project for personal task and project management, featuring a modern Angular frontend, Spring Boot backend, and extensive external service integrations.

📋 Table of Contents

🎯 Project Overview

Personal MicroManager is a full-stack application designed for comprehensive project and task management. It integrates with popular development tools and provides a unified dashboard for monitoring project health, code quality, and development progress.

Key Capabilities

  • Unified Dashboard: Centralized view of all project metrics and status
  • External Integrations: Seamless integration with Bitbucket, Jenkins, Jira, and SonarQube
  • Real-time Monitoring: Live updates of build status, code quality, and project metrics
  • User Authentication: Secure JWT-based authentication system
  • Responsive Design: Modern UI built with Angular and Tabler UI

✨ Features

Core Features

  • Authentication & Authorization

    • JWT-based authentication with Spring Security
    • Role-based access control
    • Secure session management
    • Password encryption and validation

  • External Service Integrations

    • Bitbucket: Repository management, pull request tracking, code review status
    • Jenkins: Build pipeline monitoring, job status, deployment tracking
    • Jira: Task management, issue tracking, project planning
    • SonarQube: Code quality metrics, technical debt analysis, security hotspots

  • Data Management

    • PostgreSQL database with automatic schema updates
    • Data persistence and caching strategies
    • Backup and recovery procedures
    • Data validation and sanitization
    • Auto-Sync Service: Automatic data synchronization from JSON files on application startup

Technical Features

  • API-First Design: RESTful APIs with OpenAPI 3.0 specifications
  • Code Generation: Automatic client code generation from OpenAPI specs
  • Containerization: Docker support for all components
  • Development Tools: Hot reload, debugging support, comprehensive logging

Auto-Sync Service

The application includes an intelligent auto-sync service that automatically loads demo data from JSON files into the database when the server starts. This ensures that:

  • Demo Data Availability: All sample data is immediately available for testing and demonstration
  • Consistent State: Database is always in a known, consistent state on startup
  • Configurable Behavior: Sync behavior can be controlled through application properties
  • Error Handling: Robust error handling with configurable retry mechanisms
  • Service Orchestration: Centralized coordination of all sync operations
  • Performance Optimization: Sequential execution with configurable service order

Sync Service Configuration

# Sync Service Configuration
sync.enabled=true                    # Enable/disable sync service globally
sync.startup-enabled=true            # Enable sync on application startup
sync.retry.max-attempts=3           # Maximum retry attempts for failed operations
sync.retry.delay-ms=1000            # Delay between retry attempts
sync.order=bitbucket,jenkins,jira,sonarqube  # Execution order of services
sync.continue-on-error=false        # Whether to continue if one service fails

Supported Services

  • Bitbucket: Pull requests, user data, repository information
  • Jenkins: Build jobs, build history, pipeline status
  • Jira: Issues, tasks, projects, feature requests
  • SonarQube: Code quality metrics, component analysis

🛠 Technology Stack

Backend

Frontend

Development Tools

Version Compatibility Matrix

Component Version Status Notes
Spring Boot 3.5.3 ✅ Supported Latest stable release
Java 21 ✅ Required Minimum supported version
Angular 18.2.10 ✅ Supported Latest LTS version
PostgreSQL 15+ ✅ Supported Tested with 15.x
Docker 24.0+ ✅ Recommended For containerized deployment

🏗 Architecture

Project Structure

personal-micromanager/
├── client/                    # Angular 18.2.10 frontend
│   ├── src/
│   │   ├── app/              # Application components
│   │   ├── assets/           # Static assets
│   │   └── environments/     # Environment configurations
│   ├── angular.json          # Angular CLI configuration
│   └── package.json          # Frontend dependencies
├── server/                    # Spring Boot 3.5.3 backend
│   ├── src/main/java/        # Java source code
│   ├── src/main/resources/   # Configuration files
│   └── pom.xml              # Backend dependencies
├── api/                       # Shared Java module
│   ├── src/main/openapi/     # OpenAPI specifications
│   └── pom.xml              # API module dependencies
├── docker/                    # Docker configuration
│   ├── docker-compose.yml    # Multi-service orchestration
│   └── Dockerfile           # Container definitions
└── pom.xml                   # Maven parent POM

System Architecture

  • Frontend Layer: Angular SPA with Tabler UI
  • API Gateway: Spring Boot REST API with security
  • Service Layer: Business logic and external integrations
  • Data Layer: PostgreSQL with JPA/Hibernate
  • Integration Layer: External service connectors

🚀 Getting Started

Prerequisites

Required Software

Windows-Specific Requirements

  • Docker Desktop: Download from Docker
  • Chocolatey (optional): For easy package management 
    # Install Java and Maven via Chocolatey
choco install openjdk21
choco install maven

Installation Steps

1. Clone the Repository

git clone https://github.com/your-username/personal-micromanager.git
cd personal-micromanager

2. Verify Prerequisites

# Check Java version
java -version

# Check Maven version
mvn -version

# Check Node.js version
node --version

# Check pnpm version
pnpm --version

# Check Docker version
docker --version

3. Build the Project

# Build all modules
mvn clean install

# Build frontend dependencies
cd client
pnpm install
cd ..

🔧 Development Workflow

Use Case 1: Local Development (IDE)

For development with server running from your IDE:

  1. Start Infrastructure Services:

    cd docker
docker-compose --profile local-dev up -d

  2. Configure IDE:

    • Open the project in your IDE (IntelliJ IDEA, Eclipse, VS Code)
    • Import as Maven project
    • Set Java 21 as project SDK
    • Configure run configuration for PersonalMicromanagerApplication

  3. Run the Application:

    • Start PersonalMicromanagerApplication from your IDE
    • Server will connect to PostgreSQL on localhost:5432

  4. Start Frontend (Optional):

    cd client
pnpm start

  5. Access Services:

Use Case 2: Production Deployment

For production with containerized server:

  1. Build Production Artifacts:

    # Build server JAR
cd server
mvn clean package -DskipTests
cd ..

# Build frontend
cd client
pnpm build
cd ..

  2. Deploy with Docker:

    cd docker
docker-compose --profile production up -d

  3. Verify Deployment:

Use Case 3: Debug Environment

For debugging with all services containerized:

  1. Build Debug Version:

    cd server
mvn clean package -DskipTests
cd ..

  2. Start Debug Environment:

    cd docker
docker-compose --profile debug up -d

  3. Access Debug Tools:

⚙️ Configuration

Backend Configuration

Database Configuration (application.properties)

# Database Configuration
spring.datasource.url=jdbc:postgresql://localhost:5432/micromanager
spring.datasource.username=micromanager
spring.datasource.password=micromanager123
spring.datasource.driver-class-name=org.postgresql.Driver

# JPA Configuration
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=false
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

# Server Configuration
server.port=3001
server.servlet.context-path=/api

# Security Configuration
jwt.secret=your-jwt-secret-key
jwt.expiration=86400000

# External Service Configuration
bitbucket.api.url=https://api.bitbucket.org/2.0
jenkins.api.url=http://your-jenkins-server
jira.api.url=https://your-domain.atlassian.net
sonarqube.api.url=http://your-sonarqube-server

Environment Variables

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=micromanager
DB_USERNAME=micromanager
DB_PASSWORD=micromanager123

# JWT
JWT_SECRET=your-secure-jwt-secret
JWT_EXPIRATION=86400000

# External Services
BITBUCKET_API_URL=https://api.bitbucket.org/2.0
JENKINS_API_URL=http://your-jenkins-server
JIRA_API_URL=https://your-domain.atlassian.net
SONARQUBE_API_URL=http://your-sonarqube-server

Frontend Configuration

Angular Configuration (angular.json)

{
  "projects": {
    "personal-micromanager": {
      "architect": {
        "build": {
          "options": {
            "outputPath": "dist/personal-micromanager",
            "index": "src/index.html",
            "main": "src/main.ts",
            "polyfills": "src/polyfills.ts",
            "tsConfig": "tsconfig.app.json",
            "assets": ["src/favicon.png", "src/assets"],
            "styles": ["src/styles.scss"],
            "scripts": []
          }
        }
      }
    }
  }
}

Proxy Configuration (proxy.conf.json)

{
  "/api": {
    "target": "http://localhost:3001",
    "secure": false,
    "changeOrigin": true,
    "logLevel": "debug"
  }
}

NPM/Yarn/PNPM Scripts

The following scripts are available in the client/package.json:

  • ng: Runs the Angular CLI using pnpm.
  • start: Starts the Angular development server.
  • build: Builds the Angular application for production.
  • watch: Builds the Angular app in watch mode for development.
  • test: Runs unit tests in headless Chrome.
  • generate:api: Generates TypeScript API client code from OpenAPI specs (all APIs).
  • generate:all: Generates all TypeScript API clients (alias for generate:api).
  • generate:auth: Generates TypeScript client for the Auth API.
  • generate:bitbucket: Generates TypeScript client for the Bitbucket API.
  • generate:jira: Generates TypeScript client for the Jira API.
  • generate:jenkins: Generates TypeScript client for the Jenkins API.
  • generate:sonar: Generates TypeScript client for the SonarQube API.

See client/README.md or API_GENERATION.md for more details on API client generation.

🔒 Security

Security Features

  • JWT Authentication: Secure token-based authentication
  • Spring Security: Comprehensive security framework
  • Password Encryption: BCrypt password hashing
  • CORS Configuration: Cross-origin resource sharing protection
  • Input Validation: Server-side validation for all inputs
  • SQL Injection Prevention: Parameterized queries with JPA

Security Best Practices

Authentication

// JWT Token Configuration
@Configuration
public class JwtConfig {
    @Value("${jwt.secret}")
    private String secret;
    
    @Value("${jwt.expiration}")
    private Long expiration;
}

Authorization

// Role-based access control
@PreAuthorize("hasRole('ADMIN')")
@GetMapping("/admin/users")
public List<User> getAllUsers() {
    return userService.findAll();
}

Input Validation

// Bean validation
public class LoginRequest {
    @NotBlank(message = "Username is required")
    @Size(min = 3, max = 50)
    private String username;
    
    @NotBlank(message = "Password is required")
    @Size(min = 8)
    private String password;
}

Security Checklist

  • JWT tokens are properly configured
  • Passwords are encrypted using BCrypt
  • CORS is properly configured
  • Input validation is implemented
  • SQL injection prevention is in place
  • HTTPS is used in production
  • Environment variables are used for secrets
  • Regular security updates are applied

🧪 Testing

Testing Strategy

Unit Testing

# Run unit tests
mvn test

# Run specific test class
mvn test -Dtest=UserServiceTest

# Run tests with coverage
mvn test jacoco:report

Integration Testing

# Run integration tests
mvn verify

# Run with test database
mvn test -Dspring.profiles.active=test

Frontend Testing

# Run Angular tests
cd client
pnpm test

# Run tests with coverage
pnpm test:coverage

# Run e2e tests
pnpm e2e

Test Configuration

Test Database (application-test.properties)

# Test Database Configuration
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driver-class-name=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=

# JPA Configuration for Tests
spring.jpa.hibernate.ddl-auto=create-drop
spring.jpa.show-sql=true

Test Coverage

  • Backend: Minimum 80% code coverage
  • Frontend: Minimum 70% code coverage
  • Integration: All critical paths covered

🚀 Deployment

Production Deployment

1. Build Production Artifacts

# Build backend
mvn clean package -DskipTests -Pprod

# Build frontend
cd client
pnpm build --prod
cd ..

2. Docker Deployment

# Build Docker images
docker-compose -f docker-compose.prod.yml build

# Deploy to production
docker-compose -f docker-compose.prod.yml up -d

3. Health Checks

# Check application health
curl http://localhost:3001/actuator/health

# Check database connectivity
curl http://localhost:3001/actuator/health/db

Deployment Best Practices

  • Use environment-specific configurations
  • Implement health checks
  • Set up monitoring and alerting
  • Configure backup strategies
  • Use HTTPS in production
  • Implement rate limiting
  • Set up logging aggregation
  • Configure auto-scaling

📊 Monitoring & Logging

Application Monitoring

Health Endpoints

  • Application Health: /actuator/health
  • Database Health: /actuator/health/db
  • Disk Space: /actuator/health/diskSpace
  • Application Info: /actuator/info

Metrics Endpoints

  • Application Metrics: /actuator/metrics
  • JVM Metrics: /actuator/metrics/jvm.*
  • HTTP Metrics: /actuator/metrics/http.server.requests

Logging Configuration

Logback Configuration (logback-spring.xml)

<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
    
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>logs/application.log</file>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>logs/application.%d{yyyy-MM-dd}.log</fileNamePattern>
            <maxHistory>30</maxHistory>
        </rollingPolicy>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>
    
    <root level="INFO">
        <appender-ref ref="STDOUT" />
        <appender-ref ref="FILE" />
    </root>
</configuration>

Monitoring Tools

  • Application Metrics: Spring Boot Actuator
  • Database Monitoring: pgAdmin
  • Container Monitoring: Docker stats
  • Log Aggregation: ELK Stack (optional)

🔧 Troubleshooting

Common Issues

1. Database Connection Issues

Problem: Cannot connect to PostgreSQL

# Check if PostgreSQL is running
docker ps | grep postgres

# Check database logs
docker logs personal-micromanager-postgres-1

# Verify connection settings
docker exec -it personal-micromanager-postgres-1 psql -U micromanager -d micromanager

Solution: Ensure PostgreSQL container is running and credentials are correct

2. Port Conflicts

Problem: Port 3001 or 5432 already in use

# Check port usage
netstat -ano | findstr :3001
netstat -ano | findstr :5432

# Kill process using port
taskkill /PID <process_id> /F

Solution: Stop conflicting services or change ports in configuration

3. Frontend Build Issues

Problem: Angular build fails

# Clear cache
cd client
rm -rf node_modules
pnpm install

# Check Angular version compatibility
ng version

Solution: Clear cache and reinstall dependencies

4. JWT Token Issues

Problem: Authentication fails

# Check JWT configuration
echo $JWT_SECRET

# Verify token expiration
curl -H "Authorization: Bearer <token>" http://localhost:3001/api/auth/validate

Solution: Verify JWT secret and expiration settings

Performance Issues

1. Slow Database Queries

-- Enable query logging
SET log_statement = 'all';
SET log_min_duration_statement = 1000;

-- Analyze slow queries
SELECT query, mean_time, calls 
FROM pg_stat_statements 
ORDER BY mean_time DESC 
LIMIT 10;

2. Memory Issues

# Check JVM memory usage
jstat -gc <pid>

# Monitor Docker container memory
docker stats

Debug Mode

# Enable debug logging
export LOGGING_LEVEL_ROOT=DEBUG

# Run with debug profile
mvn spring-boot:run -Dspring-boot.run.profiles=debug

📚 API Documentation

OpenAPI Specifications

API Documentation Tools

API Versioning

  • Current Version: v1
  • Version Strategy: URL path versioning (/api/v1/)
  • Backward Compatibility: Maintained for at least 2 versions

API Best Practices

  • Use proper HTTP status codes
  • Implement pagination for large datasets
  • Use consistent error response format
  • Implement rate limiting
  • Validate all inputs
  • Document all endpoints
  • Use proper authentication headers

🤝 Contributing

Development Setup

1. Fork and Clone

# Fork the repository on GitHub
# Clone your fork
git clone https://github.com/your-username/personal-micromanager.git
cd personal-micromanager

# Add upstream remote
git remote add upstream https://github.com/original-owner/personal-micromanager.git

2. Create Feature Branch

# Create and switch to feature branch
git checkout -b feature/your-feature-name

# Make your changes
# Test thoroughly
# Commit with descriptive message
git commit -m "feat: add new feature description"

3. Submit Pull Request

# Push to your fork
git push origin feature/your-feature-name

# Create pull request on GitHub
# Include detailed description of changes
# Reference any related issues

Code Quality Standards

Java Code Style

  • Follow Google Java Style Guide
  • Use meaningful variable and method names
  • Add comprehensive JavaDoc comments
  • Maintain 80%+ test coverage

Angular Code Style

  • Follow Angular Style Guide
  • Use TypeScript strict mode
  • Implement proper error handling
  • Follow component naming conventions

Git Commit Messages

feat: add new feature
fix: resolve bug
docs: update documentation
style: format code
refactor: restructure code
test: add or update tests
chore: maintenance tasks

Review Process

  1. Code Review: All changes require peer review
  2. Testing: All changes must pass tests
  3. Documentation: Update relevant documentation
  4. Security Review: Security-sensitive changes require security review

Development Guidelines

  • Write clear, readable code
  • Add comprehensive tests
  • Update documentation
  • Follow coding standards
  • Use meaningful commit messages
  • Test on multiple environments
  • Consider performance implications
  • Follow security best practices

📄 License

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

📞 Support

Getting Help

  • Documentation: Check this README and inline code comments
  • Issues: Create an issue on GitHub for bugs or feature requests
  • Discussions: Use GitHub Discussions for questions and ideas
  • Wiki: Check the project wiki for additional information

Community

Last Updated: July 2025
Version: 1.0.0

About

Personal micromanager app

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages