# imransolanki/kotlin-microservices-starter-kit architecture

> Architecture diagram of the GitHub repository imransolanki/kotlin-microservices-starter-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/imransolanki/kotlin-microservices-starter-kit
- Repository: https://github.com/imransolanki/kotlin-microservices-starter-kit

## Overview

##### Project type and purpose
- This is a standalone Kotlin microservice built with the Ktor HTTP framework. It exposes a simple “Pet” API, applies business logic in a service layer, persists data to PostgreSQL via Exposed, and uses Koin for dependency injection and Hoplite for configuration.

##### File structure
- Top-level: build files (Gradle), README, settings.
- src/main/kotlin/org/edu/api: HTTP models and route definitions (Pet.kt, PetRoutes.kt, Validator).
- src/main/kotlin/org/edu/service: business logic (PetService).
- src/main/kotlin/org/edu/persistence: database entity definitions (PetEntity).
- src/main/kotlin/org/edu/plugin: application wiring (AppModule, Configuration, DataSource, DatabaseConfig, EnvironmentConfig), Ktor plugin setup (Routing, Serialization), and SchemaMigrator for DB migrations.
- src/main/resources: application.yaml (Hoplite configuration), SQL migration scripts, logging config.
- Tests mirror API and service layers (Kotest).

##### README
- Confirms use of Ktor, Koin, Exposed, Either, Hoplite, and Kotest.
- Describes features: modular microservice, best practices, PostgreSQL backend.

##### Main components and interactions
a. Components:
- Client (HTTP consumer)
- Ktor HTTP server
- Routing plugin (registers PetRoutes)
- API layer (PetRoutes + Validator)
- Service layer (PetService, uses Either for error handling)
- Persistence layer (Exposed DAOs in PetEntity, SchemaMigrator)
- Configuration (Hoplite loading application.yaml → EnvironmentConfig)
- Dependency injection container (Koin via AppModule)
- DataSource (DatabaseConfig → HikariCP → PostgreSQL)
- External PostgreSQL database + migration scripts

b. Relationships & data flow:
1. Client → HTTP request
2. Ktor Routing → PetRoutes
3. Input validated via Validator → request DTO (Pet)
4. PetRoutes calls PetService
5. PetService uses Exposed DAO (PetEntity) to query/update DB
6. SchemaMigrator runs at startup to apply SQL migrations
7. Responses serialized → client

c. Architectural patterns & principles:
- Layered architecture (API → Service → Persistence → DB)
- Dependency injection (Koin modules wired in AppModule)
- Configuration abstraction (Hoplite)
- Database migrations at startup
- Error handling via Either monad

