A service to search and discover Kotlin Multiplatform libraries. It aggregates data from Maven Central and GitHub, enriched with AI-powered metadata generation.

The repository contains both the backend (this README) and the web frontend (see Frontend).

Build & Run

Prerequisites

• JDK 21+
• Docker (for the local PostgreSQL, LocalStack, and OpenSearch services managed via Docker Compose)

Build & test

./kotlin build   # build without running tests
./kotlin test    # run tests
./kotlin check   # run project checks

Executable Jar

./kotlin package

Output: build/tasks/_app_executableJarJvm/app-jvm-executable.jar

Run locally

From CLI:

./kotlin run -m app

or

./kotlin run

Or run the main function from Application in IntelliJ — both use the local profile.

Spring Boot automatically starts and stops

• PostgreSQL
• LocalStack
• OpenSearch (data is persisted between runs)

Configuration

Spring profiles are used to run the app in different environments. Profile-specific files are in app/src/main/resources.

• local — local development (Docker Compose for PostgreSQL, LocalStack, and OpenSearch)
• prod — production (restricts debug utilities). application-prod.yml is a template; adapt it or use externalized configuration.

Indexing of packages can be enabled/disabled via klibs.indexing. Fine-grained indexing sources (Central Sonatype, Google Maven) and executor settings are under klibs.indexing-configuration.

Files on disk

• GitHub API request cache (managed by OkHttp). Property: klibs.integration.github.cache.request-cache-path.
• README files (Markdown + HTML) stored in S3 with local disk cache. Properties: klibs.readme.cache-dir, klibs.readme.s3.*.

Endpoints

• Swagger UI: /api-docs/swagger-ui.html
• Actuator: /actuator/health, /actuator/info

Troubleshooting

See troubleshooting.md.

Modules

The project follows a "module by feature" approach:

• app — main Spring Boot module. Configurations, scheduled jobs, glue for all other modules. Runnable.
• core/* — domain modules (package, project, scm-owner, scm-repository, readme, search, storage).
• integrations/* — third-party integrations (ai, github, maven).

Architecture

Indexing logic

The general flow:

1. Check for new artifacts (published since the last check) using Maven Central's API.
2. If new artifacts are available, add them to the processing queue (table package_index_request).
3. Process the queue in a separate thread, one by one. If indexing of a package fails, increment its failed_attempts. Try to process each package up to N times. Projects and SCM owner/info are created in the process of indexing packages.

AI descriptions are generated by a separate scheduled task because the rate limits of OpenAI are much lower than of GitHub and Maven Central, so it's significantly slower.

Information taken from GitHub (repository/owner) is updated by a separate scheduled task too, based on github_repo.updated_at.

Full Text Search

PostgreSQL's Full Text Search is used for FTS. Relevant data is aggregated in two materialized views — project_index and package_index — which are updated periodically and used for search queries. Known tech debt: at some point this might need to be replaced with Solr / ElasticSearch. All search-related logic is contained in the search module (ProjectSearchRepository, PackageSearchRepository), so the migration surface is limited.

Development

Development workflow: workflow.md.

How to update JVM version

JVM toolchain version is defined in the base Kotlin/JVM module template: kotlin-jvm.module-template.yaml (settings.jvm.jdk.version). All modules inherit from this template.

The JVM version used by Kotlin Toolchain is tied to the Kotlin Toolchain distribution, so updating Kotlin Toolchain also updates the JVM runtime it runs on.