Update ARCHITECTURE.md for ADR-030 layered API #270

New issue

Closed

opened 2025-12-31 16:49:05 -08:00 by jwilger · 1 comment

jwilger commented

2025-12-31 16:49:05 -08:00

(Migrated from github.com)

Summary

Update docs/ARCHITECTURE.md to reflect the layered crate API design from ADR-030.

Parent Issue

#266 Implement ADR-030: Layered Crate Public API Design
Depends on: #267, #268, #269

Sections to Update

Crate Organization Section

Update to clearly document:

eventcore is for application developers
eventcore-types is for backend implementers
What each crate exports and why

Feature Flag Ergonomics Section

Remove references to re-exporting everything from eventcore-types:

// OLD (remove)
pub use eventcore_types::*;

// NEW (replace with)
// Minimal re-exports for application developers
pub use eventcore_types::{CommandLogic, CommandStreams, ...};

Poll-Based Projections Section

Remove references to ProjectionRunner as public API
Emphasize run_projection(projector, &backend) as the only entry point
Remove PollMode, PollConfig, EventRetryConfig from documentation (internal)

Add New Section: Crate Audience Guide

Add a clear section explaining:

Application developers: Use eventcore crate
Backend implementers: Use eventcore-types crate
Test infrastructure: May need both, with clear separation

Acceptance Criteria

ARCHITECTURE.md accurately reflects the new layered API
No references to removed public types (ProjectionRunner, PollConfig, etc.)
Clear guidance on which crate to use for which purpose
Document version updated

## Summary Update `docs/ARCHITECTURE.md` to reflect the layered crate API design from ADR-030. ## Parent Issue - #266 Implement ADR-030: Layered Crate Public API Design - Depends on: #267, #268, #269 ## Sections to Update ### Crate Organization Section Update to clearly document: - `eventcore` is for application developers - `eventcore-types` is for backend implementers - What each crate exports and why ### Feature Flag Ergonomics Section Remove references to re-exporting everything from `eventcore-types`: ```rust // OLD (remove) pub use eventcore_types::*; // NEW (replace with) // Minimal re-exports for application developers pub use eventcore_types::{CommandLogic, CommandStreams, ...}; ``` ### Poll-Based Projections Section - Remove references to `ProjectionRunner` as public API - Emphasize `run_projection(projector, &backend)` as the only entry point - Remove `PollMode`, `PollConfig`, `EventRetryConfig` from documentation (internal) ### Add New Section: Crate Audience Guide Add a clear section explaining: - **Application developers**: Use `eventcore` crate - **Backend implementers**: Use `eventcore-types` crate - **Test infrastructure**: May need both, with clear separation ## Acceptance Criteria - [ ] ARCHITECTURE.md accurately reflects the new layered API - [ ] No references to removed public types (`ProjectionRunner`, `PollConfig`, etc.) - [ ] Clear guidance on which crate to use for which purpose - [ ] Document version updated

jwilger commented

2025-12-31 17:32:25 -08:00

(Migrated from github.com)

Closing: Parent issue closed