Overview

Module: Lens Platform: Stormus Version: 1.0.0-RELEASE Last Updated: October 25, 2025 Spring Boot Version: 2.7.4 Java Version: 17

Executive Summary

AWS Lens is the comprehensive cost management, analytics, and reporting module within the Stormus platform. It provides deep insights into AWS cloud spending across 12+ service categories, manages Reserved Instance (RI) utilization and coverage, delivers customizable CUDOS dashboards, and generates detailed financial reports. With 40 REST controllers, 107 service classes, 165 data transfer objects, and 47 data access components, Lens processes billions of rows of cost data to deliver actionable insights that help organizations optimize their cloud spend by 20-40%.

Key Metrics:

Total Lines of Code: ~25,670
Controllers: 40 REST API controllers
Services: 107 service classes
DTOs: 165 data transfer objects
DAOs: 47 data access objects
API Endpoints: 100+ endpoints
Cost Breakup Categories: 12 AWS service categories
CUDOS Dashboards: 3 (S3, Data Transfer, Database)

Module Purpose & Business Value

Primary Purpose

AWS Lens serves as the centralized cost intelligence hub for multi-cloud environments, providing:

Cost Visibility - Real-time and historical cost analysis across all AWS services
Cost Optimization - Identify savings opportunities through RI management and resource optimization
Financial Reporting - Generate comprehensive reports for FinOps, chargebacks, and showbacks
Predictive Analytics - Trend analysis and cost forecasting
Governance & Compliance - Tag-based cost allocation and audit trails

Business Value

Cost Reduction: Identify and eliminate waste, saving 20-40% on cloud spend
Financial Planning: Accurate forecasting and budgeting with trend analysis
Accountability: Clear cost attribution through tags and account breakdowns
Decision Support: Data-driven insights for RI purchases and resource sizing
Compliance: Detailed audit trails and cost allocation reports

Target Users

FinOps Teams: Monitor spending, identify anomalies, generate financial reports
Engineering Teams: Understand service-level costs, optimize resource usage
Executives: High-level dashboards, cost trends, ROI analysis
Finance Teams: Invoicing, chargebacks, budget tracking

Key Features

1. Multi-Dimensional Cost Analysis

1.1 AWS vs Actual Cost Comparison

Feature: Compare AWS billed costs with actual resource usage costs
Controllers: AwsVsActualCostController
Use Case: Identify billing discrepancies, validate marketplace savings
Granularity: Account, service, region, resource-level
Time Range: Daily, weekly, monthly, custom date ranges

1.2 Cost Explorer

Feature: Interactive cost exploration with dynamic filtering
Controllers: CostExplorerController
Filters:
- Time period (hourly, daily, monthly)
- AWS service
- Region
- Account
- Tags
- Resource IDs
Visualizations: Line charts, bar charts, pie charts, tables

1.3 Cost Trends

Feature: Time-series analysis of spending patterns
Controllers: CostTrendsController
Analytics:
- Week-over-week growth
- Month-over-month comparison
- Year-over-year trends
- Seasonal patterns
- Anomaly detection

1.4 Account-Wise Breakup

Feature: Multi-account cost segmentation
Controllers: AccountWiseBreakupController, AccountWiseBreakupV2Controller
Capabilities:
- Organizational unit (OU) rollups
- Linked account analysis
- Cross-account cost attribution
- Hierarchical account structures

2. Reserved Instance (RI) Management

2.1 RI Tracking & Monitoring

Feature: Centralized Reserved Instance inventory
Controllers: ReservationController
Tracked Attributes:
- RI ID, type, instance family
- Payment option (No Upfront, Partial, All Upfront)
- Term (1yr, 3yr)
- Start/end dates
- Scope (Regional, Zonal)
- State (Active, Retired)

2.2 RI Utilization Analysis

Feature: Track how effectively RIs are being used
Controllers: ReservationUtilizationController
Metrics:
- Utilization percentage (0-100%)
- Unused RI hours
- On-Demand equivalent hours covered
- Cost savings realized
- Utilization alerts (<80% triggers notification)

2.3 RI Coverage Analysis

Feature: Identify coverage gaps for potential RI purchases
Controllers: RiCoverageController
Analysis:
- Percentage of usage covered by RIs
- Coverage by instance family
- Recommended RI purchases
- ROI calculations for new RIs
- Break-even analysis

2.4 RI Expiry Alerts

