Skip to main content

Component Design

Module: Lens Version: 1.0.0-RELEASE Last Updated: October 25, 2025 Document Type: Component Design (Implementation Details)

Overview​

This document provides detailed design information for all Lens components: 40 controllers, 107 services, 47 DAOs, and supporting utilities.

Component Statistics:

  • Controllers: 40 (14 core + 5 alerts + 13 cost breakup + 3 CUDOS + 5 others)
  • Services: 107 (20 core + 60+ cost breakup + others)
  • DAOs: 47 (35+ Snowflake + 5 MongoDB + others)
  • DTOs: 165 (across all domains)
  • Utilities: 10 utility classes

Controller Layer (40 Controllers)​

Core Controllers (14)​

1. AwsVsActualCostController​

Location: controller/AwsVsActualCostController.java:30 Purpose: Compare AWS billed costs vs actual usage costs Security: @Secured(key = "LENS_AWSVSACTUALCOSTCONTROLLER")

Endpoints:

  • GET /admin-pages/cost/summary - Cost summary comparison
  • GET /admin-pages/cost/v2/summary - Enhanced cost summary (multi-account)
  • GET /admin-pages/cost/v2/detail - Detailed resource-level breakdown
  • GET /admin-pages/cost/export - Export to Excel

Service Dependency: AwsVsActualCostService

2. BillingConsoleController​

Location: controller/BillingConsoleController.java:29 Purpose: Central billing dashboard Security: @Secured(key = "LENS_BILLINGCONSOLECONTROLLER")

Endpoints:

  • GET /billing-console/cost - Current month cost with projection
  • GET /billing-console/monthly - Monthly billing summary
  • GET /billing-console/dailyBreakup - Daily cost breakdown (line chart)
  • GET /billing-console/previousMonths - Historical monthly costs (12 months)
  • GET /billing-console/exportMonthlyReport - Export monthly report
  • GET /billing-console/exportPreviousMonthReport - Export previous month

Service Dependency: BillingConsoleService

3. BillingSummaryController​

Purpose: Generate comprehensive billing reports Endpoints: Aggregated summaries, chargeback/showback reports

4. CostExplorerController​

Purpose: Ad-hoc cost analysis with flexible filtering Key Feature: Multi-dimensional filtering (time, service, region, account, tags)

5. CostTrendsController​

Purpose: Time-series cost trend analysis Key Feature: WoW, MoM, YoY comparisons, forecasting

6. ReservationController​

Location: controller/ReservationController.java:27 Purpose: RI inventory management Endpoints:

  • GET /reservation-summary/get - All active RIs with details
  • GET /reservation-summary/export - Export RI inventory to Excel

7. ReservationUtilizationController​

Purpose: Track RI utilization percentage Alert Threshold: <80% triggers warning

8. RiCoverageController​

Purpose: RI coverage analysis, purchase recommendations Key Metric: % of usage covered by RIs

9. RecommendationController​

Purpose: AWS Cost Explorer recommendations integration Types: Rightsizing, RI purchases, Savings Plans, storage optimization

10. AccountWiseBreakupController & AccountWiseBreakupV2Controller​

Purpose: Multi-account cost segmentation V2 Enhancement: Organizational Unit (OU) hierarchy support

11. SavedReportFilterMetaController​

Purpose: Save and manage custom filter combinations

12. TagReportController​

Purpose: Tag-based cost allocation reports Use Case: Chargebacks by department/project/environment

13. DatesController​

Purpose: Date range utilities (MTD, QTD, YTD, custom)

Alert Controllers (5) - controller/alertsapi/​

1. CostAlertController​

Purpose: Budget threshold & anomaly alerts Thresholds: 50%, 80%, 100%, 120% of budget

2. DailyReportController​

Purpose: Daily cost summary emails Content: Yesterday's spend, day-over-day change, top 5 services

3. RiExpiryAlertController​

Purpose: RI expiry notifications Schedule: 90, 60, 30 days before expiry

4. RiUtilizationAlertController​

