# coal182/kotlin-api architecture

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

- Interactive diagram: https://gitdiagram.com/coal182/kotlin-api
- Repository: https://github.com/coal182/kotlin-api

## Overview

##### Project Type and Purpose
- This is a backend API project built in Kotlin, designed to be a skeleton for bootstrapping HTTP APIs.
- The README indicates that it is a starting point for new projects, emphasizing minimal boilerplate, best practices, a modern tech stack (latest stable Kotlin, Spring Boot, Java), and clear separation of concerns.
- The file tree reveals multiple modules such as “contexts/course” (which contains application, domain, and infrastructure layers) and “common” modules for shared utilities and testing.

##### File Structure
- Top-level files such as Application.kt, Dockerfile, and gradle configuration indicate that this is a runnable API application.
- The “src/main/kotlin/com/codely/api” directory holds general API controllers (like HealthcheckController and HolaController) that serve as the entry points for HTTP requests.
- The “contexts/course” directory reveals components for the course domain:
- Application layer (CourseCreator, CourseFinder) – handling business logic.
- Domain layer (Course, CourseCreated, CourseRepository interfaces) – encapsulating domain models and events.
- Infrastructure layer with persistence implementations (e.g., PostgreCourseRepository, InMemoryCourseRepository) and REST controllers for course-related actions.
- The “common” and “common-test” modules provide shared domain event definitions, publishers (e.g., KafkaPublisher and InMemoryPublisher), and test support.
- Configuration files (in src/main/kotlin/com/codely/config) such as DatabaseConfig, DependencyInjectionConf, and PublisherConfig indicate dependency wiring and external integrations.

##### README for Additional Insights
- The README emphasizes bootstrapping an API in Kotlin following best practices, and it points to using the skeleton as a foundation for creating consistent applications.
- It provides instructions to run and test the API, indirectly revealing the usage of REST endpoints, integration tests, and possibly database migration files (as observed in the resources directory).

a. Main Components:
- API Entry Point & Request Routing: Application.kt alongside API controllers (e.g., HealthcheckController and HolaController).
- Bounded Context – Course Context:
- Application Layer: Use cases like CourseCreator and CourseFinder.
- Domain Layer: Core domain models (Course, CourseCreated) and domain events.
- Infrastructure Layer: REST controllers for course operations and persistence implementations (InMemory/Postgre repositories).
- Shared/Common Components: Domain helpers (Either, DomainEvent, Publisher) and publisher implementations (KafkaPublisher, InMemoryPublisher).
- External Services: Database (drive by migration scripts) and messaging middleware (Kafka).
- Configuration components: DependencyInjection, Database, and Publisher configuration.

b. Relationships and Interactions:
- API clients send HTTP requests routed via the API controllers.
- Controllers interact with application layer services (use cases) within the course bounded context.
- The application layer validates business rules, invokes the domain layer, and persists state using repository interfaces.
- Domain events may trigger publisher components that utilize Kafka or in-memory publishers.
- Configurations wire all dependencies (using Spring Boot’s IoC/DI mechanisms) to ensure the components talk to each other properly.
- Integration tests (present in both “src/test-integration” and “common-test”) validate these flows end-to-end.

c. Architectural Patterns:
- Domain-Driven Design (DDD) is evident through bounded contexts, separation of application, domain, and infrastructure.
- Use of REST-based controllers as interfaces for client interactions.
- Layered architecture segregating API routing, business logic, domain models, and infrastructure concerns.
- Infrastructure abstraction (e.g., repositories, publishers) to allow for multiple implementations (InMemory vs. PostgreSQL vs. Kafka).

