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

# Tasks: Native Image Deployment

**Input**: Design documents from `/specs/005-native-image-deployment/`
**Prerequisites**: plan.md ✅, spec.md ✅, research.md ✅, data-model.md ✅, contracts/ ✅

**Tests**: No test tasks — this feature has no unit/integration test requirements in the spec.
Smoke testing is part of US1 implementation (T010, T011).

**Organization**: Tasks grouped by user story for independent implementation and verification.

## Format: `[ID] [P?] [Story] Description`

- **[P]**: Can run in parallel (different files, no incomplete-task dependencies)
- **[Story]**: Which user story this task belongs to (US1, US2, US3)
- Paths use `backend/` and repo root (web app structure per constitution)

---

## Phase 1: Setup (Shared Infrastructure)

**Purpose**: Verify prerequisites and baseline before touching any build files.

- [ ] T001 Verify GraalVM 25 CE or Oracle GraalVM 25 is installed: run `native-image --version` and confirm output shows GraalVM 25; document install command (`sdk install java 25-graalce`) if missing
- [ ] T002 [P] Verify baseline JVM build passes: run `mvn package -DskipTests` inside `backend/` and confirm `target/ai-teacher-backend-*.jar` is produced

**Checkpoint**: GraalVM available, existing JVM build green — safe to modify build files

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Add AOT processing and native compilation support to the Maven build. These changes
are prerequisites for all user stories.

**⚠️ CRITICAL**: US1 cannot start until T007 confirms the native executable is produced.

- [ ] T003 Add `<profile id="native">` skeleton to `backend/pom.xml` and wire `spring-boot-maven-plugin` `process-aot` goal to the `prepare-package` phase inside that profile
- [ ] T004 Add `native-maven-plugin` 0.10.6 to the `native` profile in `backend/pom.xml` with executions `add-reachability-metadata` and `compile-no-fork` (phase `package`), image name `ai-teacher-backend`, and build args `--initialize-at-build-time=org.slf4j` and `-H:+ReportExceptionStackTraces`
- [ ] T005 [P] Create `backend/src/main/java/com/aiteacher/config/NativeHintsConfig.java` implementing `RuntimeHintsRegistrar`: register resource pattern `org/apache/pdfbox/resources/**` and reflection for `org.apache.pdfbox.pdmodel.font.encoding.GlyphList` with `MemberCategory.INVOKE_PUBLIC_CONSTRUCTORS`
- [ ] T006 Add `@ImportRuntimeHints(NativeHintsConfig.class)` annotation to the main `@SpringBootApplication` class in `backend/src/main/java/com/aiteacher/`
- [ ] T007 Run `mvn -Pnative package -DskipTests` inside `backend/` and confirm `target/ai-teacher-backend` native executable is produced; fix any AOT compilation errors before proceeding

**Checkpoint**: `target/ai-teacher-backend` exists and exits cleanly — US1 implementation can begin

---

## Phase 3: User Story 1 — Build Native Docker Image (Priority: P1) 🎯 MVP

**Goal**: One command (`mvn -Pnative package jib:dockerBuild`) produces a local Docker image
containing the native backend. Container starts in < 1 s and all REST endpoints work.

**Independent Test**: Start native container with DB env vars → `GET /api/v1/books` returns 200 →
startup log shows ready in under 1 second.

### Implementation for User Story 1

- [ ] T008 [US1] Add `jib-maven-plugin` 3.4.5 to `backend/pom.xml` `<build><plugins>` section (default build, not inside `native` profile): configure `<from><image>gcr.io/distroless/base-nossl-debian12</image></from>`, `<to><image>ai-teacher-backend</image></to>`, exposed port `8080`, and `<pluginExtensions>` referencing `com.google.cloud.tools.jib.maven.extension.nativeimage.JibNativeImageExtension`; add `jib-native-image-extension-maven` 0.1.0 as plugin `<dependency>`
- [ ] T009 [US1] Run `mvn -Pnative package jib:dockerBuild -DskipTests` inside `backend/` and confirm `docker images | grep ai-teacher-backend` shows the produced image
- [ ] T010 [US1] Start the native container with required env vars (`SPRING_DATASOURCE_URL`, `SPRING_DATASOURCE_USERNAME`, `SPRING_DATASOURCE_PASSWORD`, `OPENAI_API_KEY`) pointing to a local PostgreSQL; verify startup log shows "Started … in < 1.0 seconds" and `GET /api/v1/books` returns HTTP 200
- [ ] T011 [US1] Run full smoke test against the running native container: `POST /api/v1/books` (PDF upload), `POST /api/v1/chat` (RAG query), `GET /api/v1/chat/history`, and HTTP Basic auth enforcement; for each `MissingResourceException` or `ClassNotFoundException` found, add the corresponding entry to `backend/src/main/java/com/aiteacher/config/NativeHintsConfig.java` and rebuild (T009 → T010 loop) until all pass

**Checkpoint**: Native Docker image starts < 1 s, all 5 endpoints work — US1 complete ✅

---

## Phase 4: User Story 2 — JVM Mode Preserved (Priority: P2)

**Goal**: Default Maven build and existing Dockerfile continue to work with no changes required
from developers who do not have GraalVM installed.

**Independent Test**: `mvn package -DskipTests` produces a fat-jar; `docker build` using
`backend/Dockerfile` produces a working JVM container.

### Implementation for User Story 2

