Implement milestones 0 and 1 with project and repository configuration, Work persistence, discussions, draft decisions, evidence integrity, and deterministic context exports. Add Java 25, Spring Boot and Modulith, native distributions, CI workflows, protocol documentation, and the pinned SDKMAN GraalVM CE toolchain. Validated with 20 passing tests and the macOS ARM64 native multi-repository continuity smoke.
101 lines
6.2 KiB
Markdown
101 lines
6.2 KiB
Markdown
# 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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|