Logical Architecture

Module: Lens Platform: Stormus Version: 1.0.0-RELEASE Last Updated: October 25, 2025 Document Type: Logical Architecture (Component View)

Introduction
Architectural Layers
Component Diagram
Package Structure
Layer Responsibilities
Communication Patterns
Design Patterns
Module Dependencies
Cross-Cutting Concerns

Introduction

This document describes the logical architecture of the AWS Lens module, focusing on the structural organization of components, layers, and design patterns. It provides a developer's view of how the system is organized internally.

Purpose of This Document

Define architectural layers and their responsibilities
Document component structure and relationships
Explain design patterns and principles
Guide developers on where to add new features
Ensure architectural consistency

Architectural Style

Lens follows a Layered Architecture pattern with clear separation of concerns:

┌─────────────────────────────────────────────────────────────┐
│              Presentation Layer (Controllers)                │
│                     40 REST Controllers                      │
├─────────────────────────────────────────────────────────────┤
│            Application Layer (Services)                      │
│                  107 Service Classes                         │
├─────────────────────────────────────────────────────────────┤
│           Data Access Layer (DAOs & Repositories)            │
│                  47 DAO Classes + JPA Repos                  │
├─────────────────────────────────────────────────────────────┤
│          Data Transfer Layer (DTOs & Documents)              │
│               165 DTOs + MongoDB Documents                   │
├─────────────────────────────────────────────────────────────┤
│            Infrastructure Layer (Config, Utils)              │
│         Configuration + Utilities + Cross-Cutting            │
└─────────────────────────────────────────────────────────────┘

02-functional-architecture - Business capabilities and use cases
04-technical-architecture - Technology stack and integrations
05-component-design - Detailed component documentation

Architectural Layers

Layer 1: Presentation Layer (Controllers)

Responsibility: HTTP request handling, input validation, response formatting

Components: 40 REST Controllers

Package: com.ttn.ck.lens.controller

Key Characteristics:

Stateless: Controllers do not maintain state
Thin: Minimal business logic, delegate to service layer
RESTful: Follow REST API conventions
Secured: All endpoints annotated with @Secured
Validated: Input validation via @Valid and BindingResult

Controller Categories:

Core Controllers (14): Base cost management endpoints
Alert Controllers (5): Located in controller/alertsapi
Cost Breakup Controllers (13): Located in controller/costbreakup
CUDOS Controllers (3): Located in controller/cudos
FinOps Controllers (1): Located in controller/finops
Marketplace Controllers (1): Located in controller/marketplace
Monthly Report Controllers (2): Located in controller/monthlyreport

Responsibilities:

Receive HTTP requests
Validate input using @Valid annotations
Call appropriate service methods
Wrap responses in ResponseDto (success/error)
Handle HTTP status codes
Return JSON responses

Not Responsible For:

Business logic execution
Database queries
External API calls
Complex calculations

Layer 2: Application Layer (Services)

Responsibility: Business logic, orchestration, transaction management

Components: 107 Service Classes (interfaces + implementations)

Package: com.ttn.ck.lens.service (interfaces), com.ttn.ck.lens.service.impl (implementations)

Key Characteristics:

Interface-based: Services defined as interfaces, implementations separate
Transactional: Use @Transactional where needed
Orchestration: Coordinate multiple DAOs and external services
Business Rules: Implement all business logic
Testable: Easy to mock for unit testing

Service Categories:

Core Services: AwsVsActualCostService, BillingConsoleService, etc.
Cost Breakup Services: 12 categories (Analytics, Containers, Database, etc.)
CUDOS Services: S3Dashboard, DataTransferDashboard, DatabaseDashboard
Utility Services: DatesService, RecommendationService, etc.

Subpackage Structure:

service/
├── (interfaces)                    # Service interfaces
├── impl/                           # Core implementations
│   ├── billingsummary/             # Billing summary services
│   └── costbreakup/                # Cost breakup services
│       ├── analytics/
│       ├── containers/
│       ├── database/
│       ├── datatransfer/
│       ├── instance/
│       ├── managementandgovernance/
│       ├── media/
│       ├── migrationandtransfer/
│       ├── networkingandcontent/
│       ├── security/
│       ├── serverless/
│       └── storage/

Responsibilities:

Execute business logic
Validate business rules
Aggregate data from multiple DAOs
Transform DTOs
Call external APIs (AWS SDK, Feign clients)
Cache results (when appropriate)
Handle exceptions and retries

Not Responsible For:

HTTP request/response handling
SQL query construction
Direct database access
UI concerns

Layer 3: Data Access Layer (DAOs & Repositories)

Responsibility: Database queries, data persistence, external data sources

Components: 47 DAO Classes + JPA Repositories

Packages:

com.ttn.ck.lens.dao (interfaces)
com.ttn.ck.lens.dao.impl (implementations)
com.ttn.ck.lens.repo (JPA repositories)
com.ttn.ck.lens.queries (SQL query classes)