- [ ] T012 [P] [US2] Verify `mvn package -DskipTests` (no `-Pnative`) inside `backend/` still produces `target/ai-teacher-backend-*.jar`; confirm the jar starts correctly with `java -jar`
- [ ] T013 [P] [US2] Verify `docker build -t ai-teacher-backend-jvm backend/` using the existing `backend/Dockerfile` succeeds and the resulting JVM container starts and serves `GET /api/v1/books` correctly

**Checkpoint**: JVM path fully unchanged — US2 complete ✅

---

## Phase 5: User Story 3 — Docker Compose Full Stack (Priority: P3)

**Goal**: `docker compose -f docker-compose.native.yml up` starts PostgreSQL + native backend
together so developers can run the complete native stack locally with a single command.

**Independent Test**: `docker compose -f docker-compose.native.yml up` → all services healthy →
`GET http://localhost:8080/api/v1/books` returns 200.

### Implementation for User Story 3

- [ ] T014 [US3] Create `docker-compose.native.yml` at repo root: include `postgres` service (same image and config as `docker-compose.yml`), add `backend` service using image `ai-teacher-backend:latest` with all required env vars sourced from `.env`, `depends_on` postgres with health-check condition, and port mapping `8080:8080`
- [ ] T015 [P] [US3] Create `.env.example` at repo root listing all env vars needed by the native stack (`SPRING_DATASOURCE_URL`, `SPRING_DATASOURCE_USERNAME`, `SPRING_DATASOURCE_PASSWORD`, `OPENAI_API_KEY`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`) with placeholder values and inline comments

**Checkpoint**: Full native stack starts via docker compose — US3 complete ✅

---

## Phase 6: Polish & Cross-Cutting Concerns

**Purpose**: Constitution IV gate (README must be updated in the same PR as architectural change)
and final documentation alignment.

- [ ] T016 Update `README.md` at repo root: add a "Native Image Build" section with GraalVM install command (`sdk install java 25-graalce`), build command (`mvn -Pnative package jib:dockerBuild`), and run command (`docker compose -f docker-compose.native.yml up`); update the Mermaid architecture diagram to show the native build pipeline (Maven native profile → GraalVM native-image → Jib → Docker image)
- [ ] T017 [P] Update `specs/005-native-image-deployment/quickstart.md` with any corrections or additions discovered during implementation (env var names, exact commands, troubleshooting entries)

---

## Dependencies & Execution Order

### Phase Dependencies

- **Setup (Phase 1)**: No dependencies — start immediately
- **Foundational (Phase 2)**: Requires Phase 1 completion — **BLOCKS all user stories**
- **US1 (Phase 3)**: Requires Phase 2 (T007 must pass) — primary deliverable
- **US2 (Phase 4)**: Requires Phase 2 (T003–T006 must not break JVM path) — can run in parallel with US1 after Phase 2
- **US3 (Phase 5)**: Requires US1 completion (T009 must produce the Docker image)
- **Polish (Phase 6)**: Requires US1, US2, US3 all complete

### User Story Dependencies

- **US1 (P1)**: Unblocked after Foundational — critical path
- **US2 (P2)**: Unblocked after Foundational — can run in parallel with US1 (different verification commands, no file conflicts)
- **US3 (P3)**: Depends on US1 (needs the Docker image to exist for docker-compose)

### Within US1

T008 (Jib config) → T009 (build image) → T010 (verify startup) → T011 (smoke test + hint fixes, may loop back to T009)

### Parallel Opportunities

- T001 and T002 (Phase 1): both can run in parallel
- T003/T004 (pom.xml edits) are sequential (same file); T005 (new Java file) can run in parallel with T003/T004
- T012 and T013 (US2 verification): parallel, different commands
- T014 and T015 (US3 docker-compose + .env.example): parallel, different files
- T016 and T017 (Polish): parallel, different files
- US1 (Phase 3) and US2 (Phase 4) can run in parallel after Foundational completes

---

## Parallel Example: Foundational Phase

```bash
# In parallel — different files, no dependencies between them:
Task T005: "Create NativeHintsConfig.java in backend/src/main/java/com/aiteacher/config/"

# Sequential — same file (pom.xml):
Task T003: "Add native profile skeleton with spring-boot-maven-plugin process-aot"
Task T004: "Add native-maven-plugin 0.10.6 to native profile"  # after T003
```

## Parallel Example: After Foundational Completes

```bash
# US1 and US2 can start simultaneously:
Developer A → Phase 3 (US1): T008 → T009 → T010 → T011
Developer B → Phase 4 (US2): T012, T013 (parallel)
```

---

## Implementation Strategy

### MVP First (User Story 1 Only)

1. Complete Phase 1: Setup (T001, T002)
2. Complete Phase 2: Foundational (T003–T007) — **CRITICAL, do not skip T007**
3. Complete Phase 3: US1 (T008–T011)
4. **STOP and VALIDATE**: Native image starts < 1 s, all endpoints work
5. This alone satisfies FR-001 through FR-006 and SC-001 through SC-003

### Incremental Delivery

1. Phase 1 + Phase 2 → build toolchain ready
2. Phase 3 (US1) → native Docker image working (**MVP**)
3. Phase 4 (US2) → JVM fallback confirmed
4. Phase 5 (US3) → full native stack via docker compose
5. Phase 6 (Polish) → README updated (constitution IV gate — **required before merge**)

---

## Notes

- [P] tasks operate on different files or independent commands — safe to run concurrently
- US2 (T012, T013) can be verified at any time after Phase 2; they are quick sanity checks
- The hint-fix loop in T011 is the most likely source of iteration — budget extra time
- Constitution IV gate (README update, T016) is **mandatory** — PR cannot merge without it
- `.env.example` (T015) should be committed; actual `.env` must be in `.gitignore`