Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
414 lines (377 loc) · 23.9 KB

ARCHITECTURE.md

File metadata and controls

414 lines (377 loc) · 23.9 KB

🏗️ Architecture Documentation

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Web Browser                          │
│                     (User Interface)                        │
└────────────────────┬────────────────────────────────────────┘
                     │ HTTP/HTTPS
                     │
┌────────────────────▼────────────────────────────────────────┐
│                   OpenLiberty Server                        │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Jakarta EE Servlets                     │  │
│  │  ┌────────────┐  ┌────────────┐  ┌──────────────┐  │  │
│  │  │   Home     │  │  Analyzer  │  │    Fixer     │  │  │
│  │  │  Servlet   │  │  Servlet   │  │   Servlet    │  │  │
│  │  └─────┬──────┘  └─────┬──────┘  └──────┬───────┘  │  │
│  └────────┼───────────────┼─────────────────┼──────────┘  │
│           │               │                 │              │
│  ┌────────▼───────────────▼─────────────────▼──────────┐  │
│  │              Business Logic Layer                   │  │
│  │  ┌──────────────────┐    ┌────────────────────┐    │  │
│  │  │ Issue Detector   │    │    Auto Fixer      │    │  │
│  │  │  - Pattern Match │    │  - Transformation  │    │  │
│  │  │  - File Scan     │    │  - Backup Creation │    │  │
│  │  │  - Multi-Module  │    │  - Batch Process   │    │  │
│  │  └──────────────────┘    └────────────────────┘    │  │
│  └──────────────────────────────────────────────────────┘  │
│                           │                                 │
│  ┌────────────────────────▼─────────────────────────────┐  │
│  │                  Data Models                         │  │
│  │  ┌──────────────┐    ┌──────────────────────────┐   │  │
│  │  │ ProjectInfo  │    │   MigrationIssue         │   │  │
│  │  └──────────────┘    └──────────────────────────┘   │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────┬────────────────────────────────────────┘
                     │
                     │ File System Access
                     │
┌────────────────────▼────────────────────────────────────────┐
│                  User's File System                         │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Gradle Project Files                    │  │
│  │  - build.gradle                                      │  │
│  │  - settings.gradle                                   │  │
│  │  - gradle-wrapper.properties                         │  │
│  │  - Multi-module structure                            │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Component Architecture

Frontend Layer (Web UI)

┌─────────────────────────────────────────────────────────┐
│                     index.jsp                           │
│  ┌───────────────────────────────────────────────────┐ │
│  │  Project Selection Section                        │ │
│  │  - Path input                                     │ │
│  │  - Analyze button                                 │ │
│  └───────────────────────────────────────────────────┘ │
│  ┌───────────────────────────────────────────────────┐ │
│  │  Project Information Section                      │ │
│  │  - Metadata display                               │ │
│  │  - Statistics cards                               │ │
│  └───────────────────────────────────────────────────┘ │
│  ┌───────────────────────────────────────────────────┐ │
│  │  Issues List Section                              │ │
│  │  - Filterable issue cards                         │ │
│  │  - Detailed explanations                          │ │
│  │  - Fix buttons                                    │ │
│  └───────────────────────────────────────────────────┘ │
│  ┌───────────────────────────────────────────────────┐ │
│  │  Results Section                                  │ │
│  │  - Fix results display                            │ │
│  │  - Success/failure stats                          │ │
│  └───────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
         │
         │ JavaScript (app.js)
         │
         ▼
┌─────────────────────────────────────────────────────────┐
│              Client-Side Logic                          │
│  - AJAX requests (Fetch API)                           │
│  - DOM manipulation                                     │
│  - Event handling                                       │
│  - State management                                     │
│  - UI updates                                           │
└─────────────────────────────────────────────────────────┘

Backend Layer (Jakarta EE)

┌─────────────────────────────────────────────────────────┐
│                  Servlet Layer                          │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │  HomeServlet                                    │   │
│  │  - Route: /                                     │   │
│  │  - Serves main UI                               │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │  ProjectAnalyzerServlet                         │   │
│  │  - Route: /api/analyze                          │   │
│  │  - POST: Analyze project                        │   │
│  │  - GET: Retrieve current analysis               │   │
│  │  - Session management                            │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │  IssueFixerServlet                              │   │
│  │  - Route: /api/fix                              │   │
│  │  - POST: Apply fixes                            │   │
│  │  - Batch processing                              │   │
│  │  - Result aggregation                            │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Business Logic Layer

┌─────────────────────────────────────────────────────────┐
│              GradleIssueDetector                        │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Issue Pattern Registry                         │   │
│  │  - 12 predefined patterns                       │   │
│  │  - Regex-based matching                         │   │
│  │  - Severity classification                      │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Project Scanner                                │   │
│  │  - Recursive directory traversal                │   │
│  │  - .gradle file filtering                       │   │
│  │  - Multi-module detection                       │   │
│  │  - Gradle version extraction                    │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Issue Analyzer                                 │   │
│  │  - Pattern application                          │   │
│  │  - Context extraction                           │   │
│  │  - Explanation generation                       │   │
│  │  - Fix suggestion creation                      │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│                   AutoFixer                             │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Backup Manager                                 │   │
│  │  - Timestamped backups                          │   │
│  │  - Restore capability                           │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Fix Transformers                               │   │
│  │  - Configuration replacements                   │   │
│  │  - API migrations                               │   │
│  │  - Property conversions                         │   │
│  │  - Syntax updates                               │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Batch Processor                                │   │
│  │  - Multiple issue handling                      │   │
│  │  - Result aggregation                           │   │
│  │  - Error handling                               │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Data Flow

