Files
ai-engineering/docs/architecture.md
T

115 lines
7.2 KiB
Markdown

# Architecture
AIE is a local engineering memory with two cycles: investigation/refinement and
implementation, connected by DEC and Plan. OODA is adaptive; gates constrain delivery.
The CLI records external observations and applies deterministic checks. It does not
execute repository commands, operate a server or provide distributed collaboration.
## Runtime and modules
Java 25, Gradle 9.3.1, Spring Boot 4.0.9, Modulith 2.0.9, Picocli 4.7.7 and Jackson 3
remain pinned by the build. JUnit 5.13.4, AssertJ and Modulith/ArchUnit verify behavior.
GraalVM CE 25.5.5.0+3 is pinned in .sdkmanrc. Spring supplies process lifecycle and AOT;
services are ordinary Java classes with explicit project paths and no retained Work
cache. Infrastructure stays outside immutable domain records.
| Module | Owns | May depend on |
|---|---|---|
| filesystem | Codecs, paths, SQLite sessions/typed storage, atomic external files and locks | none |
| project | Bootstrap, discovery, native/entry contracts and repository policy | filesystem |
| work | Work identity/guidance/lifecycle, source snapshots and EPIC graph/policy | project, filesystem |
| discussion | Entries, topics, surveys, answer history and dispositions | work, project, artifact, filesystem |
| decision | Drafts, approvals, revision and supersession | work, filesystem |
| planning | Plans, dependencies, results, experiments and scope exclusions | work, decision, discussion, artifact, filesystem |
| artifact | Temporary payloads, lifecycle, publication recovery and typed receipts | work, filesystem |
| agent | Proposal adapters, bounded local transport, validation and application | project, work, discussion, decision, planning, artifact, filesystem |
| legacyimport | Explicit DF preview/import, preserved originals and provenance | filesystem, project, work, discussion, artifact |
| verification | Integrity/readiness, gates, snapshots, coordination, migration and context | protocol modules |
| cli | Picocli commands and presentation | public module APIs |
ArchitectureTest enforces these boundaries. Work does not import Decision, Artifact
or Verification. Verification coordinates across independently owned domains.
## Storage boundary
New projects use `.ai-engineering/aie.db`, selected explicitly in the bootstrap.
Small configuration and entry files remain outside the database. File existence alone
never selects SQLite. Contract 4 and the database application/schema versions are
validated before use. Legacy decoding remains explicit and never converts on read.
SQLite JDBC 3.54.1.0 provides the embedded engine. SqliteDatabase owns connection
lifecycle, foreign keys, WAL/FULL durability, IMMEDIATE writes, snapshot reads and
bounded busy waits. Nested services share a transaction; failed nested mutations
cannot be accidentally committed after an exception is caught. File-publication
callbacks run after commit or rollback, after the connection closes.
SqliteRecords maps trusted record components to typed scalar columns and ordered
child rows. Composite operational values have a domain codec, not serialized file
content. List presence preserves null versus empty, necessary for historical hashes.
Identity/current-revision/format/reference tables retain ownership and revisions;
EPIC links have a unique child-parent index and foreign keys. Selected Work reads
use direct keys. Global integrity checks still inspect the whole project.
A project publication lock fences storage migration/rollback from writers. SQLite
commands wait a bounded interval and reject a backend transition observed while
waiting. Ordinary related reads need no file lock and use one database snapshot.
## Quality and temporary files
QualityGates stores required project definitions and cumulative Work additions.
Observed results bind procedures, actual invocation, inputs, Work scope/guidance,
DEC revisions, outcome and a short summary. Missing, failed or stale gates block
manual, Plan and EPIC delivery. Delivery snapshots bind the exact passed results.
Human approval remains a different record and responsibility.
Artifact bytes remain outside SQLite. Inputs stay available while the Work needs
checks. Completion atomically records validated retirement intent; after commit,
eligible payloads are unlinked and acknowledged. Pending retirement is repeatable
when deletion or acknowledgement was interrupted. New checks refuse retired inputs.
Structured Plan/EPIC receipts need no payload file. Legacy originals are preserved.
Requested outputs stay in their delivery destinations, outside the cleanup scope.
ArtifactPublication journals only owned publication intent. Rollback/recovery removes
its own orphan payload, never an unrelated file. Unknown residue is reported for
inspection. Local provider workspaces are bounded temporary directories; raw transport,
credentials, environment and complete logs do not become engineering memory.
## Authority, coordination and migration
Guidance preserves explicit human choices, DEC requests and approval policy.
Decision/Plan revisions enforce accepted authority, dependency completion, experiment
reconsideration and unresolved concerns. SQL promotion/supersession and related
references commit together. RUN failure rolls back its proposal and separately
records a short diagnostic without references to reverted records. Request replay
remains idempotent. No adapter can approve a DEC or answer on behalf of a human.
PlanCoordinator and EpicCoordinator retain SYSTEM_PLANS/SYSTEM_EPIC provenance,
RESULTS/DECOMPOSITION policy and explicit scope-bound delegation. Related SQL
mutations/propagation are transactional. Historical legacy semantics and hashes
remain readable; only the legacy backend retains per-file recovery boundaries.
StorageMigration previews canonical hashes, retains safety originals, imports typed
records in a separate database, compares content/authority/history and validates
before activation. Exact legacy bytes stay external for revision-chain verification;
readers also compare them with typed rows. Contract 4 and a visible legacy-reader
marker prevent incompatible writers. Recovery is repeatable; rollback refuses to
lose engineering memory written after activation. Existing tracked originals are
not removed. Details: [migration](storage-migration.md).
## Native package
`nativePackage` builds AIE and the pinned SQLite diagnostic CLI with companion native
libraries and a checksum manifest. Native hints cover operational records/resources.
The candidate verifier creates a disposable database with native AIE and reads it
with packaged sqlite3. Install preparation is distinct from activation: versioned
releases, a current symlink and shortcuts are switched only after verification.
Installer tests use fake tools and disposable destinations. This Work did not run
an actual installer or modify the active distribution or consumer projects.
Primary references: [SQLite JDBC native support](https://github.com/xerial/sqlite-jdbc#graalvm-native-image-support),
[SQLite transactions](https://sqlite.org/lang_transaction.html),
[foreign keys](https://sqlite.org/foreignkeys.html),
[official source releases/checksums](https://sqlite.org/download.html),
[Boot requirements](https://docs.spring.io/spring-boot/4.0/system-requirements.html),
[Gradle Java compatibility](https://docs.gradle.org/9.3.1/userguide/compatibility.html).