Feature: Proactive notifications for expiring reservations
Controllers: alertsapi/RiExpiryAlertController
Alert Rules:
- 90 days before expiry
- 60 days before expiry
- 30 days before expiry
- Automatic renewal recommendations
Channels: Email, Slack, Dashboard notifications

3. Service-Specific Cost Breakdowns

Lens provides detailed cost breakup for 12 AWS service categories, each with dedicated controllers and services:

3.1 Analytics Services

Services Covered: Kinesis Data Streams, EMR, Athena, Glue
Controllers: costbreakup/AnalyticsController
Cost Dimensions: Data ingestion, processing, storage, queries

3.2 Container Services

Services Covered: ECS, EKS, Fargate
Controllers: costbreakup/ContainersController
Cost Dimensions: Task execution, cluster management, data transfer

3.3 Database Services

Services Covered: RDS, DynamoDB, ElastiCache, Redshift, DocumentDB, OpenSearch
Controllers: costbreakup/DatabaseController
Cost Dimensions: Instance hours, storage, IOPS, backups, data transfer

3.4 Data Transfer Costs

Scope: Inter-AZ, inter-region, internet egress
Controllers: costbreakup/DataTransferController
Granularity: Source/destination breakdown, service-specific transfer

3.5 Compute Instance Costs

Services Covered: EC2, RDS instances, ElastiCache nodes
Controllers: costbreakup/InstanceCostController
Analysis: Instance type distribution, on-demand vs RI vs Spot

3.6 Management & Governance

Services Covered: CloudWatch (Logs, Metrics, Alarms, Dashboards)
Controllers: costbreakup/ManagementAndGovernanceController
Cost Tracking: Log ingestion, metric storage, alarm evaluations

3.7 Media Services

Services Covered: MediaLive, MediaConnect, MediaTailor
Controllers: costbreakup/MediaController
Cost Dimensions: Channel hours, throughput, ad insertion

3.8 Migration & Transfer Services

Services Covered: Database Migration Service (DMS)
Controllers: costbreakup/MigrationAndTransferController
Cost Tracking: Replication instance hours, data transfer

3.9 Networking & Content Delivery

Services Covered: CloudFront, API Gateway, Load Balancers, VPC
Controllers: costbreakup/NetworkingAndContentDeliveryController
Cost Dimensions: Requests, data transfer, LCU hours

3.10 Security Services

Services Covered: WAF, GuardDuty, Shield
Controllers: costbreakup/SecurityController
Cost Tracking: Rules processed, threats analyzed, DDoS protection

3.11 Serverless Services

Services Covered: Lambda, SQS, SES, SNS
Controllers: costbreakup/ServerlessController
Cost Dimensions: Invocations, duration, memory allocation, requests

3.12 Storage Services

Services Covered: S3, EBS (Volumes, Snapshots), EFS, Glacier
Controllers: costbreakup/StorageController
Cost Dimensions: Storage capacity, requests, data retrieval, storage class tiers

4. CUDOS (Cloud Usage Dashboards for Optimization & Savings)

Pre-built, industry-standard dashboards based on AWS best practices:

4.1 S3 Dashboard

Controller: cudos/S3DashboardController
Visualizations:
- Storage by bucket and storage class
- Request costs (GET, PUT, LIST)
- Data transfer costs (in/out)
- Lifecycle transition analysis
- Intelligent tiering effectiveness
Optimization Recommendations:
- Migrate to cheaper storage classes
- Enable lifecycle policies
- Delete orphaned objects

4.2 Data Transfer Dashboard

Controller: cudos/DataTransferDashboardController
Visualizations:
- Inter-AZ transfer costs
- Inter-region transfer costs
- Internet egress costs
- Transfer by service (EC2, RDS, S3, etc.)
- Top talkers (source/destination pairs)
Optimization Recommendations:
- Consolidate resources in single AZ
- Use VPC endpoints
- Implement caching (CloudFront)

4.3 Database Dashboard

Controller: cudos/DatabaseDashboardController
Coverage: RDS, ElastiCache, DynamoDB, Redshift
Visualizations:
- Database costs by engine and instance type
- Storage vs compute cost breakdown
- Backup and snapshot costs
- Utilization metrics (CPU, memory, IOPS)
Optimization Recommendations:
- Rightsize over-provisioned instances
- Enable auto-scaling (DynamoDB)
- Optimize backup retention

