ai-teacher/specs/005-native-image-deployment/spec.md

Feature Specification: Native Image Deployment

Feature Branch: 005-native-image-deployment Created: 2026-04-07 Status: Draft Input: Prepare the application for deployment using GraalVM native image for the backend, built into a Docker image via Jib.

User Scenarios & Testing (mandatory)

User Story 1 - Build Native Docker Image (Priority: P1)

A developer or CI pipeline runs a single Maven command to produce a Docker image containing the native-compiled backend binary. The image starts in under one second and uses significantly less memory than the JVM fat-jar image.

Why this priority: This is the core deliverable — without a working native Docker image the entire feature has no value.

Independent Test: Run mvn -Pnative jib:dockerBuild (or equivalent), start the resulting container, hit GET /api/v1/books, and receive a valid response. Startup log must show the server is ready in under 1 second.

Acceptance Scenarios:

1. Given a clean checkout with GraalVM installed, When the developer runs the native build command, Then a Docker image is produced without manual steps.
2. Given the produced Docker image, When the container is started with the required environment variables, Then the backend starts, connects to PostgreSQL, and serves HTTP requests correctly.
3. Given the produced Docker image, When a RAG chat request is made, Then it responds correctly (OpenAI call, pgvector retrieval, and Flyway migrations all work in native mode).

---

User Story 2 - JVM Mode Preserved (Priority: P2)

A developer who has not installed GraalVM can still build and run the backend the same way as today (fat-jar / existing Dockerfile), without any change to their workflow.

Why this priority: Preserving the developer experience for non-native builds ensures the team can keep iterating without a GraalVM prerequisite.

Independent Test: Run mvn package -DskipTests and start the resulting jar with java -jar — the application starts and serves requests identically to before this feature.

Acceptance Scenarios:

1. Given a standard JDK (no GraalVM), When mvn package is run, Then a fat-jar is produced and runs normally.
2. Given the existing Dockerfile, When docker build is run, Then a JVM-mode image is produced and works exactly as before.

---

User Story 3 - Docker Compose Full Stack (Priority: P3)

A developer can bring up the complete stack (PostgreSQL + native backend) with a single docker compose up command for local integration testing.

Why this priority: Makes it easy to validate the native image against the real database before pushing to any environment.

Independent Test: Run docker compose up (with native image tag), wait for healthy status, make a RAG request — all services communicate correctly.

Acceptance Scenarios:

1. Given the docker-compose.yml, When docker compose up is run with the native backend image, Then all services start, health checks pass, and the application is reachable.

---

Edge Cases

• What happens when a reflection-heavy library (PDFBox, AWS SDK) is called at runtime without proper native hints? → Must be caught at build time via native-image test or detected early via integration smoke test.
• What if GraalVM is not installed in CI? → Build must fail with a clear error message, not silently produce a JVM image.
• What if an environment variable required at runtime is missing? → Container must fail fast with a meaningful error (not a NullPointerException from missing reflection).

Requirements (mandatory)

Functional Requirements

• FR-001: The project MUST provide a native Maven profile that compiles the backend to a standalone native executable using GraalVM.
• FR-002: The native profile MUST include Spring Boot AOT processing to generate the reflection, serialization, and proxy hints required at compile time.
• FR-003: The Jib Maven plugin MUST be configured to package the native executable into a Docker image without requiring Docker daemon access during the build.
• FR-004: The resulting Docker image MUST start the backend in under 1 second on modern hardware (2+ CPU cores, 2 GB RAM).
• FR-005: All existing REST endpoints MUST function correctly in native mode (book upload, RAG chat, Flyway migrations, pgvector retrieval, Spring Security).
• FR-006: The JVM fat-jar build (default profile) MUST continue to work unchanged.
• FR-007: The README.md MUST be updated with native build instructions and updated architecture/deployment diagram.
• FR-008: The docker-compose.yml MUST be updated (or a companion file added) to support running the native Docker image alongside PostgreSQL.

Key Entities

• Native Profile: Maven build profile (native) that activates AOT processing and GraalVM native compilation.
• Docker Image: OCI image produced by Jib, containing the native executable and a minimal base OS layer.
• AOT Hints: Compile-time metadata (reflection, serialization, proxy) that replace runtime reflection for third-party libraries.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: The native Docker image starts and serves its first HTTP request in under 1 second on a machine with 2+ CPU cores and 2 GB RAM.
• SC-002: The native container's idle memory footprint is at least 40% lower than the equivalent JVM container running the same application.
• SC-003: All existing API endpoints return correct responses in native mode (0 regressions).
• SC-004: A developer with GraalVM installed can build the native Docker image with a single command documented in README.md.
• SC-005: The default JVM build and Dockerfile continue to work without any changes to the developer workflow.

Assumptions

• GraalVM 25 (CE or Oracle) will be available in CI and on developer machines that want to build native images.
• The native build is performed on Linux x86_64; cross-compilation for other architectures is out of scope for this feature.
• Spring Boot 4.0.5 and Spring AI 2.0.0-M4 have sufficient native image support for the features used (OpenAI chat/embedding, pgvector, Flyway, Spring Security, Spring Data JPA).
• The Docker registry target and image name/tag will be configured via Maven properties or environment variables, not hardcoded.
• Frontend deployment is out of scope for this feature; only the backend native image is addressed.
• The existing Dockerfile is kept as a fallback JVM image build; the Jib-built native image is the new primary artifact.