Distributed User Analytics API

A high-performance backend service built with Kotlin and Spring Boot 3, designed for distributed user event tracking and analytics.
This project demonstrates a clean and scalable architecture powered by Apache Cassandra, and Cassandra Migration for real-time analytical insights.

---

🚀 Overview

distributed-user-analytics-api is a distributed event tracking system that ingests and retrieves user analytics events with low latency.
The solution is architected to simulate a production-grade environment where horizontal scalability, event consistency, and data resiliency are first-class citizens.

This project highlights enterprise-grade engineering practices:

• Clean Architecture (Hexagonal Pattern)
• Domain-driven structure with isolation between core and infrastructure
• Continuous delivery readiness
• Infrastructure-as-code mindset with Docker and Testcontainers

---

🧩 Tech Stack

Layer	Technology	Purpose
Language	Kotlin 1.9+	Modern JVM language with null safety and coroutines
Framework	Spring Boot 3	Dependency injection, REST APIs, and configuration management
Database	Apache Cassandra 4.1	Distributed NoSQL database for high availability
Migration Tool	Cassandra Migration	Schema versioning and automated DDL evolution
Testing	JUnit 5, MockK, Testcontainers	Integration and unit testing with containerized environments
Build	Maven	Dependency management and build automation
Deployment	Docker	Containerized execution and CI/CD readiness

---

🧱 Architecture Overview

This project follows the Hexagonal (Ports & Adapters) Architecture, separating business logic from external dependencies.

application/
 ├── controller/       -> REST endpoints for Users and Events
 ├── dto/              -> Data Transfer Objects
domain/
 ├── model/            -> Core entities and value objects
 ├── repository/       -> Design interfaces for data access
 ├── service/          -> Business logic
infrastructure/
 ├── cassandra/        -> Entities, repositories, and migrations
 └── config/           -> Cassandra session and Spring configuration

This ensures a clean boundary between application and infrastructure, enabling testability and maintainability at scale.

---

🗄️ Database & Migration

Cassandra Schema Management

Cassandra schema versioning is managed through Cassandra Migration, which provides controlled deployment of schema changes via versioned .cql scripts.

Example migration files:

/resources/cassandra/migration/
 ├── 001_create_user_table.cql
 └── 002_create_event_table.cql

Example Keyspace (Manual Creation)

CREATE KEYSPACE IF NOT EXISTS user_analytics
WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1};

---

⚙️ REST API Endpoints

User Management

Method	Endpoint	Description
POST	/v1/api/users	Create a new user
GET	/v1/api/users/{id}	Retrieve user details
DELETE	/v1/api/users/{id}	Delete user by ID

Event Tracking

Method	Endpoint	Description
POST	/v1/api/events/{userId}	Register a new event for a user
GET	/v1/api/events/{userId}	Retrieve all events for a given user

---

🧪 Testing Strategy

The testing approach covers integration and unit testing, ensuring high reliability.

• Integration Tests use Testcontainers to spin up a real Cassandra instance during CI.
• Unit Tests rely on MockK for fast and isolated domain validation.

Example test class:

@SpringBootTest
@Testcontainers
class EventRepositoryIntegrationTest {

    @Test
    fun `should save and retrieve events by user`() {
        val event = Event(UUID.randomUUID(), UUID.randomUUID(), "LOGIN", "User login test", Instant.now())
        repository.save(event)
        val results = repository.findByUserId(event.userId)
        assertTrue("Expected at least one event", results.isNotEmpty())
    }
}

---

🐳 Running the Project

Prerequisites

• Docker & Docker Compose
• Java 21+
• Maven 3.9+

Start Cassandra Locally

docker-compose up -d cassandra

Run Application

mvn spring-boot:run

The API will be available at:

http://localhost:8080/v1/api

---

📄 Rest and DB Illustration

Create User Example

Find User Example

Create User Event Example

Find User Events Example

Cassandra DB Tables

Docker illustration

---

📘 Key Takeaways

• Demonstrates enterprise-grade engineering with Kotlin and Cassandra
• Implements Cassandra Migration for schema lifecycle control
• Applies Clean Architecture principles to enforce modularity
• Ready for CI/CD pipelines and containerized deployment

---

👤 Author

Ricardo Proença
Senior Software Engineer — Backend Specialist in Kotlin & Java
🔗 LinkedIn
💻 GitHub