Purpose: Low RI utilization warnings Thresholds: <80% warning, <60% critical

5. AccountsDatesController​

Purpose: Account-specific date utilities for alerts

Cost Breakup Controllers (13) - controller/costbreakup/​

All extend AbstractCostBreakupController for common validation/error handling.

1. AnalyticsController​

Services: Kinesis, EMR, Athena, Glue Cost Dimensions: Data ingestion, processing, storage

2. ContainersController​

Services: ECS, EKS, Fargate Cost Dimensions: Task hours, cluster management

3. DatabaseController​

Services: RDS, DynamoDB, ElastiCache, Redshift, OpenSearch Cost Dimensions: Instance hours, storage, IOPS, backups

4. DataTransferController​

Types: Inter-AZ, inter-region, internet egress Key Insight: Shows source/destination pairs (top talkers)

5. InstanceCostController​

Services: EC2, RDS instances, ElastiCache nodes Analysis: On-Demand vs RI vs Spot distribution

6. ManagementAndGovernanceController​

Services: CloudWatch (Logs, Metrics, Alarms)

7. MediaController​

Services: MediaLive, MediaConnect, MediaTailor

8. MigrationAndTransferController​

Services: Database Migration Service (DMS)

9. NetworkingAndContentDeliveryController​

Services: CloudFront, Load Balancers, API Gateway

10. SecurityController​

Services: WAF, GuardDuty, Shield

11. ServerlessController​

Services: Lambda, SQS, SNS, SES

12. StorageController​

Services: S3, EBS, EFS, Glacier Key Feature: Storage class distribution, lifecycle recommendations

13. AbstractCostBreakupController​

Purpose: Base class for common logic (validation, error handling, response wrapping)

CUDOS Controllers (3) - controller/cudos/​

1. S3DashboardController​

Purpose: S3-specific cost dashboard Metrics: Storage by class, request costs, data transfer, lifecycle effectiveness

2. DataTransferDashboardController​

Purpose: Data transfer cost analysis Breakdown: Inter-AZ, inter-region, internet egress by service

3. DatabaseDashboardController​

Purpose: Database cost dashboard (RDS, ElastiCache, DynamoDB) Metrics: Compute vs storage, utilization, backup costs

Other Controllers (5)​

1. FinOpsRecommendationController - controller/finops/​

Purpose: Custom FinOps best practices Examples: CLB→ALB migration, idle resource detection, S3 lifecycle

2. MarketPlaceController - controller/marketplace/​

Purpose: AWS Marketplace metering integration

3. MonthlyReportAccountDates - controller/monthlyreport/​

Purpose: Date utilities for monthly reports

4. ReportRecommendationController - controller/monthlyreport/​

Purpose: Top 10 monthly recommendations report

Service Layer (107 Services)​

Core Services (20)​

1. AwsVsActualCostService / AwsVsActualCostServiceImpl​

Location: service/impl/AwsVsActualCostServiceImpl.java Key Methods:

  • getCostSummary(GenericRequestDTO) - Fetch cost comparison
  • getCostV2Summary(GenericRequestDTO) - Enhanced multi-account version
  • getCostV2Detail(AwsVsActualCostDetailDTO) - Resource-level details
  • exportReport(ReportDTO) - Generate Excel export

Business Logic:

  • Queries Snowflake for AWS billed costs and actual usage costs
  • Calculates variance percentage: (ActualCost - AwsCost) / AwsCost * 100
  • Marketplace savings: (AwsStandardCost - MarketplaceCost) / AwsStandardCost * 100
  • Aggregates by service, region, account

Dependencies: AwsVsActualCostDao, ExcelWriter

2. BillingConsoleService / BillingConsoleServiceImpl​

Key Methods:

  • getCost(BillingConsoleRequestDTO) - Current month cost + projection
  • getMonthlyReport(GenericRequestDTO) - Complete monthly summary
  • getDailyBreakup(GenericRequestDTO) - Daily time-series data
  • getPreviousMonth(GenericRequestDTO) - Historical comparison
  • exportMonthlyReport(ReportDTO) - Excel export

