2.0 System Overview
Purpose: NLZ ACH transaction processing for one-time deposits, one-time withdrawals, and recurring/periodic ACH. Replaces OLZ investor-ach-api with cloud-native architecture.
2.1 System Context Diagram
graph TD
subgraph cam_process["cam-movemoney-process-api"]
CTRL["AchController"]
ACH["AchService
Channel Router"]
AV["AvAchService"]
SCA["ScaAchService"]
ELIG["EligibilityService
(inline)"]
COMP["ComplianceService
(inline)"]
COMMON["AchCommonService
Shared pipeline"]
QUEUE["AchQueueService"]
end
CTRL --> ACH
ACH -->|AV| AV
ACH -->|SCA| SCA
AV --> ELIG
AV --> COMP
AV --> COMMON
SCA --> COMMON
CTRL --> QUEUE
COMMON --> SYS["cam-movemoney-system-api"]
COMMON --> INST["cam-mm-instruction-system-api"]
COMMON --> ACCT(["Account Details"])
COMMON --> RTT(["RTT"])
COMMON --> KAFKA(["Kafka"])
SYS --> BETA(["BETA"])
style cam_process fill:#e6faf5,stroke:#00b894,color:#1a1d2e
style ELIG fill:#fde8e6,stroke:#e74c3c
style COMP fill:#fde8e6,stroke:#e74c3c
style SYS fill:#e3f0ff,stroke:#1e88e5
style BETA fill:#f0eeff,stroke:#6c5ce7
3.0 Design Considerations
3.1.1 System Inputs
| Endpoint | Input Model | Key Fields |
|---|
POST /ach/transaction | TransactionRequest | LplAccountNumber, Amount, TransactionType (ACHC/ACHD), BetaInstructionNumber, OriginId (AV/SCA), RequestedExecutionDate |
POST /ach/queueprocess | Query params | requestId, requestedBy, origin |
POST /ach/periodic-instruction | PeriodicInstructionRequest NEW | FrequencyCode (W/BW/M/Q/A), CycleBeginDate, CycleEndDate, Amount, AmountType, TransactionType |
3.1.2 System Outputs
| Output | Model | Key Fields |
|---|
| Transaction response | TransactionResponse | CmRequestId, Status, ErrorMessage |
| Kafka event | TransactionData | transactionId, status, accountNumber (masked), amount, timestamp |
3.1.3 System Behavior: 10-Step Pipeline
flowchart TD
S1["1. PARALLEL: Account + Restrictions
+ Transfers + Instructions"]
S2["2. Validate + Map + Insert DB
Status = Received"]
S3["3. Enqueue notification
(fire-and-forget)"]
S4["4. RTT → Submitted"]
S5["5a. EligibilityService (inline)
5b. ComplianceService (inline)"]
S6["6. Status → Approved + Audit"]
S7["7. Check Beta off-hours"]
S8["8. PostBeta via cam-system-api"]
S9["9. Patch Beta identifiers"]
S10["10. Status → Completed
RTT → Completed
Kafka event"]
S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9 --> S10
style S1 fill:#e3f0ff,stroke:#1e88e5
style S5 fill:#fde8e6,stroke:#e74c3c
style S8 fill:#f0eeff,stroke:#6c5ce7
style S10 fill:#e6faf5,stroke:#00b894
3.1.4 New: ACHD Withdrawal Additions
| Component | Change Required |
|---|
| AvAchService | Handle TransactionType=ACHD alongside ACHC |
| EligibilityService | Add ACHD rules: IRA distribution limits, margin account checks, high-dollar withdrawal threshold |
| cam-system-api BETA | Map distribution PECO codes (reference OLZ BetaRequestFactory.GetIrasPecoCode) |
| TaxWithholdingService NEW | FedTax/StateTax calculation, net vs gross distribution |
3.1.5 New: Periodic Instruction Schema
| Column | Type | Description |
|---|
| PeriodicInstructionId | int (PK) | Auto-increment identifier |
| InstructionId | int (FK) | Reference to bank instruction |
| LplAccountNo | varchar | Account number |
| TransactionType | varchar | ACHC or ACHD |
| FrequencyCode | varchar | W (weekly), BW (biweekly), M (monthly), Q (quarterly), A (annual) |
| AmountType | varchar | Fixed or Variable |
| Amount | decimal | Transaction amount |
| CycleBeginDate | datetime | First execution date |
| CycleEndDate | datetime (nullable) | Optional end date |
| Status | varchar | Active / Inactive / Cancelled |
| NextExecutionDate | datetime | Calculated next cycle date |
| LastExecutedDate | datetime (nullable) | Last successful execution |
3.1.6 PII Data Attributes
| Attribute | Classification | Protection |
|---|
| LplAccountNumber | PII / Confidential | Masked in logs (DataMaskUtility), encrypted at rest |
| BankAccountNumber | PII / Confidential | Masked in logs, encrypted at rest, TLS in transit |
| SSN (tax withholding) | PII / Restricted | Pass-through only, not stored in MM system |
3.1.7 Monitoring & Health Checks
- Structured JSON logging via Serilog (ELK forwarding)
- Correlation IDs on all requests (
ILplCorrelationContextAccessor)
- Health check endpoints: host, version, environment, memory
- Kafka event trail for transaction lifecycle tracking