Key Characteristics:

Data Source Abstraction: Hide database implementation details
Query Optimization: Efficient SQL queries
Multi-Database: Support Snowflake, MongoDB, MySQL
Result Mapping: Map database rows to DTOs

DAO Categories:

Snowflake DAOs: Cost data queries (primary data source)
MongoDB Repositories: Document storage (saved reports, filters)
JPA Repositories: Transactional data (MySQL)

Subpackage Structure:

dao/
├── (interfaces)                    # DAO interfaces
├── impl/                           # Snowflake DAO implementations
├── cudos/                          # CUDOS-specific DAOs
└── marketplace/                    # Marketplace DAOs

repo/                                # JPA & Mongo repositories

queries/                             # SQL query classes
├── costbreakup/
├── cudos/
└── marketplace/

Responsibilities:

Execute Snowflake SQL queries
Map result sets to DTOs
Handle database connections
Query optimization
Pagination
Caching query results

Not Responsible For:

Business logic
Data transformation (beyond mapping)
HTTP handling

Layer 4: Data Transfer Layer (DTOs & Documents)

Responsibility: Data structures for transferring data between layers

Components: 165 DTOs + MongoDB Documents

Packages:

com.ttn.ck.lens.dto (Data Transfer Objects for API)
com.ttn.ck.lens.document (MongoDB documents)

Key Characteristics:

Immutability: DTOs should be immutable (use @Data for Lombok)
Validation Annotations: Use JSR-303 annotations (@NotNull, @Size, etc.)
Serializable: Support JSON serialization
Flat Structure: Avoid deep nesting

DTO Categories:

dto/
├── AwsVsActualCost/                # Cost comparison DTOs
├── accountwisebreakup/             # Account breakup DTOs
├── billingconsole/                 # Billing console DTOs
├── billingsummary/                 # Billing summary DTOs
├── costalert/                      # Cost alert DTOs
├── costbreakup/                    # Cost breakup DTOs (12 categories)
├── costexplorer/                   # Cost explorer DTOs
├── costtrends/                     # Cost trends DTOs
├── cudos/                          # CUDOS dashboard DTOs
├── recommendation/                 # Recommendation DTOs
├── reservation/                    # Reservation DTOs
├── ricoverage/                     # RI coverage DTOs
├── riexpiry/                       # RI expiry DTOs
└── GenericRequestDTO.java          # Common request DTO

Responsibilities:

Define data contracts between layers
Input validation (request DTOs)
Response formatting (response DTOs)
JSON serialization/deserialization
Field-level validation

Not Responsible For:

Business logic
Database operations
HTTP handling

Layer 5: Infrastructure Layer (Config, Utils, Cross-Cutting)

Responsibility: Configuration, utilities, cross-cutting concerns

Components: Configuration classes, utilities, caching, listeners

Packages:

com.ttn.ck.lens.config (Configuration classes)
com.ttn.ck.lens.utils (Utility classes)
com.ttn.ck.lens.cache (Caching logic)
com.ttn.ck.lens.listner (Event listeners)
com.ttn.ck.lens.enums (Enumerations)
com.ttn.ck.lens.clients (External service clients - Feign)

Key Characteristics:

Reusable: Used across all layers
Stateless: Most utilities are stateless
Configuration: Externalized via Spring Cloud Config

Subpackages:

config/                              # Spring configuration
  ├── SnowflakeConfig.java
  ├── MongoConfig.java
  ├── RedisConfig.java
  └── RabbitMQConfig.java

utils/                               # Utility classes
  ├── ApplicationConstants.java      # 660+ constants
  ├── ApplicationUtils.java          # Common utilities
  ├── ColumnNameConstants.java       # Database column names
  ├── QueueConstants.java            # RabbitMQ constants
  ├── SortUtils.java                 # Sorting utilities
  └── AccountWiseBreakUpReportGenerator.java

cache/                               # Caching logic
  └── CacheConfiguration.java

listner/                             # Event listeners
  └── MessageQueueListener.java      # RabbitMQ consumer

clients/                             # Feign clients
  └── AwsRecommendationClient.java   # AWS Cost Explorer API

enums/                               # Enumerations
  ├── costbreakup/
  └── cudos/

Responsibilities:

Application configuration
Common utilities (date, string, sorting)
Constants management
Caching configuration
Event processing (RabbitMQ listeners)
External API clients (Feign)

Not Responsible For:

Business logic
Direct database access

Component Diagram

High-Level Component View