5. Reporting & Dashboards

5.1 Billing Console

Feature: Comprehensive billing dashboard
Controllers: BillingConsoleController
Components:
- Current month spend vs budget
- Top 10 cost drivers
- Service-level breakdown
- Account-level breakdown
- Historical comparison

5.2 Billing Summary Reports

Feature: Aggregated monthly/quarterly reports
Controllers: BillingSummaryController
Report Types:
- Executive summary (PDF)
- Detailed line-item report (CSV/Excel)
- Chargeback/showback reports
- Cost allocation by tags
Distribution: Email, S3, dashboard download

5.3 Tag-Based Reports

Feature: Cost attribution using AWS tags
Controllers: TagReportController
Tag Dimensions:
- Environment (prod, dev, staging)
- Team/department
- Project/application
- Cost center
- Custom tags
Analysis: Tag compliance, untagged resource identification

5.4 Daily Cost Reports

Feature: Automated daily cost summaries
Controllers: alertsapi/DailyReportController
Content:
- Yesterday's total spend
- Day-over-day change
- Top 5 cost changes
- Anomalies detected
Delivery: Email, Slack, webhook

6. Cost Alerting & Anomaly Detection

6.1 Cost Alerts

Feature: Threshold-based cost notifications
Controllers: alertsapi/CostAlertController
Alert Types:
- Budget threshold exceeded (50%, 80%, 100%, 120%)
- Spending anomaly detected (ML-based)
- Service-level spike (>50% increase)
- Account-level spike
Response Actions:
- Send notifications
- Trigger automation (optional)
- Create incident tickets

6.2 RI Utilization Alerts

Feature: Low RI utilization warnings
Controllers: alertsapi/RiUtilizationAlertController
Thresholds:
- Critical: <60% utilization
- Warning: <80% utilization
Actions: Notify FinOps team, suggest modifications

7. Optimization Recommendations

7.1 AWS Native Recommendations

Feature: AWS Cost Explorer recommendations integration
Controllers: RecommendationController
Recommendation Types:
- EC2 rightsizing (downsize over-provisioned instances)
- RDS rightsizing
- S3 storage class recommendations
- Reserved Instance purchase recommendations
- Savings Plans recommendations
Prioritization: By savings potential (high to low)

7.2 FinOps Recommendations

Feature: Custom FinOps best practices
Controllers: finops/FinOpsRecommendationController
Recommendations:
- Classic Load Balancer → ALB/NLB migration
- EBS volumes → EFS migration (for shared storage)
- On-Demand → Spot instances
- Idle resource detection (ELBs, EIPs, volumes)

7.3 Monthly Report Recommendations

Feature: Curated monthly optimization report
Controllers: monthlyreport/ReportRecommendationController
Content:
- Top 10 cost-saving opportunities
- Estimated annual savings
- Implementation difficulty (easy, medium, hard)
- Action items with owners

8. AWS Marketplace Integration

8.1 Marketplace Metering

Feature: Usage tracking for marketplace products
Controllers: marketplace/MarketPlaceController
Capabilities:
- Hourly usage reporting to AWS
- Custom pricing dimensions
- Subscription management
Use Case: CloudKeeper's own marketplace offering

9. Advanced Features

9.1 Saved Report Filters

Feature: Save complex filter combinations for reuse
Controllers: SavedReportFilterMetaController
Use Case: Create "Cost Center A - Production - Q1" saved view

9.2 Date Utilities

Feature: Flexible date range selection
Controllers: DatesController
Supported Ranges: Last 7 days, last 30 days, MTD, QTD, YTD, custom

9.3 Custom Query Processing

Feature: Optimize complex Snowflake queries
Integration: Uses queryprocessor module
Optimization: Query caching, parallel execution, result pagination

9.4 Async Processing

Feature: Background processing for heavy reports
Implementation: @EnableAsync in LensApplication.java:12
Use Case: Large Excel exports, multi-account aggregations

9.5 Intelligent Caching

Feature: Redis-based response caching
Implementation: @EnableCaching in LensApplication.java:14
TTL: 15 minutes for dashboard queries, 1 hour for filter metadata
Cache Keys: Account + date range + service

9.6 Automatic Retry

Feature: Resilient external API calls
Implementation: @EnableRetry in LensApplication.java:13
Retry Policy: 3 attempts, exponential backoff
Use Case: Snowflake connection failures, AWS API throttling

