# Build Contract: Native Image

**Branch**: `005-native-image-deployment` | **Date**: 2026-04-07

## Overview

This contract defines what the native build produces and how consumers (developers, CI, docker-compose)
interact with it. The REST API contract is **unchanged** — all existing endpoints remain identical.

## Build Inputs

| Input | Required | Description |
|-------|----------|-------------|
| GraalVM JDK 25 | Yes (native profile only) | `JAVA_HOME` must point to GraalVM 25 |
| `DOCKER_HOST` / Docker daemon | Optional | Required for `jib:dockerBuild`; not needed for `jib:build` |
| `jib.to.image` Maven property | Optional | Override target image name; defaults to `ai-teacher-backend` |

## Build Outputs

| Profile | Command | Output |
|---------|---------|--------|
| Default (JVM) | `mvn package` | `target/ai-teacher-backend-*.jar` |
| Native | `mvn -Pnative package` | `target/ai-teacher-backend` (native executable) |
| Native + Docker | `mvn -Pnative package jib:dockerBuild` | Local Docker image `ai-teacher-backend:latest` |
| Native + Registry | `mvn -Pnative package jib:build` | Remote Docker image (configured via properties) |

## Docker Image Contract

| Property | Value |
|----------|-------|
| Base image | `gcr.io/distroless/base-nossl-debian12` |
| Entrypoint | `/app/ai-teacher-backend` (native executable) |
| Exposed port | `8080` |
| Architecture | `linux/amd64` (matches build host) |
| Required env vars | Same as JVM mode (`SPRING_DATASOURCE_URL`, `OPENAI_API_KEY`, etc.) |

## REST API Contract

Unchanged — the native image exposes the same HTTP API as the JVM image:

- `GET  /api/v1/books`
- `POST /api/v1/books` (multipart PDF upload)
- `DELETE /api/v1/books/{id}`
- `POST /api/v1/chat`
- `GET  /api/v1/chat/history`

All endpoints use the same request/response schemas.