┌───────────────────────────────────────────────────────────────────┐
│                        LENS MODULE                                 │
│                                                                    │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │            PRESENTATION LAYER (Controllers)                 │  │
│  │                                                              │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │  │
│  │  │    Core      │  │   Alerts     │  │ CostBreakup  │    │  │
│  │  │ Controllers  │  │ Controllers  │  │ Controllers  │    │  │
│  │  │    (14)      │  │     (5)      │  │    (13)      │    │  │
│  │  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘    │  │
│  │         │                  │                  │             │  │
│  └─────────┼──────────────────┼──────────────────┼─────────────┘  │
│            │                  │                  │                 │
│            └──────────────────┴──────────────────┘                 │
│                               │                                    │
│  ┌────────────────────────────┼────────────────────────────────┐  │
│  │      APPLICATION LAYER (Services)              │            │  │
│  │                                                 ▼            │  │
│  │  ┌─────────────┐  ┌──────────────┐  ┌────────────────────┐│  │
│  │  │    Core     │  │ CostBreakup  │  │   CUDOS Services   ││  │
│  │  │  Services   │  │  Services    │  │                    ││  │
│  │  │    (20)     │  │    (60+)     │  │       (3)          ││  │
│  │  └─────┬───────┘  └──────┬───────┘  └────────┬───────────┘│  │
│  │        │                  │                    │            │  │
│  └────────┼──────────────────┼────────────────────┼────────────┘  │
│           │                  │                    │                │
│           └──────────────────┴────────────────────┘                │
│                              │                                     │
│  ┌───────────────────────────┼──────────────────────────────────┐ │
│  │       DATA ACCESS LAYER (DAOs & Repositories)  │             │ │
│  │                                                 ▼             │ │
│  │  ┌───────────────┐  ┌────────────────┐  ┌────────────────┐ │ │
│  │  │  Snowflake    │  │    MongoDB     │  │   JPA Repos    │ │ │
│  │  │     DAOs      │  │  Repositories  │  │    (MySQL)     │ │ │
│  │  │     (35+)     │  │      (5)       │  │      (7)       │ │ │
│  │  └───────┬───────┘  └────────┬───────┘  └────────┬───────┘ │ │
│  │          │                    │                    │         │ │
│  └──────────┼────────────────────┼────────────────────┼─────────┘ │
│             │                    │                    │           │
│             ▼                    ▼                    ▼           │
│  ┌──────────────────────────────────────────────────────────────┐│
│  │                    DATA SOURCES                               ││
│  │  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌────────┐ ││
│  │  │Snowflake │    │ MongoDB  │    │  MySQL   │    │ Redis  │ ││
│  │  │Analytics │    │Documents │    │Transaction│   │ Cache  │ ││
│  │  └──────────┘    └──────────┘    └──────────┘    └────────┘ ││
│  └──────────────────────────────────────────────────────────────┘│
│                                                                    │
│  ┌──────────────────────────────────────────────────────────────┐│
│  │              EXTERNAL INTEGRATIONS                            ││
│  │  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌────────┐ ││
│  │  │ AWS SDK  │    │ RabbitMQ │    │  Config  │    │ AuthX  │ ││
│  │  │(Feign)   │    │ (AMQP)   │    │  Server  │    │ (JWT)  │ ││
│  │  └──────────┘    └──────────┘    └──────────┘    └────────┘ ││
│  └──────────────────────────────────────────────────────────────┘│
└───────────────────────────────────────────────────────────────────┘

Package Structure

Complete Package Hierarchy

