# Architecture ## Technology selection The project deliberately stays on a compatible maintenance pair: **Spring Boot 4.0.9 and Spring Modulith 2.0.9**. The published Modulith 2.0.9 POM declares Boot autoconfigure 4.0.9. Java compilation and bytecode target are both **25**, without preview features. Gradle **9.3.1** supports running on Java 25; its Wrapper distribution is pinned with SHA-256 verification. The local development JDK is pinned through `.sdkmanrc` to SDKMAN candidate `25.5.5.0+3-graalce` (GraalVM CE 25.5.5.0.3, OpenJDK 25.0.5.0.3). This [GraalVM innovation release](https://www.graalvm.org/release-notes/25.5/) still uses Java 25. It provides both JVM and Native Image tooling without changing compilation target or application dependencies. Use `sdk env` for project-scoped activation; the Gradle Wrapper remains responsible for the Gradle version. Primary compatibility references checked during implementation: - [Spring Boot 4.0 requirements](https://docs.spring.io/spring-boot/4.0/system-requirements.html): Java 25, Gradle 9 and GraalVM 25 are supported; Native Build Tools 0.11.5 is the documented version. - [Published Modulith 2.0.9 dependencies](https://repo.maven.apache.org/maven2/org/springframework/modulith/spring-modulith-core/2.0.9/spring-modulith-core-2.0.9.pom): Boot 4.0.9 dependency. - [Gradle Java compatibility](https://docs.gradle.org/9.3.1/userguide/compatibility.html): Java 25 support starts at Gradle 9.1. - [Spring AOT Gradle integration](https://docs.spring.io/spring-boot/4.0/gradle-plugin/aot.html). - [Picocli native configuration](https://picocli.info/#_graalvm_native_images): annotation-processor-generated reflection metadata. - [GraalVM 25 release notes](https://www.graalvm.org/release-notes/JDK_25/): macOS x86_64 support was removed. Picocli **4.7.7** handles argument validation, help and dispatch. Jackson 3 YAML/JSON comes from Boot's BOM. JUnit is explicitly pinned to **5.13.4** because the requested test baseline is JUnit 5; the Boot BOM otherwise selects a newer major generation. AssertJ and Modulith/ArchUnit verify behavior and dependencies. There is no Spring AI, Embabel, web starter, persistence server or workflow framework. ## Module boundaries All packages below are under `net.intrepid.aiengineering`. A module's base package is its explicit public API; implementation-only Git adapters live in `project.internal`. `package-info.java` declares allowed dependencies. `ArchitectureTest` calls `ApplicationModules.verify()` to enforce cycles, visibility and dependency rules. | Module | Owns | May depend on | |---|---|---| | filesystem | Protocol codecs, safe paths, atomic file writes, locks, errors | none | | project | Configuration, discovery, repository policy, read-only Git adapter | filesystem | | work | Work identity, lifecycle, repository snapshots and reference manifest | project, filesystem | | discussion | Append-only refinement entries and thread grouping | work, filesystem | | decision | Draft DEC records | work, filesystem | | artifact | Small evidence payloads and integrity metadata | work, filesystem | | verification | Structural conformance and portable context assembly | all protocol modules | | cli | Picocli commands, formats, exit codes | all APIs above | Spring owns the process lifecycle and CLI bean, and supplies AOT processing. Protocol services are ordinary Java classes with explicit path arguments and no retained Work cache. This keeps direct tests and fresh instances simple. Infrastructure dependencies remain inside services, outside immutable domain records. The small `GitAdapter` port is internal to Project and can be replaced without changing Work contracts. Context assembly belongs to Verification because it combines independently persisted modules and refuses to export structurally inconsistent state. Work does not depend on Discussion, Decision or Artifact, avoiding cycles. It owns stable references only. The engineering project is independent of repository count: a plain folder can use the protocol with no Git dependency, a single Git repository can register the root using `.`, and a larger workspace can register several child repositories. The same configuration schema and services support each case; no separate project mode or additional repository type is needed. ## Persistence and native execution Writers take an OS file lock per project. Complete UTF-8 files are written to a sibling temporary file, forced to disk and published atomically. New files use a hard link to avoid overwriting an existing destination. Existing files use atomic replacement; unsupported filesystems fail instead of quietly falling back to partial writes. New Works, projects and artifact payload bundles are staged before directory rename. See the protocol document for crash limits and recovery. Jackson parses explicit records, rejects unknown fields, duplicate YAML keys and unsupported schema versions. Native hints register those records; Picocli's annotation processor provides command reflection metadata. The Spring AOT tasks are wired by the native build plugin. No application arguments are passed through Spring's property parser. The entry point explicitly chooses non-web mode and closes its context. Discussion document version 2 separates typed YAML metadata from an opaque Markdown body. The filesystem codec maps that body to the domain record's existing `text` field; it does not infer structure from prose headings. The reader accepts legacy YAML-only text as well. Explicit migration backs up originals, preserves semantic state and skips converted files. Work and draft DEC persistence are unchanged; Markdown context renders discussion/decision prose without YAML escaping. ## Earlier framework review and migration Both implementations were inspected read-only: - The user-identified Python repository at `/Users/niltonconstantino/personal/workspace.personal/intrepid/discussion-framework`: README, model/locking/index persistence and structural validation. - The sibling Java `discussion-framework`: `DiscussionOrchestrator`, `WorkflowValidator`, `WorkPacket`, `ArtifactDocumentParser` and `FilesystemDiscussionRepository` concepts and implementations. Reused concepts: deterministic context as the handoff surface, stable IDs, explicit references, file locks, atomic replacement, duplicate/reference checks and separating content from mechanical CLI state management. No Python code or dependency was copied. The old generic Markdown inference was replaced by typed, versioned front matter; semantic sections are explicit and cannot silently disappear from context parsing. No legacy HTTP adapter, NDJSON global index, accepted-agenda gate, automatic housekeeping deletion or Lesson model was retained. Work is the project-scoped aggregate; Discussion is refinement within a Work. Source repositories were not changed. There is no automated legacy importer in Milestone 1. A future migration should create one Work per coherent agenda, retain original discussion/decision text with origin references, and verify identifiers and links before publication. Legacy Lessons should be reviewed for integration into canonical docs, not recreated as a required entity.