spring-marketing-report/.readme at master · mlwilli/spring-marketing-report · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
#Spring Marketing Report

A lightweight Spring Boot service for generating marketing performance reports.
It takes raw client data (spend, impressions, clicks, conversions, churn risk), processes KPIs, segments clients, and returns a structured marketing report with insights and recommendations.

This project is intentionally simple but structured for internal demonstration.

Features

REST endpoint for generating reports

Rule-based client segmentation

High value

At risk

Low engagement

KPI aggregation

Total spend

CTR / CVR

Avg CPC / CPA

Automated recommendations based on segment data

In-memory report storage

Clean domain-driven architecture

No database dependencies

Running the Application

Using Maven wrapper:

./mvnw spring-boot:run


Or from IntelliJ, run:

MarketingReportApplication


Once running, the service is available at:

http://localhost:8080/api/reports

Generating a Report
Example Request

(Use Git Bash, WSL, macOS Terminal, or real curl)

curl -X POST http://localhost:8080/api/reports/generate \
  -H "Content-Type: application/json" \
  -d '{
        "periodLabel": "Last 30 days",
        "clients": [
          {
            "clientId": "c1",
            "name": "Acme Corp",
            "industry": "E-commerce",
            "spend": 12000,
            "impressions": 500000,
            "clicks": 15000,
            "conversions": 600,
            "churnRisk": 0.2
          },
          {
            "clientId": "c2",
            "name": "Beta Health",
            "industry": "Healthcare",
            "spend": 3000,
            "impressions": 200000,
            "clicks": 1000,
            "conversions": 40,
            "churnRisk": 0.7
          }
        ]
      }'

Example Response (trimmed)
{
  "id": "db147a11-a2b8-4cd8-8174-83c6e9fae1ed",
  "generatedAt": "2025-01-12T10:15:00Z",
  "periodLabel": "Last 30 days",
  "kpiSummary": {
    "totalSpend": 15000,
    "totalImpressions": 700000,
    "totalClicks": 16000,
    "totalConversions": 640,
    "overallCtr": 0.022,
    "overallCvr": 0.04
  },
  "segments": [
    { "segmentType": "HIGH_VALUE", "clientIds": ["c1"] },
    { "segmentType": "AT_RISK",    "clientIds": ["c2"] }
  ],
  "recommendations": [
    { "title": "Scale budget on high value accounts" },
    { "title": "Retention campaigns for at-risk clients" }
  ]
}

Endpoints
POST /api/reports/generate

Generates a new marketing report.

GET /api/reports/{id}

Fetch a previously generated report.

GET /api/reports

List all generated reports in memory.

Architecture
domain/      → Client, ClientPerformance, KPIs, Segment, Report objects
service/     → ReportService, rule-based segmentation & KPI logic
repository/  → InMemoryReportRepository (simple storage)
api/         → REST controller + DTOs


Designed for clarity and testability.

Example Use Cases

Agencies wanting quick campaign health summaries

Internal analytics teams prototyping reporting logic

Demo dashboards needing backend-generated insights

Portfolio / GitHub activity project (your case)

Requirements

Java 21

Spring Boot 3.2.x

Maven