com.ttn.ck.lens/
│
├── LensApplication.java                 # Main Spring Boot application
│
├── controller/                          # Presentation Layer (40 controllers)
│   ├── AwsVsActualCostController.java
│   ├── BillingConsoleController.java
│   ├── BillingSummaryController.java
│   ├── CostExplorerController.java
│   ├── CostTrendsController.java
│   ├── DatesController.java
│   ├── RecommendationController.java
│   ├── ReservationController.java
│   ├── ReservationUtilizationController.java
│   ├── RiCoverageController.java
│   ├── SavedReportFilterMetaController.java
│   ├── TagReportController.java
│   ├── AccountWiseBreakupController.java
│   ├── AccountWiseBreakupV2Controller.java
│   │
│   ├── alertsapi/                       # Alert controllers (5)
│   │   ├── AccountsDatesController.java
│   │   ├── CostAlertController.java
│   │   ├── DailyReportController.java
│   │   ├── RiExpiryAlertController.java
│   │   └── RiUtilizationAlertController.java
│   │
│   ├── costbreakup/                     # Cost breakup controllers (13)
│   │   ├── AbstractCostBreakupController.java
│   │   ├── AnalyticsController.java
│   │   ├── ContainersController.java
│   │   ├── DatabaseController.java
│   │   ├── DataTransferController.java
│   │   ├── InstanceCostController.java
│   │   ├── ManagementAndGovernanceController.java
│   │   ├── MediaController.java
│   │   ├── MigrationAndTransferController.java
│   │   ├── NetworkingAndContentDeliveryController.java
│   │   ├── SecurityController.java
│   │   ├── ServerlessController.java
│   │   └── StorageController.java
│   │
│   ├── cudos/                           # CUDOS controllers (3)
│   │   ├── DataTransferDashboardController.java
│   │   ├── S3DashboardController.java
│   │   └── DatabaseDashboardController.java
│   │
│   ├── finops/                          # FinOps controller (1)
│   │   └── FinOpsRecommendationController.java
│   │
│   ├── marketplace/                     # Marketplace controller (1)
│   │   └── MarketPlaceController.java
│   │
│   └── monthlyreport/                   # Monthly report controllers (2)
│       ├── MonthlyReportAccountDates.java
│       └── ReportRecommendationController.java
│
├── service/                             # Application Layer (107 services)
│   ├── (Interface files)                # Service interfaces
│   │   ├── AwsVsActualCostService.java
│   │   ├── BillingConsoleService.java
│   │   ├── BillingSummaryService.java
│   │   ├── CostExplorerService.java
│   │   ├── CostTrendsService.java
│   │   ├── RecommendationService.java
│   │   ├── ReservationService.java
│   │   └── ... (20+ core service interfaces)
│   │
│   └── impl/                            # Service implementations
│       ├── AwsVsActualCostServiceImpl.java
│       ├── BillingConsoleServiceImpl.java
│       ├── BillingSummaryServiceImpl.java
│       ├── CostExplorerServiceImpl.java
│       ├── CostTrendsServiceImpl.java
│       ├── ... (20+ core implementations)
│       │
│       ├── billingsummary/              # Billing summary services
│       │   └── ... (billing services)
│       │
│       └── costbreakup/                 # Cost breakup services (60+)
│           ├── analytics/
│           │   ├── AnalyticsService.java
│           │   ├── AnalyticsServiceImpl.java
│           │   ├── KinesisService.java
│           │   └── EmrService.java
│           │
│           ├── containers/
│           │   ├── ContainersService.java
│           │   ├── EcsService.java
│           │   ├── EksService.java
│           │   └── FargateService.java
│           │
│           ├── database/
│           │   ├── DatabaseService.java
│           │   ├── RdsService.java
│           │   ├── DynamoDbService.java
│           │   ├── ElastiCacheService.java
│           │   └── RedshiftService.java
│           │
│           ├── datatransfer/
│           ├── instance/
│           ├── managementandgovernance/
│           ├── media/
│           ├── migrationandtransfer/
│           ├── networkingandcontent/
│           ├── security/
│           ├── serverless/
│           └── storage/
│
├── dao/                                 # Data Access Layer (47 DAOs)
│   ├── (Interface files)                # DAO interfaces
│   │   ├── AwsVsActualCostDao.java
│   │   ├── BillingConsoleDao.java
│   │   ├── CostExplorerDao.java
│   │   └── ... (35+ DAO interfaces)
│   │
│   ├── impl/                            # DAO implementations
│   │   ├── AwsVsActualCostDaoImpl.java
│   │   ├── BillingConsoleDaoImpl.java
│   │   └── ... (35+ implementations)
│   │
│   ├── cudos/                           # CUDOS DAOs
│   │   ├── S3DashboardDao.java
│   │   ├── DataTransferDashboardDao.java
│   │   └── DatabaseDashboardDao.java
│   │
│   └── marketplace/                     # Marketplace DAOs
│       └── MarketPlaceDao.java
│
├── queries/                             # SQL Query Classes
│   ├── costbreakup/
│   │   ├── AnalyticsQueries.java
│   │   ├── DatabaseQueries.java
│   │   ├── StorageQueries.java
│   │   └── ... (12 query classes)
│   │
│   ├── cudos/
│   │   ├── S3Queries.java
│   │   ├── DataTransferQueries.java
│   │   └── DatabaseQueries.java
│   │
│   └── marketplace/
│       └── MarketPlaceQueries.java
│
├── dto/                                 # Data Transfer Layer (165 DTOs)
│   ├── GenericRequestDTO.java           # Common request DTO
│   ├── AwsVsActualCost/
│   ├── accountwisebreakup/
│   ├── billingconsole/
│   ├── billingsummary/
│   ├── costalert/
│   ├── costbreakup/                     # 12 subcategories
│   ├── costexplorer/
│   ├── costtrends/
│   ├── cudos/
│   ├── recommendation/
│   ├── reservation/
│   ├── ricoverage/
│   └── riexpiry/
│
├── document/                            # MongoDB Documents
│   ├── SavedReportDocument.java
│   ├── FilterMetadataDocument.java
│   └── CustomQueryDocument.java
│
├── repo/                                # JPA & MongoDB Repositories
│   ├── SavedReportRepository.java       # MongoDB
│   ├── FilterMetadataRepository.java    # MongoDB
│   └── ... (7 repositories)
│
├── config/                              # Configuration Classes
│   ├── SnowflakeConfig.java
│   ├── MongoConfig.java
│   ├── RedisConfig.java
│   ├── RabbitMQConfig.java
│   ├── CacheConfig.java
│   └── SwaggerConfig.java
│
├── utils/                               # Utility Classes
│   ├── ApplicationConstants.java        # 660+ constants
│   ├── ApplicationUtils.java
│   ├── ColumnNameConstants.java
│   ├── QueueConstants.java
│   ├── HourlyDataConverter.java
│   ├── SequenceGenerationUtil.java
│   ├── SortUtils.java
│   ├── StrReplaceForMongoUtils.java
│   ├── UtilityService.java
│   └── AccountWiseBreakUpReportGenerator.java
│
├── cache/                               # Caching Logic
│   └── CacheConfiguration.java
│
├── listner/                             # Event Listeners
│   └── MessageQueueListener.java        # RabbitMQ consumer
│
├── clients/                             # External Service Clients
│   └── AwsRecommendationClient.java     # Feign client
│
└── enums/                               # Enumerations
    ├── costbreakup/
    │   ├── AnalyticsServiceEnum.java
    │   ├── DatabaseServiceEnum.java
    │   └── ... (12 enum files)
    └── cudos/
        └── CudosServiceEnum.java

