← Back to ProjectsView Architecture

Jenkins Monitor#

Project Overview##

  • Name: Jenkins Monitor
  • Version: 0.1.0
  • Type: Monorepo Jenkins CI/CD Monitoring System
  • Architecture: Full-stack TypeScript application with NestJS backend and Next.js frontend
  • Purpose: Comprehensive monitoring, configuration management, and audit capabilities for Jenkins environments

Monorepo Structure##

Root Configuration###

  • Package Manager: pnpm with workspace configuration
  • Workspace Definition: pnpm-workspace.yaml defines packages in packages/*
  • Shared Dependencies: Managed at root level with individual package-specific dependencies
  • Development Tool: Concurrently for running multiple processes

Package Organization###

txt

Backend Architecture (@jenkins-monitor/backend)##

Technology Stack###

  • Framework: NestJS 11.x with Express platform
  • Database: MongoDB with Mongoose ODM 8.x
  • Authentication: JWT with Passport strategies
  • Real-time Communication: Socket.IO 4.x
  • Background Processing: Bull queues with @nestjs/schedule
  • API Documentation: Swagger/OpenAPI with @nestjs/swagger
  • Validation: class-validator and class-transformer
  • Logging: Winston with daily file rotation
  • Testing: Jest with supertest for e2e testing

Core Application Configuration###

  • Global API Prefix: jenkins-monitor/api
  • Versioning: URI-based versioning (v1 default)
  • CORS: Enabled with credentials support
  • Validation: Global validation pipe with whitelist enabled
  • Swagger UI: Available at /jenkins-monitor/api/swagger-ui
  • Health Check: Available at /jenkins-monitor/api/v1/ping
  • Socket.IO UI: Available at /jenkins-monitor/api/socketio-ui.html

Module Architecture###

Core Infrastructure Modules

  1. Database Module (src/database/)

    • MongoDB connection with Mongoose
    • Connection pooling and retry logic
    • Global module available across application

  2. Configuration Module (src/config/)

    • Multi-tier configuration system
    • Database > Environment Variables > Defaults priority
    • Dynamic runtime updates with event emission
    • Schema-based validation

  3. Logging Module (src/logging/)

    • Winston-based logging with daily rotation
    • Request ID middleware for tracing
    • Request/response logging middleware
    • Configurable log levels and retention

  4. Audit Module (src/audit/)

    • MongoDB-based audit trails
    • Automatic action logging for system changes
    • Sensitive data sanitization
    • Configurable retention with automated cleanup

  5. Error Handling (src/errors/)

    • Global exception filter
    • Custom application exceptions
    • Unified error response format
    • Request context logging

Authentication & Authorization

  • Admin Module (src/admin/)

    • Key-based authentication via x-admin-key header
    • Admin guard for protected endpoints
    • Background task management service

  • Auth Module (src/auth/)

    • JWT token management with refresh tokens
    • Passport strategies (JWT, local)
    • Role-based access control decorators
    • Password hashing service

Business Logic Modules

  1. Users Module (src/users/)

    • User management and authentication
    • Status management and role assignment
    • Password reset functionality

  2. Teams Module (src/teams/)

    • Team creation and member management
    • Service assignment to teams
    • Team-based access control

  3. Services Module (src/services/)

    • Service discovery and monitoring
    • Health check management and scheduling
    • Service status tracking

  4. Pipelines Module (src/pipelines/)

    • Jenkins pipeline synchronization
    • Pipeline discovery and categorization
    • Build status tracking

  5. Builds Module (src/builds/)

    • Build execution monitoring
    • Build result tracking
    • Historical build data management

  6. Deployments Module (src/deployments/)

    • Deployment tracking
    • Chronic failure detection
    • Environment-specific deployment management

  7. Environments Module (src/environments/)

    • Environment discovery and management
    • Configuration deployment tracking

Integration & Communication

  1. Jenkins Module (src/jenkins/)

    • Jenkins API integration
    • Connection testing and validation
    • Pipeline and build data synchronization

  2. Socket Module (src/socket/)

    • Real-time WebSocket communication
    • Client subscription management
    • Event broadcasting for status updates

  3. Ping Module (src/ping/)

    • Health check endpoints
    • System status monitoring
    • Load balancer readiness checks

Data Models & Schemas###

Core Schemas (Mongoose)

  • User Schema: User profiles, authentication, status management
  • Team Schema: Team structures, member assignments, service relationships
  • Service Schema: Service definitions, health check configurations
  • Pipeline Schema: Jenkins pipeline metadata, synchronization status
  • Build Schema: Build execution records, results, processing status
  • Environment Schema: Environment configurations, deployment tracking
  • Health Check Schema: Service health monitoring data
  • Audit Log Schema: System action tracking, user activity logs
  • JWT Token Schema: Token management, refresh token handling

Enums & Constants

  • User Status: Active, Inactive, Pending, Suspended
  • Roles: Admin, User, Viewer, Manager
  • Build Results: Success, Failure, Unstable, Aborted, In Progress
  • Build Processing Status: Pending, Processing, Completed, Failed
  • Pipeline Categories: Build, Deploy, Test, Release
  • Health Check Status: Healthy, Warning, Critical, Unknown
  • Sync Status: Pending, In Progress, Completed, Failed
  • Privilege Actions: Create, Read, Update, Delete, Execute

API Design Patterns###

Request/Response Structure

  • Unified response format with status, message, data, and pagination
  • Request ID propagation for end-to-end tracing
  • Global validation with class-validator decorators
  • Swagger documentation generation from code annotations

Error Handling

  • Custom exception hierarchy with application-specific error codes
  • Global exception filter with sanitization
  • Context-aware error logging with request correlation

Security Features

  • JWT-based authentication with automatic token refresh
  • Admin key authentication for administrative endpoints
  • CORS configuration with credential support
  • Input validation and sanitization

Frontend Architecture (@jenkins-monitor/frontend)##

Technology Stack - Frontend###

  • Framework: Next.js 15.x with App Router
  • UI Framework: Radix UI components with Tailwind CSS 3.x
  • State Management: React Context for authentication and local state
  • Forms: React Hook Form 7.x with Zod validation
  • Data Visualization: Recharts for charts and graphs
  • Data Tables: TanStack Table for complex data grids
  • Notifications: Sonner for toast messages
  • Theme Management: next-themes for dark/light mode
  • Real-time: Socket.IO client for live updates
  • Drag & Drop: DND Kit for interactive interfaces

Application Configuration###

  • Base Path: /jenkins-monitor for deployment routing
  • Development Server: Next.js dev server on port 3000
  • Build Target: Static optimization with image unoptimization
  • TypeScript: Build errors ignored for development flexibility
  • ESLint: Build-time linting disabled for faster builds

Architecture Patterns###

App Router Structure

  • File-based Routing: Next.js 15 App Router conventions
  • Layout System: Nested layouts with shared navigation
  • Loading States: Route-level loading components
  • Error Boundaries: Route-level error handling

Component Architecture

  1. UI Components (components/ui/)

    • Radix UI primitive wrappers
    • Consistent design system
    • Accessibility-first implementation
    • Theme-aware styling with Tailwind CSS

  2. Feature Components

    • Domain-specific components (teams, services, builds)
    • Reusable business logic components
    • Modal and dialog implementations

  3. Layout Components

    • App layout with navigation
    • Site header and navigation
    • Sidebar and mobile-responsive design

State Management

  1. Authentication Context (lib/auth/auth-context.tsx)

    • JWT token management
    • Automatic token refresh
    • User session handling
    • Remember me functionality

  2. Socket Context (lib/socket/socket-context.tsx)

    • Real-time connection management
    • Event subscription handling
    • Connection status monitoring

  3. Theme Provider (components/theme-provider.tsx)

    • Dark/light mode management
    • System preference detection
    • Persistent theme storage

API Integration Layer###

Centralized API Client (lib/apis/api-client.ts)

  • Axios-based HTTP client with interceptors
  • Automatic authentication token injection
  • Request/response logging
  • Error handling and retry logic
  • Base URL configuration for backend communication

API Modules

  1. Authentication API: Login, logout, token refresh, password reset
  2. User API: User management, profile updates, status changes
  3. Team API: Team CRUD operations, member management
  4. Service API: Service monitoring, health checks, status updates
  5. Pipeline API: Pipeline synchronization, build triggering
  6. Build API: Build monitoring, result tracking, historical data
  7. Environment API: Environment discovery, configuration management
  8. Deployment API: Deployment tracking, failure analysis
  9. Admin API: System administration, configuration management

TypeScript Type System (lib/types/)

  • Comprehensive type definitions for all API contracts
  • Shared interfaces between frontend and backend
  • Strong typing for forms, tables, and components
  • Generic types for common patterns (pagination, responses)

Real-time Features###

Socket.IO Integration

  • Automatic connection management
  • Subscription-based event handling
  • Real-time status updates for builds, services, and deployments
  • Connection status indicators
  • Automatic reconnection logic

Live Data Updates

  • Build status changes
  • Service health monitoring
  • Environment synchronization status
  • User activity notifications

User Interface Features###

Data Tables

  • TanStack Table for complex data operations
  • Server-side pagination and filtering
  • Column sorting and customization
  • Row selection and bulk operations
  • Export functionality

Forms & Validation

  • React Hook Form with Zod schema validation
  • Dynamic form generation
  • Real-time validation feedback
  • File upload support
  • Multi-step form workflows

Charts & Visualization

  • Recharts integration for metrics display
  • Build success/failure trends
  • Service health dashboards
  • Deployment frequency charts
  • Performance monitoring graphs

Navigation & Layout

  • Responsive sidebar navigation
  • Breadcrumb navigation
  • Mobile-optimized interface
  • Keyboard accessibility
  • Screen reader support

Development Features###

Performance Optimization

  • Lazy loading components
  • Virtual scrolling for large data sets
  • Debounced search and filtering
  • Optimistic UI updates
  • Smart caching strategies

Error Handling - Frontend

  • Error boundaries for component isolation
  • Toast notifications for user feedback
  • Network error detection and retry
  • Graceful degradation for offline scenarios

Accessibility

  • ARIA labels and roles
  • Keyboard navigation support
  • Color contrast compliance
  • Screen reader optimization
  • Focus management

Development Workflow##

Environment Setup###

  1. Prerequisites: Node.js, pnpm package manager
  2. Installation: pnpm install for all dependencies
  3. Development: pnpm dev starts both frontend and backend
  4. Port Configuration: Backend (3001), Frontend (3000)

Build & Deployment###

  1. Build Process: pnpm build for production builds
  2. Production Start: pnpm start for both applications
  3. Static Assets: Frontend builds to static files
  4. API Serving: Backend serves both API and static files

Code Quality###

  1. Linting: ESLint configuration for both packages
  2. Formatting: Prettier for consistent code style
  3. Type Checking: TypeScript strict mode enabled
  4. Testing: Jest for unit and integration tests

Git Workflow###

  • Main Branch: master for production releases
  • Development Branch: dev_clean_backend for active development
  • Feature Branches: Individual feature development
  • Status Tracking: Modified files tracked in package-lock.json

Environment Variables & Configuration##

Backend Environment Variables###

  • DATABASE_URI: MongoDB connection string
  • JWT_SECRET: Secret key for JWT token signing
  • CORS_ORIGIN: Frontend URL for CORS configuration
  • PORT: Backend server port (default: 3001)
  • NODE_ENV: Environment mode (development/production)
  • Admin authentication keys for protected endpoints

Frontend Environment Variables###

  • API endpoint configuration for backend communication
  • WebSocket connection settings
  • Theme and UI configuration options
  • Analytics and monitoring configurations

Security & Compliance##

Authentication Security###

  • JWT token expiration and refresh mechanisms
  • Secure cookie handling for persistent sessions
  • Password hashing with bcrypt
  • Admin key validation for privileged operations

Data Protection###

  • Sensitive data sanitization in logs
  • Input validation and sanitization
  • SQL injection prevention through Mongoose ODM
  • XSS protection through React's built-in escaping

API Security###

  • CORS configuration with specific origins
  • Rate limiting and request validation
  • Authentication required for protected endpoints
  • Audit logging for all system changes

Monitoring & Observability##

Logging Strategy###

  • Structured logging with Winston
  • Request tracing with correlation IDs
  • Performance monitoring and metrics
  • Error aggregation and alerting

Health Monitoring###

  • Application health check endpoints
  • Database connection monitoring
  • Service dependency health checks
  • Real-time status dashboards

Audit & Compliance###

  • Comprehensive audit trail for all user actions
  • Configurable retention policies
  • Administrative access logging
  • Data change tracking and history

Deployment Architecture##

Production Deployment###

  • Frontend: Static file generation with CDN optimization
  • Backend: Node.js application with process management
  • Database: MongoDB with replica set configuration
  • Reverse Proxy: nginx for SSL termination and routing

Scaling Considerations###

  • Horizontal scaling support for backend instances
  • Database connection pooling and optimization
  • CDN integration for frontend asset delivery
  • Load balancing configuration for high availability

This comprehensive overview provides complete context about the Jenkins Monitor project structure, architecture, technologies, and implementation patterns.

Architecture Diagram

Drag to pan, scroll to zoom