9.7 Job Scheduling

Feature: Scheduled data refresh jobs
Implementation: @EnableScheduling in LensApplication.java:15
Jobs:
- Daily cost ingestion (2 AM UTC)
- RI utilization refresh (hourly)
- Report generation (configurable)

Technology Stack Summary

Frameworks & Core Libraries

Technology	Version	Purpose
Spring Boot	2.7.4	Application framework
Spring Cloud	2021.0.8	Microservices infrastructure
Java	17	Programming language
Gradle	7.6	Build tool

Spring Modules Enabled

Spring Boot Starter Web - REST API support
Spring Boot Starter Data JPA - Relational database access
Spring Boot Starter Data MongoDB - NoSQL document storage
Spring Boot Starter Thymeleaf - Server-side HTML templating (for reports)
Spring Boot Actuator - Health checks, metrics
Spring Retry - Automatic retry logic
Spring Cache - Caching abstraction
Spring Scheduling - Scheduled task execution
Spring Data JPA Auditing - Entity auditing (created/modified timestamps)

Databases

Database	Purpose	Key Tables/Collections
Snowflake	Analytics data warehouse	COST_DAILY, COST_HOURLY, RI_UTILIZATION
MongoDB	Document storage	saved_reports, filter_metadata, custom_queries
Redis	In-memory cache	dashboard_cache, query_results
MySQL	Transactional data	accounts, users, billing_metadata

External Integrations

Integration	Library	Purpose
Snowflake	snowflake-jdbc:3.13.27	Query cost data warehouse
AWS SDK	aws-java-sdk:1.12.324	Fetch recommendations, RI data, Cost Explorer
RabbitMQ	spring-boot-starter-amqp	Async event processing
Spring Cloud Config	spring-cloud-starter-config	Centralized configuration

API Documentation

Tool	Version	Purpose
SpringDoc OpenAPI	1.6.12	Auto-generate API docs (Swagger UI)

Testing & Quality

Tool	Version	Purpose
JUnit Jupiter	5.x	Unit testing
Mockito	5.2.0	Mocking framework
JaCoCo	0.8.7	Code coverage
SonarQube	4.4.1.3373	Code quality analysis

Module Dependencies

Lens depends on the following internal modules:

Module	Purpose
snowplug	Snowflake multi-tenant datasource configuration
monitoring	Prometheus metrics, application monitoring
errorhandler	Centralized exception handling
loggerutil	Structured logging utilities

Quick Start Guide

Prerequisites

Java 17 or higher
Gradle 7.6 or higher
Snowflake account with cost data
MongoDB instance
Redis instance
RabbitMQ instance
Access to Spring Cloud Config Server

Running Lens Locally

# 1. Clone the repository
cd /home/ubuntu/repos/product/stormus/lens

# 2. Configure environment
export SNOWFLAKE_URL="jdbc:snowflake://your-account.snowflakecomputing.com"
export SNOWFLAKE_USER="your-username"
export SNOWFLAKE_PASSWORD="your-password"
export MONGODB_URI="mongodb://localhost:27017/lens"
export REDIS_HOST="localhost"
export RABBITMQ_HOST="localhost"
export CONFIG_SERVER_URL="http://localhost:8888"

# 3. Build the application
./gradlew clean build

# 4. Run the application
./gradlew bootRun

# Or run the JAR directly
java -jar build/libs/lens-1.0.0-RELEASE.jar

Accessing the API

Base URL: http://localhost:<port>

Swagger UI: http://localhost:<port>/swagger-ui.html

Health Check: http://localhost:<port>/actuator/health

Example API Call

# Get cost summary
curl -X GET "http://localhost:8080/admin-pages/cost/summary?accountId=123456789012&startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "auth-customer: customer-123"

Architecture Overview (High-Level)

