First Page ‐ Project Overview

📌 Project Overview

Project Name: ktx-audit-service

🔹 This project provides a flexible and modular security event logging system based on Hexagonal Architecture.
🔹 It is designed to be decoupled from specific storage and messaging technologies, making it adaptable to various environments.
🔹 The system logs security-related events (e.g., failed logins, account lockouts) and publishes them to a message broker (Kafka) for further processing.

---

📐 Architecture Overview

This project follows the Hexagonal Architecture (Ports & Adapters) pattern, ensuring loose coupling between components.

🛠️ Core Concepts

Component	Responsibility
🔹 ktx-core	Defines interfaces (ports) for event logging and messaging. No concrete implementation.
🔹 SecurityEventService	Handles security event logging and publishing to Kafka.
🔹 SecurityEventRepository	Adapter for MySQL persistence, storing security events.
🔹 SecurityEventProducer	Adapter for Kafka, responsible for publishing events.

🖼️ System Diagram (ASCII)

                     +--------------------------------+
                     |   Application Layer (Ports)   |
                     |--------------------------------|
                     |  - SecurityEventService       |
                     |  - KtxEventService<T>         |
                     +--------------------------------+
                                  |
                                  v
         +--------------------------------------------------+
         |              Infrastructure Layer (Adapters)     |
         |--------------------------------------------------|
         |  🔹 SecurityEventRepository  ->  MySQL Adapter  |
         |  🔹 SecurityEventProducer    ->  Kafka Adapter  |
         +--------------------------------------------------+
                                  |
                                  v
         +--------------------------------------------------+
         |                  External Systems                |
         |--------------------------------------------------|
         |  - MySQL Database                                |
         |  - Kafka Message Broker                          |
         +--------------------------------------------------+

---

🚀 How It Works

1️⃣ Security Events are Generated

• Example: A failed login attempt triggers an event.

2️⃣ Events are Logged & Persisted

• SecurityEventService saves the event using KtxEventService<T>.
• The underlying persistence is managed by the appropriate adapter (e.g., MySQL via SecurityEventRepository).

3️⃣ Events are Published to Kafka

• SecurityEventProducer pushes the event to the security-events Kafka topic.
• Other microservices can consume and react to security-related events.

---

📦 Modules

The project is structured into multiple modules:

🔹 ktx-core

• Contains only interfaces (ports).
• Enables plug-and-play architecture where modules can inject implementations dynamically.

🔹 security-audit-service

• Implements the event logging and persistence logic.
• Uses SecurityEventRepository for MySQL and SecurityEventProducer for Kafka.

🔹 (Upcoming) security-enforcement-service

• Planned module that will apply security policies (e.g., account lockout, brute-force prevention).

---

🛠️ Setup & Installation

1️⃣ Prerequisites

Ensure you have:
✅ Java 17+
✅ Maven
✅ Docker (for MySQL & Kafka setup)

2️⃣ Run with Docker

docker-compose up -d

This starts MySQL, Kafka, and Zookeeper.

3️⃣ Run the Application

mvn spring-boot:run

---

📝 Next Steps

🔹 [ ] Clarify SecurityService Role: Should it handle security enforcement?
🔹 [ ] Make Security Configurable: Define thresholds for event-driven security rules.
🔹 [ ] Improve Documentation: Expand Wiki with event payload examples, API usage, and architecture deep dive.

---

📚 Related Resources

📌 🔗 GitHub Repository
📌 🔗 API Documentation (Swagger)
📌 🔗 Kafka Management UI

---

🚀 This is the first page of the GitHub Wiki. Next, we can add more details on API usage, security event types, and best practices. Let me know what you want next! 🎯