001 Execution Architecture

# ADR-001: Execution Architecture - Monolith-First with Legacy Services Archived
 
## Status
 
Accepted
 
## Date
 
2024-12-29
 
## Context
 
RGL8R Product Blueprint v3.0 defines the current execution scope as:
- **SHIP** (freight audit) for KnifeCenter pilot
- **TRADE** (CBSA/SIMA compliance) for Wayfair pilot
 
The repo contains 13 microservices, but only 3 are needed for the current pilots. The Blueprint explicitly states: *"Initial implementation uses an in-process module dispatcher and a single deployable app. As modules stabilize and boundaries are proven, we'll peel them into independent services."*
 
### Problem Statement
 
1. The repo signals 13 services to build, but the current scope only requires SHIP + TRADE
2. Legacy Wayfair microservices exist but shouldn't become the default architecture
3. New engineers may build in the wrong place (services/ vs apps/api)
4. Label-transmitted dims/weight data isn't available yet, affecting SHIP scope
 
## Decision
 
### 1. apps/api is the primary runtime
 
New SHIP and TRADE capabilities go in `apps/api` with core logic in `packages/modules/*`. This is called via an in-process module dispatcher, not HTTP between services.
 
### 2. packages/modules/* contains core business logic
 
The modules (`@rgl8r/ship`, `@rgl8r/trade`, `@rgl8r/core`, etc.) are the reusable domain logic. They are imported directly, not called via network.
 
### 3. Wayfair pipeline consolidated into apps/api
 
The Wayfair flow now runs in-process inside `apps/api`. The legacy services
(`wayfair-adapter`, `attribute-validator`, `sima-risk`) are archived for reference only.
New customers (e.g., KnifeCenter) use `apps/api` directly.
 
### 4. 10 scaffolded services are future scope
 
These services are documented as "scaffolded only" and are not part of the current execution scope:
- landed-cost-engine
- validation-audit-service
- product-compliance-service
- licensing-graph-service
- duty-recovery-service
- external-calculator-adapters
- import-export-ledger
- customs-documentation-service
- compliance-rules-engine
- regulatory-ingestion-service
 
They will be activated in future phases when module boundaries are proven.
 
### 5. SHIP Phase 1 uses catalog data
 
Label-transmitted dims/weight per tracking are not yet available. Therefore:
- **Phase 1 SHIP = leak detection** (catalog vs billed variance)
- **Phase 2 SHIP = dispute-eligible audits** (once label data flows)
 
The audit engine is built now; the source of truth upgrades later.
 
### 6. KnifeCenter ingestion is CSV-first
 
The term "EDI 210" applies to motor carrier freight invoices (LTL/truckload). Parcel carrier exports (FedEx Billing Online, UPS Billing Center) are typically CSV/Excel. We will:
- Build CSV upload + column mapping first
- Add carrier-specific formats only when a customer explicitly needs them
 
## Consequences
 
### Positive
 
- **Faster iteration**: Single deployable, no distributed system debugging during pilots
- **Clear boundaries**: Everyone knows where new code goes (apps/api, not services/)
- **Reduced confusion**: Scaffolded services clearly marked as future
- **Flexible upgrade path**: Can peel services out later when boundaries stabilize
 
### Negative
 
- **Documentation overhead**: Must keep docs aligned with actual scope
 
### Neutral
 
- External broker/event-driven architecture is deferred, not rejected
- Scaffolded services remain in repo (not deleted) for future use
 
## Alternatives Considered
 
### A. Continue building all 13 services
 
**Rejected.** Too much complexity for the current scope. Blueprint says SHIP + TRADE only.
 
### B. Migrate Wayfair to in-process API
 
**Accepted.** Consolidated into `apps/api` to remove unnecessary infrastructure for the pilot.
 
### C. Delete scaffolded services
 
**Rejected.** Loses interface contracts and scaffolding. Doc-level labeling is sufficient.
 
## References
 
- Product Blueprint v3.0 (shared separately) - Section 3.1, "Explicit Scope Boundaries"
- [Engineering Review Pack](../ENGINEERING_REVIEW_PACK.md) - Current state assessment
- [Archived services README](../../_archived/services/README.md) - Legacy service status