Business Logic:

  • Calculates MTD (month-to-date) spend
  • Projects end-of-month total: MTDSpend / DaysElapsed * TotalDaysInMonth
  • Compares vs budget, flags if >80%
  • Aggregates top 10 services by cost

3. CostExplorerService / CostExplorerServiceImpl​

Purpose: Flexible cost queries with dynamic filtering Key Feature: Supports up to 5 simultaneous filters (service, region, account, tag, resource)

4. CostTrendsService / CostTrendsServiceImpl​

Purpose: Trend analysis and forecasting Calculations:

  • WoW growth: (ThisWeek - LastWeek) / LastWeek * 100
  • MoM growth: (ThisMonth - LastMonth) / LastMonth * 100
  • Linear forecast: y = mx + b (simple regression)

5. ReservationService / ReservationServiceImpl​

Purpose: RI inventory management Data Source: AWS Cost Explorer API + Snowflake (historical data)

6. RecommendationService / RecommendationServiceImpl​

Purpose: Fetch and prioritize AWS recommendations Sorting: By estimated annual savings (DESC)

7. DatesService / DatesServiceImpl​

Purpose: Date range calculations (MTD, QTD, YTD, last 30 days, etc.)

8. CustomReportParserService​

Purpose: Parse saved report definitions

9. DailyReportService​

Purpose: Generate daily cost summary

10. DashboardReportService​

Purpose: Aggregate dashboard data

Cost Breakup Services (60+)​

Organized by AWS service category, located in service/impl/costbreakup/.

Pattern: Each category has:

  • Interface: [Category]Service.java
  • Implementation: [Category]ServiceImpl.java
  • Multiple sub-services for specific AWS services

Example - Analytics Category:

service/impl/costbreakup/analytics/
├── AnalyticsService.java (interface)
├── AnalyticsServiceImpl.java (orchestrator)
├── KinesisService.java
├── KinesisServiceImpl.java
├── EmrService.java
└── EmrServiceImpl.java

Analytics Services​

  • KinesisService: Kinesis Data Streams cost breakdown (shard hours, PUT units)
  • EmrService: EMR cluster costs (instance hours by type, storage)
  • AthenaService: Athena query costs (data scanned)
  • GlueService: Glue job costs (DPU hours, crawls)

Database Services​

  • RdsService: RDS instance + storage costs
  • DynamoDbService: DynamoDB capacity units (read/write), storage
  • ElastiCacheService: ElastiCache node hours
  • RedshiftService: Redshift node hours, storage, Spectrum
  • OpenSearchService: OpenSearch instance hours, storage

Storage Services​

  • S3Service: S3 storage by class, requests, data transfer
  • EbsService: EBS volumes by type (gp2/gp3/io1), snapshots
  • EfsService: EFS storage (Standard/IA), throughput
  • GlacierService: Glacier storage, retrieval costs

(60+ services total across 12 categories)

DAO Layer (47 DAOs)​

Snowflake DAOs (35+)​

Pattern: All Snowflake DAOs follow this structure:

  • Interface: [Feature]Dao.java
  • Implementation: [Feature]DaoImpl.java
  • Queries: Defined in .properties files (src/main/resources/queries/)

Key DAOs:​

1. AwsVsActualCostDao / AwsVsActualCostDaoImpl Location: dao/impl/AwsVsActualCostDaoImpl.java Methods:

  • queryCostSummary(GenericRequestDTO) → List<CostSummaryDTO>
  • queryCostDetail(AwsVsActualCostDetailDTO) → List<CostDetailDTO>

Query Pattern:

-- Loaded from resources/queries/AwsVsActualCost.properties
SELECT
    ACCOUNT_ID,
    SERVICE,
    SUM(AWS_COST) AS AWS_COST,
    SUM(ACTUAL_COST) AS ACTUAL_COST,
    SUM(ACTUAL_COST) - SUM(AWS_COST) AS VARIANCE
