# klibs.io
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](frontend/README.md)), as well as the klibs-io-notifier Gradle plugin (see [notifier-plugin](notifier-plugin/README.md)).
## Build & Run
### Prerequisites
- JDK 21+
- Docker (for the local PostgreSQL, LocalStack, and OpenSearch services managed via Docker Compose)
### Build & test
```bash
./kotlin build # build without running tests
./kotlin test # run tests
./kotlin check # run project checks
```
### Executable Jar
```bash
./kotlin package
```
Output: `build/tasks/_app_executableJarJvm/app-jvm-executable.jar`
### Run locally
From CLI:
```bash
./kotlin run -m app
```
or
```bash
./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](https://docs.spring.io/spring-boot/reference/features/profiles.html) are used to run the app
in different environments. Profile-specific files are in [app/src/main/resources](app/src/main/resources).
- `local` — local development (Docker Compose for PostgreSQL, LocalStack, and OpenSearch)
- `prod` — production (restricts debug utilities).
[application-prod.yml](app/src/main/resources/application-prod.yml) is a template; adapt it or use
[externalized configuration](https://docs.spring.io/spring-boot/reference/features/external-config.html).
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](https://square.github.io/okhttp/features/caching/)).
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](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](https://www.postgresql.org/docs/17/textsearch.html) 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](workflow.md).
### How to update JVM version
JVM toolchain version is defined in the base Kotlin/JVM module template:
[kotlin-jvm.module-template.yaml](build-logic/templates/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.