d. Key technologies:
- Ktor (HTTP server, Routing, Serialization)
- Koin (DI)
- Exposed (ORM)
- Hoplite (config)
- Kotest (tests)
- PostgreSQL

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Infrastructure Layer
    subgraph "Infrastructure" 
        direction TB
        ApplicationEntry["Application.kt\n(Ktor Server Entry)"]:::infra
        ConfigurationLoader["Configuration.kt\n(Hoplite Loader)"]:::infra
        EnvConfig["EnvironmentConfig.kt\n(Config Model)"]:::infra
        DatabaseConfig["DatabaseConfig.kt\n(DB Config Wrapper)"]:::infra
        DataSource["DataSource.kt\n(HikariCP → PostgreSQL)"]:::infra
        AppModule["AppModule.kt\n(Koin DI Container)"]:::infra
    end

    %% API Layer
    subgraph "API Layer" 
        direction TB
        RoutingPlugin["Routing.kt\n(Ktor Routing Plugin)"]:::api
        SerializationPlugin["Serialization.kt\n(JSON Serialization)"]:::api
        PetRoutes["PetRoutes.kt\n(Route Definitions)"]:::api
        PetModel["Pet.kt\n(Request/Response Models)"]:::api
        Validator["Validator.kt\n(Input Validation)"]:::api
    end

    %% Service Layer
    subgraph "Service Layer" 
        direction TB
        PetService["PetService.kt\n(Business Logic, Either)"]:::service
    end

    %% Persistence Layer
    subgraph "Persistence Layer" 
        direction TB
        SchemaMigrator["SchemaMigrator.kt\n(DB Migration Runner)"]:::persistence
        MigrationScript["V1__create_pet.sql\n(Migration Script)"]:::persistence
        PetEntity["PetEntity.kt\n(Exposed DAO)"]:::persistence
    end

    %% External Systems
    subgraph "External" 
        direction TB
        PostgreSQL[(PostgreSQL DB)]:::external
        AppYaml["application.yaml\n(Config File)"]:::external
    end

    %% Relationships
    ApplicationEntry -->|"loads config"| ConfigurationLoader
    ConfigurationLoader -->|"parses YAML"| AppYaml
    ConfigurationLoader -->|"generates"| EnvConfig
    ApplicationEntry -->|"initializes DI"| AppModule
    EnvConfig -->|"bound in"| AppModule
    ApplicationModuleConfig-->dummy[ ] 
    AppModule -->|"registers"| RoutingPlugin
    AppModule -->|"registers"| SerializationPlugin
    AppModule -->|"registers"| PetService
    AppModule -->|"registers"| DataSource
    AppModule -->|"registers"| DatabaseConfig

    ApplicationEntry -->|"runs migrations"| SchemaMigrator
    SchemaMigrator -->|"executes"| MigrationScript
    MigrationScript -->|"applies to"| PostgreSQL

    RoutingPlugin --> PetRoutes
    SerializationPlugin --> PetRoutes
    PetRoutes -->|"uses model"| PetModel
    PetRoutes -->|"validates via"| Validator
    PetRoutes -->|"calls"| PetService

    PetService -->|"uses DAO"| PetEntity
    PetEntity -->|"reads/writes"| PostgreSQL
    DataSource -->|"connects to"| PostgreSQL
    DatabaseConfig --> DataSource

    %% Click Events
    click ApplicationEntry "https://github.com/imransolanki/kotlin-microservices-starter-kit/blob/main/src/main/kotlin/Application.kt"
    click RoutingPlugin "https://github.com/imransolanki/kotlin-microservices-starter-kit/blob/main/src/main/kotlin/org/edu/plugin/Routing.kt"
    click SerializationPlugin "https://github.com/imransolanki/kotlin-microservices-starter-kit/blob/main/src/main/kotlin/org/edu/plugin/Serialization.kt"
    click PetRoutes "https://github.com/imransolanki/kotlin-microservices-starter-kit/blob/main/src/main/kotlin/org/edu/api/PetRoutes.kt"
    click PetModel "https://github.com/imransolanki/kotlin-microservices-starter-kit/blob/main/src/main/kotlin/org/edu/api/Pet.kt"
    click Validator "https://github.com/imransolanki/kotlin-microservices-starter-kit/blob/main/src/main/kotlin/org/edu/api/Validator.kt"
    click PetService "https://github.com/imransolanki/kotlin-microservices-starter-kit/blob/main/src/main/kotlin/org/edu/service/PetService.kt"
    click PetEntity "https://github.com/imransolanki/kotlin-microservices-starter-kit/blob/main/src/main/kotlin/org/edu/persistence/PetEntity.kt"
    click SchemaMigrator "https://github.com/imransolanki/kotlin-microservices-starter-kit/blob/main/src/main/kotlin/org/edu/plugin/SchemaMigrator.kt"
    click MigrationScript "https://github.com/imransolanki/kotlin-microservices-starter-kit/blob/main/src/main/resources/db/migration/V1__create_pet.sql"
    click ConfigurationLoader "https://github.com/imransolanki/kotlin-microservices-starter-kit/blob/main/src/main/kotlin/org/edu/plugin/Configuration.kt"
    click EnvConfig "https://github.com/imransolanki/kotlin-microservices-starter-kit/blob/main/src/main/kotlin/org/edu/plugin/EnvironmentConfig.kt"
    click DataSource "https://github.com/imransolanki/kotlin-microservices-starter-kit/blob/main/src/main/kotlin/org/edu/plugin/DataSource.kt"
    click DatabaseConfig "https://github.com/imransolanki/kotlin-microservices-starter-kit/blob/main/src/main/kotlin/org/edu/plugin/DatabaseConfig.kt"
    click AppModule "https://github.com/imransolanki/kotlin-microservices-starter-kit/blob/main/src/main/kotlin/org/edu/plugin/AppModule.kt"
    click AppYaml "https://github.com/imransolanki/kotlin-microservices-starter-kit/blob/main/src/main/resources/application.yaml"

    %% Styles
    classDef api fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef service fill:#e6ffed,stroke:#28a745,color:#28a745
    classDef persistence fill:#fff5e6,stroke:#d9822b,color:#d9822b
    classDef infra fill:#e6e6e6,stroke:#6a737d,color:#6a737d
    classDef external fill:#fbefff,stroke:#6f42c1,color:#6f42c1
```
