# 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
```bash
./gradlew build
```

### Running the API Gateway
```bash
./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](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](docs/API_DOCUMENTATION_GUIDELINES.md). 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](SERVICE_DISCOVERY_IMPLEMENTATION.md).

## Last Updated

2025-07-21