meldestelle/README.md

Meldestelle - Self-Contained Systems Architecture

This is a Kotlin JVM backend project implementing a Self-Contained Systems (SCS) architecture for an equestrian sport management system.

Architecture Overview

The project follows Domain-Driven Design (DDD) principles with clearly separated bounded contexts:

Implemented Modules

• shared-kernel - Common domain types, enums, serializers, validation utilities, and base DTOs
• master-data - Master data management (countries, regions, age classes, venues)
• member-management - Person and club/association management
• horse-registry - Horse registration and management
• event-management - Event and tournament management
• api-gateway - Central API gateway aggregating all services

Module Dependencies

api-gateway
├── shared-kernel
├── master-data
├── member-management
├── horse-registry
└── event-management

event-management
├── shared-kernel
└── horse-registry

horse-registry
├── shared-kernel
└── member-management

member-management
├── shared-kernel
└── master-data

master-data
└── shared-kernel

Technology Stack

• Kotlin JVM - Primary programming language
• Ktor - Web framework for REST APIs
• Exposed - Database ORM
• PostgreSQL - Database
• Consul - Service discovery and registry
• Kotlinx Serialization - JSON serialization
• Gradle - Build system

Getting Started

Prerequisites

• JDK 17 or higher
• PostgreSQL database

Building the Project

./gradlew build

Running the API Gateway

./gradlew :api-gateway:jvmRun

Documentation

See the docs/ directory for detailed architecture documentation and diagrams.

API Documentation

The project includes comprehensive API documentation for all endpoints:

• Central API Documentation: Access the central API documentation page at /docs (or /api which redirects to /docs)
• Swagger UI: Access the interactive API documentation at /swagger when the application is running
• OpenAPI Specification: The OpenAPI specification is available at /openapi
• JSON API Overview: A JSON representation of the API structure is available at /api/json
• Developer Guidelines: Guidelines for documenting APIs are available in docs/API_DOCUMENTATION_GUIDELINES.md

The API documentation covers all bounded contexts:

• Authentication API
• Master Data API
• Member Management API
• Horse Registry API
• Event Management API

How to Use the API Documentation

1. Start the application with ./gradlew :api-gateway:jvmRun
2. For a comprehensive documentation portal, navigate to http://localhost:8080/docs
3. For detailed interactive documentation, navigate to http://localhost:8080/swagger
4. For the raw OpenAPI specification, navigate to http://localhost:8080/openapi
5. Explore the available endpoints, request/response models, and authentication requirements
6. Test API calls directly from the Swagger UI interface

The central documentation page provides:

• Overview of the API architecture
• Details about all API contexts and their endpoints
• Links to additional documentation resources
• Authentication instructions
• Response format examples

For Developers

When adding or modifying API endpoints, please follow the API Documentation Guidelines. These guidelines ensure consistency across all API documentation and make it easier for developers, testers, and API consumers to understand and use our APIs.

Service Discovery

The project uses Consul for service discovery, allowing services to dynamically discover and communicate with each other without hardcoded endpoints. This makes the system more resilient and scalable.

Architecture

The service discovery implementation consists of three main components:

1. Consul Service Registry: A central registry where services register themselves and discover other services.
2. Service Registration: Each service registers itself with Consul on startup.
3. Service Discovery: The API Gateway uses Consul to discover services and route requests to them.

Using Service Discovery

• Consul UI: Access the Consul UI at http://localhost:8500 when the system is running.
• Service Registration: Services automatically register with Consul on startup.
• Dynamic Routing: The API Gateway dynamically routes requests to services based on the service registry.

For detailed implementation instructions, see SERVICE_DISCOVERY_IMPLEMENTATION.md.

Last Updated

2025-07-21