Kotlin/Ktor Simple Food API Guide

Expert assistant for the Simple Food project - a Kotlin/Ktor server application for food management with multi-module architecture.

Project Overview

Simple Food implements a REST API for food/product management using:

Architecture Understanding

Before making changes, understand the multi-module structure:

1. **Transport Layer**: `simple-food-transport-models` - OpenAPI-generated DTOs

2. **Business Layer**: `simple-food-common-models` - Domain models, repository interfaces

3. **Mapping Layer**: `simple-food-transport-mappers` - DTO ↔ Business model conversion

4. **Repository Layer**:

- `simple-food-product-repo-memory` - In-memory (ConcurrentHashMap)

- `simple-food-product-repo-postgresql` - PostgreSQL with Exposed ORM

- `simple-food-repo-measure-memory` - In-memory measure units

- `simple-food-repo-measure-postgres` - PostgreSQL measure units

5. **Application Layer**: `simple-food-product-app` - Ktor REST API server

6. **Specification**: `specs/` - OpenAPI YAML definitions

Refer to `docs/architecture.md` for detailed architecture documentation.

Data Flow Pattern

Always follow this flow:

```

HTTP Request → Transport DTO → [.toContext()] → Business Model → Repository

↓

HTTP Response ← Transport DTO ← [.toTransport()] ← Business Model ← Repository

```

**Critical Rules:**

Step-by-Step Workflow

Adding/Modifying API Endpoints

1. **Update OpenAPI Spec**: Edit `specs/spec-simple-food-api-*.yaml`

2. **Regenerate Models**: Run `./gradlew :simple-food-transport-models:openApiGenerate`

3. **Update Mappers**: Modify mapping functions in `simple-food-transport-mappers`

4. **Write Mapper Tests**: Add/update tests for new mappings

5. **Implement Routes**: Update routes in `simple-food-product-app` using mappers

6. **Test**: Build with `./gradlew build`

Working with Repositories

**Configuration Options:**

**Environment Variables for PostgreSQL:**

```bash

REPOSITORY_TYPE=postgres

DB_URL=jdbc:postgresql://localhost:5432/simplefood

DB_USER=postgres

DB_PASSWORD=postgres

```

**Repository Interfaces:**

Database Setup

For PostgreSQL development:

```bash

docker run -d -p 5432:5432 \

-e POSTGRES_DB=simplefood \

-e POSTGRES_USER=postgres \

-e POSTGRES_PASSWORD=postgres \

postgres:16

```

Migrations managed by Flyway automatically on startup.

Common Commands

```bash

Build entire project

./gradlew build

Run with in-memory storage (default)

./gradlew :simple-food-product-app:run

Run with PostgreSQL

REPOSITORY_TYPE=postgres ./gradlew :simple-food-product-app:run

Regenerate OpenAPI transport models

./gradlew :simple-food-transport-models:openApiGenerate

Run tests

./gradlew test

```

Configuration Reference

Location: `simple-food-product-app/src/main/resources/application.conf`

Key settings:

Important Constraints

1. **Java Version**: Requires Java 21+

2. **Mapping**: Never bypass mapper functions

3. **Error Format**: Use OpenAPI `Error(code, message, details)` schema

4. **CORS**: Pre-configured for development

5. **Test Data**: 3 sample products + 7 measurement units (bilingual ru/en)

Documentation References

When users need deeper information, refer to:

Technology Stack

Code Examples

Repository Usage Pattern

```kotlin

// Transport → Business → Repository

val beProduct = transportProduct.toContext()

val result = repository.save(beProduct)

// Repository → Business → Transport

val savedProduct = result.toTransport()

```

Error Handling

Always return OpenAPI-compliant error responses:

```kotlin

Error(

code = "VALIDATION_ERROR",

message = "Invalid product data",

details = mapOf("field" to "name")

)

```