FROM COST_DAILY
WHERE ACCOUNT_ID IN (?)
  AND DATE BETWEEN ? AND ?
GROUP BY ACCOUNT_ID, SERVICE
ORDER BY VARIANCE DESC

2. BillingConsoleDao / BillingConsoleDaoImpl Queries: Monthly summaries, daily breakups, top services

3. CostExplorerDao / CostExplorerDaoImpl Feature: Dynamic query builder based on filters

4. Cost Breakup DAOs (12 categories):

  • AnalyticsDao, DatabaseDao, StorageDao, etc.
  • Each queries specific Snowflake tables for service-level cost data

Query Optimization:

  • All queries use parameterized statements (PreparedStatement) - prevents SQL injection
  • WHERE DATE BETWEEN ? AND ? clause enables partition pruning
  • GROUP BY reduces result set size
  • ORDER BY with LIMIT for top-N queries

MongoDB Repositories (5)​

Spring Data MongoDB - Interface-based, no implementation needed.

1. SavedReportRepository

public interface SavedReportRepository extends MongoRepository<SavedReportDocument, String> {
    `List<SavedReportDocument>` findByCustomerId(String customerId);
    `Optional<SavedReportDocument>` findByReportId(String reportId);
}

2. FilterMetadataRepository

public interface FilterMetadataRepository extends MongoRepository<FilterMetadataDocument, String> {
    `Optional<FilterMetadataDocument>` findByCustomerIdAndFilterType(String customerId, String filterType);
}

3. CustomQueryRepository 4. ReportScheduleRepository 5. UserPreferencesRepository

JPA Repositories (7) - MySQL​

1. UserRepository

public interface UserRepository extends JpaRepository<User, String> {
    `Optional<User>` findByEmail(String email);
    `List<User>` findByCustomerId(String customerId);
}

2. AccountRepository 3. BillingMetadataRepository (7 repositories total for transactional data)

Utility Classes (10)​

1. ApplicationConstants.java​

Location: utils/ApplicationConstants.java Size: 660+ constants Categories:

  • SQL query keys
  • API endpoint paths
  • Error messages
  • Configuration keys
  • Queue names
  • Cache names

Example:

public class ApplicationConstants {
    // Query keys
    public static final String QUERY_COST_SUMMARY = "query.cost.summary";

    // Error messages
    public static final String ERROR_INVALID_DATE_RANGE = "Invalid date range. End date must be after start date.";

    // Cache names
    public static final String CACHE_DASHBOARD = "dashboardQueries";
    public static final String CACHE_FILTERS = "filterMetadata";
}

2. ApplicationUtils.java​

Purpose: Common utility methods Methods:

  • formatDate(LocalDate) - Format dates consistently
  • calculatePercentage(double, double) - Calculate % with null safety
  • roundToTwoDecimals(double) - Round currency values
  • isValidDateRange(LocalDate, LocalDate) - Validate date ranges

3. ColumnNameConstants.java​

Purpose: Database column name constants (avoid typos)

4. QueueConstants.java​

Purpose: RabbitMQ queue/exchange names

5. SortUtils.java​

Purpose: Sorting utilities for collections

6. AccountWiseBreakUpReportGenerator.java​

Purpose: Generate account-wise Excel reports

7. HourlyDataConverter.java​

Purpose: Convert hourly data to daily/monthly aggregations

8. SequenceGenerationUtil.java​

Purpose: Generate unique IDs

9. StrReplaceForMongoUtils.java​

Purpose: Escape special characters for MongoDB queries

10. UtilityService.java​

Purpose: Miscellaneous helper service methods

Query Classes (Snowflake SQL)​

Location: queries/ package Pattern: Java classes holding SQL query strings

Example - AnalyticsQueries.java:

public class AnalyticsQueries {
    public static final String KINESIS_COST_QUERY = """
        SELECT
            USAGE_TYPE,
            SUM(COST) AS TOTAL_COST,
            SUM(USAGE_QUANTITY) AS USAGE_QUANTITY
        FROM COST_DAILY
        WHERE ACCOUNT_ID = :accountId
          AND SERVICE = 'Amazon Kinesis'
          AND DATE BETWEEN :startDate AND :endDate
        GROUP BY USAGE_TYPE
        ORDER BY TOTAL_COST DESC
        """;
}

Query Property Files (resources/queries/):

  • billingConsoleQueries.properties
  • costExplorerQueries.properties
  • riUtilizationQuery.properties
  • costbreakup/[category]Queries.properties (12 files)
  • cudos/[dashboard]Queries.properties (3 files)

Configuration Classes​

1. SnowflakeConfig.java​

Purpose: Snowflake datasource configuration Key Beans:

  • snowflakeDataSource() - HikariCP connection pool
  • snowflakeJdbcTemplate() - JdbcTemplate for queries

2. MongoConfig.java​

Purpose: MongoDB configuration Key Features: Custom converters, codec registry

3. RedisConfig.java​

Purpose: Redis cache configuration Key Beans:

  • redisConnectionFactory()
  • cacheManager() with TTL configuration

4. RabbitMQConfig.java​

Purpose: RabbitMQ exchanges, queues, bindings Declares:

  • lens.events topic exchange
  • Multiple queues for different event types
  • Routing key bindings

5. SwaggerConfig.java​

Purpose: OpenAPI/Swagger UI configuration

Enumerations​

Cost Breakup Enums (12)​

Location: enums/costbreakup/

Example - AnalyticsServiceEnum.java:

public enum AnalyticsServiceEnum {
    KINESIS("Amazon Kinesis"),
    EMR("Amazon Elastic MapReduce"),
    ATHENA("Amazon Athena"),
    GLUE("AWS Glue");

    private final String serviceName;

    AnalyticsServiceEnum(String serviceName) {
        this.serviceName = serviceName;
    }
}

CUDOS Enums (3)​

  • S3MetricEnum - S3 dashboard metrics
  • DataTransferTypeEnum - Transfer types (inter-AZ, inter-region, etc.)
  • DatabaseTypeEnum - Database services

Component Interaction Example​

Scenario: User requests cost summary

1. HTTP Request
   GET /admin-pages/cost/summary?customerId=CUST-123&startDate=2024-01-01&endDate=2024-01-31

2. AwsVsActualCostController.getAwsAndActualCostSummary()
   - Validates input (@Valid GenericRequestDTO)
   - authX checks JWT and permissions

3. AwsVsActualCostService.getCostSummary()
   - Calls AwsVsActualCostDao.queryCostSummary()
   - Calculates variance percentages
   - Sorts by absolute variance (DESC)

4. AwsVsActualCostDao.queryCostSummary()
   - Loads SQL from AwsVsActualCost.properties
   - Executes against Snowflake (schema: CUSTOMER_123)
   - Maps ResultSet to `List<CostSummaryDTO>`

5. Snowflake
   - Executes query with partition pruning (DATE filter)
   - Returns aggregated results

6. Response Path
   DAO → Service (adds business logic) → Controller (wraps in SuccessResponseDto) → HTTP Response

Summary​

Component Count:

  • 40 Controllers: Handle HTTP, validate input, delegate to services
  • 107 Services: Business logic, orchestration, data aggregation
  • 47 DAOs: Database queries, result mapping
  • 165 DTOs: Data transfer between layers
  • 10 Utilities: Common helper methods
  • Enums: Type-safe constants

Design Principles:

  • Separation of Concerns: Clear layer boundaries
  • Interface-Based: Services and DAOs defined as interfaces
  • DRY: AbstractCostBreakupController for common logic
  • Type Safety: Enums over strings
  • Security: All controllers secured with @Secured

Code Quality:

  • Testable: Interface-based design enables easy mocking
  • Maintainable: Consistent naming conventions
  • Scalable: Stateless services, connection pooling
  • Performant: Query optimization, caching

Related Documents:

Document Version: 1.0 Last Updated: October 25, 2025