┌─────────────────────────────────────────────────────────────┐
│                     AWS LENS MODULE                          │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────┐      ┌──────────────┐      ┌───────────┐ │
│  │              │      │              │      │           │ │
│  │ Controllers  │─────▶│   Services   │─────▶│    DAO    │ │
│  │   (40)       │      │    (107)     │      │    (47)   │ │
│  │              │      │              │      │           │ │
│  └──────────────┘      └──────────────┘      └───────────┘ │
│         │                     │                      │       │
│         │                     │                      │       │
│         ▼                     ▼                      ▼       │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              DTOs & Domain Models (165)              │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                               │
└─────────────────────────────────────────────────────────────┘
                           │
                           │ Integrates with
                           ▼
    ┌──────────────┬──────────────┬──────────────┬──────────┐
    │              │              │              │          │
    │  Snowflake   │   MongoDB    │     Redis    │  RabbitMQ│
    │  (Analytics) │ (Documents)  │   (Cache)    │ (Events) │
    │              │              │              │          │
    └──────────────┴──────────────┴──────────────┴──────────┘
                           │
                           │ Fetches data from
                           ▼
              ┌───────────────────────────┐
              │      AWS Services         │
              │  • Cost Explorer API      │
              │  • Pricing API            │
              │  • Organizations API      │
              └───────────────────────────┘

Key Statistics

Metric	Count	Details
Total Lines of Code	25,670	Java source files only
Controllers	40	REST API endpoints
Services	107	Business logic layer
DTOs	165	Data transfer objects
DAOs	47	Data access objects
API Endpoints	100+	Public REST APIs
Cost Breakup Categories	12	AWS service categories
CUDOS Dashboards	3	S3, Data Transfer, Database
Alert Types	4	Cost, RI expiry, RI utilization, daily
Dependencies (Internal)	4	snowplug, monitoring, errorhandler, loggerutil
Dependencies (External)	10+	Snowflake, AWS SDK, MongoDB, etc.

02-functional-architecture - Business capabilities and use cases
03-logical-architecture - Layer structure and design patterns
04-technical-architecture - Technology stack deep dive
05-component-design - Detailed controller, service, and DAO documentation
06-api-reference - Complete API documentation with examples
11-deployment-guide - How to deploy Lens
12-developer-guide - Contributing and development guidelines

Next Steps

Understand Architecture: Read 03-logical-architecture for layer structure
Explore APIs: Check 06-api-reference for endpoint documentation
Set Up Environment: Follow 11-deployment-guide for local setup
Start Contributing: Read 12-developer-guide for contribution guidelines

Lens Module Version: 1.0.0-RELEASE Documentation Version: 1.0 Last Updated: October 25, 2025

Executive Summary​

Module Purpose & Business Value​

Primary Purpose​

Business Value​

Target Users​

Key Features​

1. Multi-Dimensional Cost Analysis​

1.1 AWS vs Actual Cost Comparison​

1.2 Cost Explorer​

1.3 Cost Trends​

1.4 Account-Wise Breakup​

2. Reserved Instance (RI) Management​

2.1 RI Tracking & Monitoring​

2.2 RI Utilization Analysis​

2.3 RI Coverage Analysis​

2.4 RI Expiry Alerts​

3. Service-Specific Cost Breakdowns​

3.1 Analytics Services​

3.2 Container Services​

3.3 Database Services​

3.4 Data Transfer Costs​

3.5 Compute Instance Costs​

3.6 Management & Governance​

3.7 Media Services​

3.8 Migration & Transfer Services​

3.9 Networking & Content Delivery​

3.10 Security Services​

3.11 Serverless Services​

3.12 Storage Services​

4. CUDOS (Cloud Usage Dashboards for Optimization & Savings)​

4.1 S3 Dashboard​

4.2 Data Transfer Dashboard​

4.3 Database Dashboard​

5. Reporting & Dashboards​

5.1 Billing Console​

5.2 Billing Summary Reports​

5.3 Tag-Based Reports​

5.4 Daily Cost Reports​

6. Cost Alerting & Anomaly Detection​

6.1 Cost Alerts​

6.2 RI Utilization Alerts​

7. Optimization Recommendations​

7.1 AWS Native Recommendations​

7.2 FinOps Recommendations​

7.3 Monthly Report Recommendations​

8. AWS Marketplace Integration​

8.1 Marketplace Metering​

9. Advanced Features​

9.1 Saved Report Filters​

9.2 Date Utilities​

9.3 Custom Query Processing​

9.4 Async Processing​

9.5 Intelligent Caching​

9.6 Automatic Retry​

9.7 Job Scheduling​

Technology Stack Summary​

Frameworks & Core Libraries​

Spring Modules Enabled​

Databases​

External Integrations​

API Documentation​

Testing & Quality​

Module Dependencies​

Quick Start Guide​

Prerequisites​

Running Lens Locally​

Accessing the API​

Example API Call​

Architecture Overview (High-Level)​

Key Statistics​

Related Documentation​

Next Steps​