Layer Responsibilities

Request Flow Through Layers

Example: Get Cost Summary Request

1. HTTP Request
   ↓
2. AwsVsActualCostController.getAwsAndActualCostSummary()
   - Validates input (@Valid GenericRequestDTO)
   - Security check (@Secured annotation)
   ↓
3. AwsVsActualCostService.getCostSummary()
   - Business logic: Date range validation
   - Calls DAO layer
   - Aggregates results
   - Calculates savings percentage
   ↓
4. AwsVsActualCostDao.queryCostData()
   - Builds Snowflake SQL query
   - Executes query
   - Maps ResultSet to DTOs
   ↓
5. Snowflake Database
   - Executes query
   - Returns result set
   ↓
6. (Return path - up the stack)
   DAO → Service → Controller → HTTP Response

Separation of Concerns:

Controller: "What data did the user request?" (routing)
Service: "How do we process this business logic?" (orchestration)
DAO: "How do we fetch this data?" (persistence)
DTO: "What does the data look like?" (structure)

Communication Patterns

1. Synchronous Request-Response

Pattern: Controller → Service → DAO → Database → Response

Used For: Most API endpoints (cost queries, dashboards, reports)

Example:

// Controller
@GetMapping("/cost/summary")
public ResponseDto<`List<CostSummaryDTO>`> getCostSummary(@Valid GenericRequestDTO request) {
    return new SuccessResponseDto<>(awsVsActualCostService.getCostSummary(request));
}

// Service
public `List<CostSummaryDTO>` getCostSummary(GenericRequestDTO request) {
    // Business logic
    return awsVsActualCostDao.queryCostSummary(request);
}

// DAO
public `List<CostSummaryDTO>` queryCostSummary(GenericRequestDTO request) {
    // SQL query execution
    return jdbcTemplate.query(sql, rowMapper);
}

Characteristics:

Blocking (request waits for response)
Simple to debug
Works for fast queries (<2 seconds)

2. Asynchronous Processing

Pattern: Controller → Service → @Async Method → Background Thread → Database

Used For: Heavy reports, large exports, batch processing

Implementation:

// LensApplication.java:12
@EnableAsync

// Service
@Async
public `CompletableFuture<File>` generateLargeReport(ReportDTO request) {
    // Heavy processing in background
    File report = reportGenerator.generate(request);
    return CompletableFuture.completedFuture(report);
}

// Controller
@GetMapping("/export")
public `ResponseEntity<String>` exportReport(@Valid ReportDTO request) {
    `CompletableFuture<File>` future = service.generateLargeReport(request);
    return ResponseEntity.accepted().body("Report generation started. ID: " + jobId);
}

Characteristics:

Non-blocking (controller returns immediately)
Used for long-running operations (>5 seconds)
Improves user experience (no timeout)

3. Caching Pattern

Pattern: Request → Check Cache → Cache Hit? → Return Cached Data : Fetch from DB → Store in Cache → Return

Used For: Frequently accessed, slowly-changing data (filter metadata, static queries)

Implementation:

// LensApplication.java:14
@EnableCaching

// Service
@Cacheable(value = "filterMetadata", key = "#customerId")
public FilterMetadataDTO getFilterMetadata(String customerId) {
    // Expensive database query
    return dao.queryFilterMetadata(customerId);
}

@CacheEvict(value = "filterMetadata", key = "#customerId")
public void updateFilterMetadata(String customerId, FilterMetadataDTO metadata) {
    dao.updateMetadata(customerId, metadata);
}

Cache Configuration:

Backend: Redis
TTL: 15 minutes (dashboard queries), 1 hour (filter metadata)
Eviction: LRU (Least Recently Used)
Size: 1000 entries max

Characteristics:

Reduces database load
Faster response times (cache hit: <10ms vs DB query: 500ms)
Cache invalidation on updates

4. Event-Driven (Message Queue)

Pattern: Service → Publish Message → RabbitMQ → Consumer → Process Event

Used For: Cost data updates, alert generation, async notifications

Implementation:

// Publisher (Service)
public void publishCostUpdateEvent(CostUpdateDTO update) {
    rabbitTemplate.convertAndSend(QueueConstants.COST_UPDATE_EXCHANGE,
                                   QueueConstants.COST_UPDATE_ROUTING_KEY,
                                   update);
}

// Consumer (Listener)
@RabbitListener(queues = QueueConstants.COST_UPDATE_QUEUE)
public void handleCostUpdate(CostUpdateDTO update) {
    // Process cost update
    // Invalidate caches
    // Trigger alerts if needed
}

Queues Used:

cost.update - Cost data updated
alert.cost - Cost alert triggered
report.generated - Report generation complete

Characteristics:

Decoupled (publisher doesn't wait for consumer)
Reliable (messages persisted in RabbitMQ)
Scalable (multiple consumers)

5. Retry Pattern

Pattern: Service → Call External API → Failure? → Retry (exponential backoff)

Used For: External API calls (AWS SDK, Snowflake connections)

Implementation:

// LensApplication.java:13
@EnableRetry

// Service
@Retryable(
    value = {SnowflakeConnectionException.class},
    maxAttempts = 3,
    backoff = @Backoff(delay = 1000, multiplier = 2)
)
public `List<CostDTO>` queryCostData(RequestDTO request) {
    return dao.queryCostData(request);
}

@Recover
public `List<CostDTO>` recover(SnowflakeConnectionException ex, RequestDTO request) {
    log.error("Failed to query cost data after 3 retries", ex);
    throw new GenericException("Unable to fetch cost data. Please try again later.");
}

Retry Configuration:

Max Attempts: 3
Initial Delay: 1 second
Backoff Multiplier: 2x (1s, 2s, 4s)
Recoverable Exceptions: SnowflakeConnectionException, AwsApiThrottlingException

Characteristics:

Resilient to transient failures
Exponential backoff prevents overwhelming failed service
Recovery method provides graceful degradation

Design Patterns

1. Layered Architecture

Description: Clear separation of concerns into horizontal layers

Implementation: Controller → Service → DAO → Database

Benefits:

Easy to understand
Easy to test (mock each layer)
Easy to maintain
Enforces separation of concerns

2. Interface-Based Design (Dependency Inversion)

Description: Services and DAOs defined as interfaces, implementations injected

Implementation:

// Interface
public interface AwsVsActualCostService {
    `List<CostSummaryDTO>` getCostSummary(GenericRequestDTO request);
}

// Implementation
@Service
public class AwsVsActualCostServiceImpl implements AwsVsActualCostService {
    @Override
    public `List<CostSummaryDTO>` getCostSummary(GenericRequestDTO request) {
        // Implementation
    }
}

// Controller (dependency injection)
@AllArgsConstructor
public class AwsVsActualCostController {
    private final AwsVsActualCostService service; // Interface, not implementation
}

Benefits:

Easy to mock for testing
Easy to swap implementations
Loose coupling

3. DTO Pattern (Data Transfer Object)

Description: Dedicated objects for transferring data between layers

Implementation: Separate DTO classes for request, response, database entities

Benefits:

Decouples layers
Allows different representations (API vs DB)
Input validation

4. Template Method Pattern (Abstract Controllers)

Description: Abstract base class with common controller logic

Implementation:

// AbstractCostBreakupController.java
public abstract class AbstractCostBreakupController {
    protected ResponseDto<CostBreakupDTO> getCostBreakup(RequestDTO request) {
        // Common validation
        // Common error handling
        // Call abstract method
        CostBreakupDTO data = fetchCostData(request);
        return new SuccessResponseDto<>(data);
    }

    protected abstract CostBreakupDTO fetchCostData(RequestDTO request);
}

// AnalyticsController extends AbstractCostBreakupController
@Override
protected CostBreakupDTO fetchCostData(RequestDTO request) {
    return analyticsService.getAnalyticsCostBreakup(request);
}

Benefits:

Code reuse
Consistent behavior across cost breakup controllers
Easy to add new cost breakup categories

5. Repository Pattern (JPA & MongoDB)

Description: Abstract data access logic behind repository interfaces

Implementation:

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

Benefits:

Standardized data access
Spring Data JPA generates implementations
Easy to switch databases

6. Strategy Pattern (Cost Breakup Services)

Description: Different algorithms for different cost breakup categories

Implementation: Each cost breakup service (Analytics, Database, Storage) implements same interface but with different logic

Benefits:

Extensible (easy to add new AWS services)
Clean separation

7. Builder Pattern (Query Construction)

Description: Fluent API for building complex SQL queries

Implementation:

String sql = QueryBuilder.select()
    .from("COST_DAILY")
    .where("ACCOUNT_ID", accountId)
    .where("DATE BETWEEN", startDate, endDate)
    .groupBy("SERVICE")
    .orderBy("COST DESC")
    .build();

Benefits:

Readable query construction
Type-safe

Module Dependencies

Internal Module Dependencies

Lens depends on 4 internal Stormus modules:

1. snowplug

Purpose: Snowflake multi-tenant datasource configuration

Usage: Provides Snowflake connection pooling and multi-tenant schema routing

Dependency:

api project(":snowplug")

Integration:

@Autowired
private SnowflakeJdbcTemplate snowflakeTemplate;

public `List<CostDTO>` queryCosts(String customerId) {
    // snowplug automatically routes to customer's schema
    return snowflakeTemplate.query(sql, rowMapper, customerId);
}

2. monitoring

Purpose: Prometheus metrics, application monitoring

Usage: Exposes metrics for cost query latency, cache hit rates, API calls

Dependency:

api project(":monitoring")

Integration:

@Autowired
private MeterRegistry meterRegistry;

public `List<CostDTO>` queryCosts(RequestDTO request) {
    Timer.Sample sample = Timer.start(meterRegistry);
    `List<CostDTO>` result = dao.queryCosts(request);
    sample.stop(meterRegistry.timer("lens.query.cost.duration"));
    return result;
}

Metrics Exposed:

lens.query.cost.duration - Cost query latency
lens.cache.hit.rate - Cache hit percentage
lens.api.requests - API request count by endpoint

3. errorhandler

Purpose: Centralized exception handling

Usage: Consistent error responses across all Lens endpoints

Dependency:

api project(":errorhandler")

Integration:

// errorhandler provides @ControllerAdvice for global exception handling

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(GenericException.class)
    public `ResponseEntity<ErrorResponseDto>` handleGenericException(GenericException ex) {
        return ResponseEntity.status(500).body(new ErrorResponseDto(ex.getMessage()));
    }
}