Analysis Flow

User Input (Project Path)
    │
    ▼
ProjectAnalyzerServlet
    │
    ├─► Validate path
    │
    ├─► Create GradleIssueDetector
    │
    ├─► analyzeProject()
    │       │
    │       ├─► Scan directory structure
    │       │
    │       ├─► Detect modules
    │       │
    │       ├─► Extract Gradle version
    │       │
    │       ├─► For each .gradle file:
    │       │       │
    │       │       ├─► Apply patterns
    │       │       │
    │       │       ├─► Extract matches
    │       │       │
    │       │       ├─► Generate explanations
    │       │       │
    │       │       └─► Create MigrationIssue objects
    │       │
    │       └─► Aggregate results
    │
    ├─► Create ProjectInfo
    │
    ├─► Store in session
    │
    └─► Return JSON response
            │
            ▼
        Display in UI

Fix Flow

User Selection (Issue IDs)
    │
    ▼
IssueFixerServlet
    │
    ├─► Retrieve ProjectInfo from session
    │
    ├─► Find selected issues
    │
    ├─► Create AutoFixer
    │
    ├─► For each issue:
    │       │
    │       ├─► Validate auto-fixable
    │       │
    │       ├─► Create backup
    │       │       │
    │       │       └─► file.backup.timestamp
    │       │
    │       ├─► Read file content
    │       │
    │       ├─► Apply transformation
    │       │       │
    │       │       ├─► Pattern matching
    │       │       │
    │       │       ├─► String replacement
    │       │       │
    │       │       └─► Regex substitution
    │       │
    │       ├─► Write fixed content
    │       │
    │       └─► Create FixResult
    │
    ├─► Aggregate results
    │
    ├─► Update session
    │
    └─► Return JSON response
            │
            ▼
        Display results in UI

State Management

Session State

HttpSession
    │
    ├─► currentProject (ProjectInfo)
    │       │
    │       ├─► projectPath
    │       ├─► projectName
    │       ├─► currentGradleVersion
    │       ├─► isMultiModule
    │       ├─► modules[]
    │       └─► issues[]
    │               │
    │               └─► MigrationIssue[]
    │                       │
    │                       ├─► id
    │                       ├─► type
    │                       ├─► severity
    │                       ├─► filePath
    │                       ├─► lineNumber
    │                       ├─► currentCode
    │                       ├─► suggestedFix
    │                       └─► explanation
    │
    └─► Session timeout: 30 minutes

Client State

JavaScript State
    │
    ├─► currentProject (object)
    │
    ├─► allIssues (array)
    │
    └─► selectedIssues (Set)

Security Architecture

Input Validation

┌─────────────────────────────────────────┐
│  User Input                             │
└───────────┬─────────────────────────────┘
            │
            ▼
┌─────────────────────────────────────────┐
│  Validation Layer                       │
│  - Path sanitization                    │
│  - Null checks                          │
│  - Format validation                    │
└───────────┬─────────────────────────────┘
            │
            ▼
┌─────────────────────────────────────────┐
│  Business Logic                         │
└─────────────────────────────────────────┘

File System Access

┌─────────────────────────────────────────┐
│  Requested Path                         │
└───────────┬─────────────────────────────┘
            │
            ▼
┌─────────────────────────────────────────┐
│  Path Validation                        │
│  - Exists check                         │
│  - Readable check                       │
│  - Directory check                      │
└───────────┬─────────────────────────────┘
            │
            ▼
┌─────────────────────────────────────────┐
│  File Operations                        │
│  - Read only (analysis)                 │
│  - Write with backup (fix)              │
└─────────────────────────────────────────┘

Deployment Architecture

Development

┌─────────────────────────────────────────┐
│  Developer Machine                      │
│  ┌───────────────────────────────────┐ │
│  │  ./gradlew libertyDev             │ │
│  │  - Hot reload enabled             │ │
│  │  - Debug port: 7777               │ │
│  │  - Interactive console            │ │
│  └───────────────────────────────────┘ │
└─────────────────────────────────────────┘

Production

┌─────────────────────────────────────────┐
│  Application Server                     │
│  ┌───────────────────────────────────┐ │
│  │  OpenLiberty / WildFly / Payara   │ │
│  │  ┌─────────────────────────────┐  │ │
│  │  │  gradle-migration-helper.war│  │ │
│  │  └─────────────────────────────┘  │ │
│  └───────────────────────────────────┘ │
│                                         │
│  HTTP: 9080                             │
│  HTTPS: 9443                            │
└─────────────────────────────────────────┘

Performance Considerations

Scalability

  • Concurrent Users: 50+ (session-based)
  • File Processing: Async for large projects
  • Memory: ~50MB per 1000 files
  • Response Time: <5s for typical projects

Optimization Strategies

  1. Pattern Compilation: Pre-compiled regex patterns
  2. File Filtering: Early filtering of non-Gradle files
  3. Lazy Loading: Issues loaded on demand
  4. Session Management: Efficient state storage
  5. Batch Processing: Multiple fixes in single transaction

Architecture Version: 1.0.0
Last Updated: October 30, 2024
⚡