Files
ai-engineering/docs/architecture.md
T
bquarkz 8160c991a4 feat: support simple projects and root Git repositories
Allow registering a single Git repository at the engineering project root with --path . while retaining path safety checks.

Document Git-optional projects first and cover plain folders, root repositories, and multiple repositories in process tests and native smoke scenarios.

Validated with 23 passing tests and macOS ARM64 native smoke checks for all three layouts.
2026-11-11 16:38:18 +00:00

107 lines
6.6 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.
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.
## 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.