Error Response Format:

{
  "status": "error",
  "code": 500,
  "message": "Unable to fetch cost data",
  "timestamp": "2025-10-25T18:30:00Z"
}

4. loggerutil

Purpose: Structured logging utilities

Usage: Consistent log formatting, correlation IDs, log levels

Dependency:

api project(":loggerutil")

Integration:

import com.ttn.ck.loggerutil.Logger;

private static final Logger log = Logger.getLogger(AwsVsActualCostService.class);

public `List<CostDTO>` getCostSummary(RequestDTO request) {
    log.info("Fetching cost summary for customer: {}, date range: {} - {}",
             request.getCustomerId(), request.getStartDate(), request.getEndDate());
    // ...
}

Log Format:

2025-10-25 18:30:00.123 INFO [lens-api] [request-id-123] [customer-456] AwsVsActualCostService - Fetching cost summary for customer: 456, date range: 2024-01-01 - 2024-01-31

External Module Dependencies

See 04-technical-architecture for detailed external dependency information.

Key External Dependencies:

Snowflake JDBC (3.13.27)
AWS Java SDK (1.12.324)
Spring Boot (2.7.4)
Spring Cloud (2021.0.8)
MongoDB
Redis
RabbitMQ

Cross-Cutting Concerns

1. Security

Implementation: All controllers secured with @Secured annotation

Location: com.ttn.ck.authX (external module)

Mechanism: JWT token validation

Example:

@Secured(key = "LENS_AWSVSACTUALCOSTCONTROLLER")
public class AwsVsActualCostController {
    // All endpoints in this controller require valid JWT with appropriate permissions
}

Security Flow:

Client sends JWT token in Authorization header
authX module validates token
Extracts user context (customer ID, roles)
Checks if user has permission for controller
Allows/denies request

2. Logging

Implementation: Structured logging via loggerutil module

Log Levels:

ERROR: Exceptions, failures
WARN: Anomalies, deprecated usage
INFO: Business events (queries, reports)
DEBUG: Detailed debug information

Correlation ID: Every request has unique ID for tracing across services

3. Monitoring

Implementation: Prometheus metrics via monitoring module

Metrics Categories:

Request Metrics: Count, latency, errors
Cache Metrics: Hit rate, miss rate, evictions
Database Metrics: Query duration, connection pool usage
Business Metrics: Cost queries per customer, report generations

Dashboards: Grafana dashboards for real-time monitoring

4. Caching

Implementation: Redis via Spring Cache

Cache Strategies:

Filter Metadata: 1 hour TTL (rarely changes)
Dashboard Queries: 15 minutes TTL (changes daily)
RI Data: 1 hour TTL (changes hourly)

Cache Eviction: Automatic on updates + scheduled cleanup

5. Error Handling

Implementation: Global exception handler via errorhandler module

Exception Types:

GenericException: Business logic errors
SnowflakeConnectionException: Database connectivity
AwsApiException: AWS API failures
ValidationException: Input validation errors

Error Response: Consistent JSON format with status, code, message

6. Validation

Implementation: JSR-303 Bean Validation

Location: DTO classes

Example:

public class GenericRequestDTO {
    @NotNull(message = "Customer ID is required")
    private String customerId;

    @NotNull(message = "Start date is required")
    @PastOrPresent(message = "Start date cannot be in future")
    private LocalDate startDate;

    @NotNull(message = "End date is required")
    private LocalDate endDate;

    @AssertTrue(message = "End date must be after start date")
    public boolean isDateRangeValid() {
        return endDate.isAfter(startDate);
    }
}

7. Configuration Management

Implementation: Spring Cloud Config

Externalized Properties:

Database credentials
API endpoints
Feature flags
Cache TTLs

Configuration Profiles: dev, uat, prod

Summary

The AWS Lens module follows a Layered Architecture with clear separation of concerns:

40 Controllers (Presentation Layer): Handle HTTP, validate input, return responses
107 Services (Application Layer): Execute business logic, orchestrate DAOs
47 DAOs (Data Access Layer): Query databases, map results to DTOs
165 DTOs (Data Transfer Layer): Define data contracts
Infrastructure Layer: Configuration, utilities, cross-cutting concerns

Communication Patterns: Synchronous request-response, asynchronous processing, caching, event-driven (RabbitMQ), retry

Design Patterns: Layered Architecture, Interface-Based Design, DTO Pattern, Template Method, Repository, Strategy, Builder

Module Dependencies: 4 internal modules (snowplug, monitoring, errorhandler, loggerutil)

Cross-Cutting Concerns: Security, logging, monitoring, caching, error handling, validation, configuration

Next Steps:

04-technical-architecture - Technology stack deep dive
05-component-design - Detailed component documentation
06-api-reference - Complete API documentation

Document Version: 1.0 Last Updated: October 25, 2025

Table of Contents​

Introduction​

Purpose of This Document​

Architectural Style​

Related Documents​

Architectural Layers​

Layer 1: Presentation Layer (Controllers)​

Layer 2: Application Layer (Services)​

Layer 3: Data Access Layer (DAOs & Repositories)​

Layer 4: Data Transfer Layer (DTOs & Documents)​

Layer 5: Infrastructure Layer (Config, Utils, Cross-Cutting)​

Component Diagram​

High-Level Component View​

Package Structure​

Complete Package Hierarchy​

Layer Responsibilities​

Request Flow Through Layers​

Communication Patterns​

1. Synchronous Request-Response​

2. Asynchronous Processing​

3. Caching Pattern​

4. Event-Driven (Message Queue)​

5. Retry Pattern​

Design Patterns​

1. Layered Architecture​

2. Interface-Based Design (Dependency Inversion)​

3. DTO Pattern (Data Transfer Object)​

4. Template Method Pattern (Abstract Controllers)​

5. Repository Pattern (JPA & MongoDB)​

6. Strategy Pattern (Cost Breakup Services)​

7. Builder Pattern (Query Construction)​

Module Dependencies​

Internal Module Dependencies​

1. snowplug​

2. monitoring​

3. errorhandler​

4. loggerutil​

External Module Dependencies​

Cross-Cutting Concerns​

1. Security​

2. Logging​

3. Monitoring​

4. Caching​

5. Error Handling​

6. Validation​

7. Configuration Management​

Summary​

Table of Contents

Introduction

Purpose of This Document

Architectural Style

Related Documents

Architectural Layers

Layer 1: Presentation Layer (Controllers)

Layer 2: Application Layer (Services)

Layer 3: Data Access Layer (DAOs & Repositories)

Layer 4: Data Transfer Layer (DTOs & Documents)

Layer 5: Infrastructure Layer (Config, Utils, Cross-Cutting)

Component Diagram

High-Level Component View

Package Structure

Complete Package Hierarchy

Layer Responsibilities

Request Flow Through Layers

Communication Patterns

1. Synchronous Request-Response

2. Asynchronous Processing

3. Caching Pattern

4. Event-Driven (Message Queue)

5. Retry Pattern

Design Patterns

1. Layered Architecture

2. Interface-Based Design (Dependency Inversion)

3. DTO Pattern (Data Transfer Object)

4. Template Method Pattern (Abstract Controllers)

5. Repository Pattern (JPA & MongoDB)

6. Strategy Pattern (Cost Breakup Services)

7. Builder Pattern (Query Construction)

Module Dependencies

Internal Module Dependencies

1. snowplug

2. monitoring

3. errorhandler

4. loggerutil

External Module Dependencies

Cross-Cutting Concerns

1. Security

2. Logging

3. Monitoring

4. Caching

5. Error Handling

6. Validation

7. Configuration Management

Summary