shiprocket-ads-core

Summary

Spring Boot 3 service providing core capabilities for Shiprocket Ads. It exposes web APIs, integrates with Meta (Facebook) and Google Ads for insights/management, validates seller/platform context, processes CSV-based workflows, publishes/consumes Kafka topics for async processing, persists operational data in MySQL and MongoDB, and uses Redis for caching and shared state. Includes observability via Actuator and OpenTelemetry.

Responsibilities

• Expose REST endpoints for ads core functions (validation, orchestration, utilities) with standardized exception handling and Swagger UI
• Integrate with Meta Graph API/Ad Library and Google Ads/OAuth to fetch and manage ads insights and related operations
• Process CSV upload/validation/processing workflows and emit progress/results events
• Publish/consume Kafka topics for insights ingestion, audit reporting, recharge/payment flows, and dead-letter handling
• Persist and query ads domain data in MySQL (JPA) and MongoDB; use Redis for caching and distributed/shared state
• Send email notifications via AWS SES and manage creative/payment assets via AWS S3
• Provide service health/metrics and distributed tracing via Actuator and OpenTelemetry OTLP

Dependencies

• Spring Boot 3.3.1 (Web, Validation, Actuator, Log4j2)
• Spring Data JPA (Hibernate) with MySQL Connector/J
• Spring Data MongoDB (driver/repositories; application excludes auto-config but uses Mongo URLs in config)
• Spring Kafka (Kafka producers/consumers)
• Redis (via spring-data-redis and internal common-redis library)
• AWS SDK (S3, SES) and JavaMail
• Google Ads API client (google-ads) and Google OAuth/Auth libraries
• Meta Graph API integration (via HTTP client; configured endpoints/tokens)
• Resilience4j (fault tolerance)
• OpenTelemetry (API/SDK/OTLP exporter; javaagent at runtime)
• Jackson CSV (CSV parsing)
• GraalVM JS (script engine used by logging selector / potential rules execution)
• Internal service clients (aggregator-service, communication service, checkout/edge service, ads-python service)
• AI/LLM APIs (OpenAI, Google Gemini/Vertex AI, OpenRouter)

Architecture Diagram

Mermaid Source

flowchart LR
  U[Client/UI or Internal Caller] --> S[shiprocket-ads-core]
  S --> CFG[Config Server]
  S --> K[Kafka]
  S --> R[Redis]
  S --> MY[(MySQL)]
  S --> MO[(MongoDB)]
  S --> S3[AWS S3]
  S --> SES[AWS SES]
  S --> META[Meta Graph API]
  S --> GADS[Google Ads API]
  S --> OAI[OpenAI API]
  S --> VAI[Vertex AI / Gemini]
  S --> OR[OpenRouter]
  S --> AGG[Aggregator Service]
  S --> COMM[Communication Service]
  S --> EDGE[Edge/Checkout Public API]
  S --> PY[Ads Python Service]
  S --> OTLP[OTLP Collector (SigNoz)]

DFD Diagram

Mermaid Source

flowchart TB
  %% External Entities
  E1[External Entity: Client/UI] 
  E2[External Entity: Meta Graph API]
  E3[External Entity: Google Ads/OAuth]
  E4[External Entity: AWS S3/SES]
  E5[External Entity: Kafka Cluster]
  E6[External Entity: Config Server]
  E7[External Entity: Internal Services (Aggregator/Communication/Edge/Ads-Python)]
  E8[External Entity: OTLP Collector]
  
  %% Process
  P1((Process: shiprocket-ads-core API & Workers))
  
  %% Data Stores
  D1[(Data Store: MySQL)]
  D2[(Data Store: MongoDB)]
  D3[(Data Store: Redis)]
  
  %% Flows
  E1 -->|API Requests (Ads ops, CSV workflows)| P1
  P1 -->|API Responses| E1
  E6 -->|Config/Secrets/Properties| P1
  P1 -->|Read/Write ads data| D1
  P1 -->|Read/Write documents/insights| D2
  P1 -->|Cache/locks/state| D3
  P1 -->|Publish/Consume events (insights, audit, validation, DLQ)| E5
  P1 -->|Fetch/Manage campaigns & insights| E2
  P1 -->|Auth & Ads operations| E3
  P1 -->|Store creatives / send emails| E4
  P1 -->|Service-to-service calls| E7
  P1 -->|Traces/Metrics (OTLP)| E8