d. Relevant Technologies, Frameworks, or Libraries:
- Kotlin language and Spring Boot framework.
- Gradle (build system) and Docker for containerization.
- Relational database support (via migrations in PostgreSQL).
- Kafka for event publishing, facilitated by specific publisher classes.
- Testing frameworks (Kotlin test with JUnit, integrated via Gradle tasks).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    HTTP["HTTP Client"]:::external

    %% API Entry Layer
    subgraph "API Entry Layer"
        API["Application.kt"]:::api
        Health["HealthcheckController"]:::api
        Hola["HolaController"]:::api
    end

    %% Course Context
    subgraph "Course Context"
        %% Application Layer
        subgraph "Application Layer"
            Creator["CourseCreator"]:::courseApp
            Finder["CourseFinder"]:::courseApp
        end
        %% Domain Layer
        subgraph "Domain Layer"
            Course["Course"]:::courseDomain
            CourseEvt["CourseCreated"]:::courseDomain
            RepoInterface["CourseRepository"]:::courseDomain
        end
        %% Infrastructure Layer
        subgraph "Infrastructure Layer"
            REST1["GetFindCourseByIdController"]:::courseInfra
            REST2["PostCreateCourseController"]:::courseInfra
            InfraInMem["InMemoryCourseRepository"]:::courseInfra
            InfraPost["PostgreCourseRepository"]:::courseInfra
            Clock["LocalDateTimeClock"]:::courseInfra
        end
    end

    %% Shared/Common Components
    subgraph "Shared/Common Components"
        Either["Either"]:::common
        DomainEvtNode["DomainEvent"]:::common
        DomainEvtErr["DomainEventError"]:::common
        Publisher["Publisher"]:::common
        KafkaPub["KafkaPublisher"]:::common
        InMemPub["InMemoryPublisher"]:::common
        CourseMother["CourseMother (Test Support)"]:::common
    end

    %% Configuration Components
    subgraph "Configuration"
        DbConfig["DatabaseConfig"]:::config
        DIConfig["DependencyInjectionConf"]:::config
        PubConfig["PublisherConfig"]:::config
    end

    %% External Services
    subgraph "External Services"
        DB1["Migration V1.0.0"]:::external
        DB2["Migration V1.0.1"]:::external
        Docker["Dockerfile"]:::external
        CI["CI/CD (.github/workflows/ci.yml)"]:::external
    end

    %% Connections between layers
    HTTP -->|"sendsRequest"| API
    API -->|"routesReq"| Health
    API -->|"routesReq"| Hola

    %% API controllers invoking course infrastructure
    Health -->|"delegatesTo"| REST1
    Hola -->|"delegatesTo"| REST2

    %% Course REST controllers invoking application use cases
    REST1 -->|"callsUseCase"| Finder
    REST2 -->|"callsUseCase"| Creator

    %% Application layer interactions
    Creator -->|"executesDomainLogic"| Course
    Creator -->|"persistsVia"| RepoInterface
    Finder -->|"queries"| Course

    %% Domain triggering events and repository abstractions
    CourseEvt -->|"triggers"| Publisher
    RepoInterface -->|"implementedBy"| InfraInMem
    RepoInterface -->|"implementedBy"| InfraPost

    %% Publisher implementations
    Publisher -->|"publishesTo"| KafkaPub
    Publisher -->|"publishesTo"| InMemPub

    %% Configuration wiring
    DIConfig -->|"wires"| API
    DIConfig -->|"wires"| Creator
    DIConfig -->|"wires"| Finder
    DIConfig -->|"wires"| REST1
    DIConfig -->|"wires"| REST2
    DbConfig -->|"configures"| InfraPost
    PubConfig -->|"configures"| Publisher

    %% Infrastructure using external database migrations
    InfraPost -->|"usesMigration"| DB1
    InfraPost -->|"usesMigration"| DB2

    %% Class Definitions for Colors
    classDef api fill:#f9d6cc,stroke:#333,stroke-width:2px
    classDef courseApp fill:#c6f7d0,stroke:#333,stroke-width:2px
    classDef courseDomain fill:#d0e6ff,stroke:#333,stroke-width:2px
    classDef courseInfra fill:#ffd6f9,stroke:#333,stroke-width:2px
    classDef common fill:#e0d6ff,stroke:#333,stroke-width:2px
    classDef config fill:#ccf9ff,stroke:#333,stroke-width:2px
    classDef external fill:#fde2ab,stroke:#333,stroke-width:2px

    %% Click Events for API Entry Layer
    click API "https://github.com/coal182/kotlin-api/blob/main/src/main/kotlin/com/codely/Application.kt"
    click Health "https://github.com/coal182/kotlin-api/blob/main/src/main/kotlin/com/codely/api/infrastructure/HealthcheckController.kt"
    click Hola "https://github.com/coal182/kotlin-api/blob/main/src/main/kotlin/com/codely/api/infrastructure/HolaController.kt"

    %% Click Events for Course Context - Application Layer
    click Creator "https://github.com/coal182/kotlin-api/blob/main/contexts/course/src/main/kotlin/com/codely/course/application/CourseCreator.kt"
    click Finder "https://github.com/coal182/kotlin-api/blob/main/contexts/course/src/main/kotlin/com/codely/course/application/find/CourseFinder.kt"

    %% Click Events for Course Context - Domain Layer
    click Course "https://github.com/coal182/kotlin-api/blob/main/contexts/course/src/main/kotlin/com/codely/course/domain/Course.kt"
    click CourseEvt "https://github.com/coal182/kotlin-api/blob/main/contexts/course/src/main/kotlin/com/codely/course/domain/CourseCreated.kt"
    click RepoInterface "https://github.com/coal182/kotlin-api/blob/main/contexts/course/src/main/kotlin/com/codely/course/domain/CourseRepository.kt"

    %% Click Events for Course Context - Infrastructure Layer
    click REST1 "https://github.com/coal182/kotlin-api/blob/main/contexts/course/src/main/kotlin/com/codely/course/infrastructure/rest/GetFindCourseByIdController.kt"
    click REST2 "https://github.com/coal182/kotlin-api/blob/main/contexts/course/src/main/kotlin/com/codely/course/infrastructure/rest/PostCreateCourseController.kt"
    click InfraInMem "https://github.com/coal182/kotlin-api/blob/main/contexts/course/src/main/kotlin/com/codely/course/infrastructure/persistence/InMemoryCourseRepository.kt"
    click InfraPost "https://github.com/coal182/kotlin-api/blob/main/contexts/course/src/main/kotlin/com/codely/course/infrastructure/persistence/PostgreCourseRepository.kt"
    click Clock "https://github.com/coal182/kotlin-api/blob/main/contexts/course/src/main/kotlin/com/codely/course/infrastructure/LocalDateTimeClock.kt"

    %% Click Events for Shared/Common Components
    click Either "https://github.com/coal182/kotlin-api/blob/main/common/src/main/kotlin/com/codely/common/Either.kt"
    click DomainEvtNode "https://github.com/coal182/kotlin-api/blob/main/common/src/main/kotlin/com/codely/common/domain/DomainEvent.kt"
    click DomainEvtErr "https://github.com/coal182/kotlin-api/blob/main/common/src/main/kotlin/com/codely/common/domain/DomainEventError.kt"
    click Publisher "https://github.com/coal182/kotlin-api/blob/main/common/src/main/kotlin/com/codely/common/domain/Publisher.kt"
    click KafkaPub "https://github.com/coal182/kotlin-api/blob/main/common/src/main/kotlin/com/codely/common/infrastructure/KafkaPublisher.kt"
    click InMemPub "https://github.com/coal182/kotlin-api/blob/main/common/src/main/kotlin/com/codely/common/infrastructure/InMemoryPublisher.kt"
    click CourseMother "https://github.com/coal182/kotlin-api/blob/main/common-test/src/main/kotlin/com/codely/common/course/CourseMother.kt"

    %% Click Events for Configuration Components
    click DbConfig "https://github.com/coal182/kotlin-api/blob/main/src/main/kotlin/com/codely/config/DatabaseConfig.kt"
    click DIConfig "https://github.com/coal182/kotlin-api/blob/main/src/main/kotlin/com/codely/config/DependencyInjectionConf.kt"
    click PubConfig "https://github.com/coal182/kotlin-api/blob/main/src/main/kotlin/com/codely/config/PublisherConfig.kt"

    %% Click Events for External Services
    click DB1 "https://github.com/coal182/kotlin-api/blob/main/src/main/resources/db/migration/V1.0.0__course_table.sql"
    click DB2 "https://github.com/coal182/kotlin-api/blob/main/src/main/resources/db/migration/V1.0.1__course_table.sql"
    click Docker "https://github.com/coal182/kotlin-api/tree/main/Dockerfile"
    click CI "https://github.com/coal182/kotlin-api/blob/main/.github/workflows/ci.yml"
```
