Skip to content

Commit 20ddef0

Browse files
RaghuvorkadyRaghuvorkady
committed
2 parents 018f297 + 684640b commit 20ddef0

1 file changed

Lines changed: 260 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,71 @@ The system follows a microservices architecture where each service owns its own
1010

1111
### System Overview
1212
<!-- START_DIAGRAM_FLOWCHART -->
13+
```mermaid
14+
flowchart LR
15+
16+
%% ==========================================
17+
%% Nodes
18+
%% ==========================================
19+
FE["Frontend App"]
20+
TS["Transfer Service"]
21+
QS["Quote Service"]
22+
TR["Transfer Repository"]
23+
REDIS[("Redis Cache<br/>(Quotes)")]
24+
US["User Service"]
25+
CS["Compliance Service"]
26+
KAFKA[("Kafka<br/>Event Bus")]
27+
SS["Settlement Service"]
28+
EXT_FX["External FX API"]
29+
30+
%% ======================
31+
%% QUOTE FLOW
32+
%% ======================
33+
FE -- "(1) Request Quote" --> QS
34+
QS -- "(1.1) Get FX Rate" --> EXT_FX
35+
QS -- "(1.2) Cache Quote" --> REDIS
36+
37+
%% ======================
38+
%% TRANSFER REQUEST
39+
%% ======================
40+
FE -- "(2) Create Transfer Request" --> TS
41+
42+
TS -- "(2.1) Verify Idempotency Key" --> TR
43+
TS -- "(2.2) Record Transfer<br/>(INITIATED)" --> TR
44+
TS -- "(2.3) Validate Quote<br/>Cross-check Cache)" --> REDIS
45+
TS -- "(2.4) Validate User<br/>(Sync HTTP)" --> US
46+
TS -- "(2.5) Verify Compliance<br/>(Sync HTTP)" --> CS
47+
TS -- "(2.6) Update Transaction with Quote Details" --> TR
48+
TS -- "(2.7) Advance State = SETTLEMENT_IN_PROGRESS" --> TR
49+
50+
%% ======================
51+
%% EVENT-DRIVEN SETTLEMENT
52+
%% ======================
53+
TS -- "(2.8) Publish TRANSFER_CREATED" --> KAFKA
54+
KAFKA -- "(2.9) Consume TRANSFER_CREATED" --> SS
55+
SS -- "(2.10) Publish TRANSFER_SETTLED / TRANSFER_FAILED" --> KAFKA
56+
57+
KAFKA -- "(2.11) Consume Settlement Result" --> TS
58+
TS -- "(2.12) Update Status = COMPLETED / FAILED" --> TR
59+
60+
%% ==========================================
61+
%% Styling / Class Definitions
62+
%% ==========================================
63+
classDef controller fill:#e1f5fe,stroke:#01579b,stroke-width:1px;
64+
classDef messaging fill:#fff3e0,stroke:#e65100,stroke-width:1px;
65+
classDef repository fill:#f3e5f5,stroke:#4a148c,stroke-width:1px;
66+
classDef external fill:#e8f5e9,stroke:#1b5e20,stroke-width:1px;
67+
classDef infra fill:#eceff1,stroke:#263238,stroke-width:1px;
68+
69+
%% ==========================================
70+
%% Apply Styles
71+
%% ==========================================
72+
class FE controller;
73+
class TR repository;
74+
class EXT_FX external;
75+
class REDIS infra;
76+
class KAFKA messaging;
77+
```
1378
<!-- END_DIAGRAM_FLOWCHART -->
1479

1580

@@ -21,10 +86,205 @@ The system follows a microservices architecture where each service owns its own
2186

2287
### Microservice Internal Structure
2388
<!-- START_DIAGRAM_MICRO_SERVICE -->
89+
```mermaid
90+
flowchart TB
91+
92+
User((User)) --> FE["Frontend App"]
93+
94+
%% ======================
95+
%% Infrastructure
96+
%% ======================
97+
subgraph INFRA["**Core Infrastructure**"]
98+
REDIS[("Redis Cache<br/>(Quotes)")]
99+
KAFKA[("Kafka<br/>Event Bus")]
100+
end
101+
102+
EX_API["External FX API"]
103+
104+
%% ======================
105+
%% User Service
106+
%% ======================
107+
subgraph USER_SRV["**User Service**"]
108+
direction TB
109+
UC["UserController<br/>AuthController"]
110+
US["UserService"]
111+
UR["UserRepository"]
112+
UDB[("PostgreSQL<br/>user_db")]
113+
114+
UC --> US --> UR --> UDB
115+
end
116+
117+
%% ======================
118+
%% Transfer Service (Orchestrator)
119+
%% ======================
120+
subgraph TRANSFER_SRV["**Transfer Service**"]
121+
direction TB
122+
123+
subgraph TS_CLIENT["Downstream Clients"]
124+
TSC_CC["Compliance Client"]
125+
TSC_UC["User Client"]
126+
TSC_FX["FX Rate Client"]
127+
end
128+
129+
subgraph TS_MESSAGING["Message Handling"]
130+
T_SUB["CONSUMER<br/>SettlementResultListener"]
131+
T_PUB["PUBLISHER<br/>TransferEventPublisher"]
132+
end
133+
134+
TC["TransferController<br/>QuoteController"]
135+
TS["TransferService<br/>QuoteService"]
136+
TR["TransactionRepository"]
137+
TDB[("PostgreSQL<br/>transfer_db")]
138+
139+
TC --> TS --> TR --> TDB
140+
141+
%% Internal Orchestration
142+
TS --> TSC_CC
143+
TS --> TSC_UC
144+
TS --> TSC_FX
145+
TS --> T_PUB
146+
T_SUB --> TS
147+
end
148+
149+
%% ======================
150+
%% Compliance Service
151+
%% ======================
152+
subgraph COMPLIANCE_SRV["**Compliance Service**"]
153+
CC["ComplianceController"]
154+
CS["ComplianceService"]
155+
CC --> CS
156+
end
157+
158+
%% ======================
159+
%% Async Services
160+
%% ======================
161+
subgraph SETTLEMENT_SRV["**Settlement Service**"]
162+
SL["SettlementListener"]
163+
SS["SettlementService"]
164+
S_PUB["SettlementEventPublisher"]
165+
SL --> SS --> S_PUB
166+
end
167+
168+
subgraph NOTIFICATION_SRV["**Notification Service**"]
169+
NL["NotificationListener"]
170+
end
171+
172+
%% ======================
173+
%% Communication Paths
174+
%% ======================
175+
176+
FE -- "HTTPS" --> TC
177+
178+
%% Sync Orchestration
179+
TSC_UC -- "REST (Sync)" --> UC
180+
TSC_CC -- "REST (Sync)" --> CC
181+
TS -- "Check Cache" --> REDIS
182+
183+
%% External Integration
184+
TSC_FX -- "Fetch Rates" --> EX_API
185+
186+
%% Async Choreography
187+
T_PUB -- "TRANSFER_CREATED" --> KAFKA
188+
KAFKA -- "TRANSFER_CREATED" --> SL
189+
KAFKA -- "TRANSFER_CREATED / TRANSFER_SETTLED / TRANSFER_FAILED" --> NL
190+
191+
S_PUB -- "TRANSFER_SETTLED / TRANSFER_FAILED" --> KAFKA
192+
KAFKA -- "TRANSFER_SETTLED / TRANSFER_FAILED" --> T_SUB
193+
194+
%% ==========================================
195+
%% Styling / Class Definitions
196+
%% ==========================================
197+
classDef controller fill:#e1f5fe,stroke:#01579b,stroke-width:0.5px;
198+
classDef service fill:#fff3e0,stroke:#e65100,stroke-width:0.5px;
199+
classDef repository fill:#f3e5f5,stroke:#4a148c,stroke-width:0.5px;
200+
classDef database fill:#e8f5e9,stroke:#1b5e20,stroke-width:0.5px;
201+
classDef infra fill:#eceff1,stroke:#263238,stroke-width:0.5px;
202+
classDef messaging fill:#ffffb0,stroke:#fbc02d,stroke-width:0.5px;
203+
classDef client fill:#fcefec,stroke:#880e4f,stroke-width:0.5px;
204+
205+
%% ==========================================
206+
%% Apply Styles
207+
%% ==========================================
208+
class UC,TC,CC controller;
209+
class US,TS,CS,SS service;
210+
class UR,TR repository;
211+
class UDB,TDB,REDIS database;
212+
class KAFKA infra;
213+
class T_PUB,T_SUB,SL,S_PUB,NL messaging;
214+
class TS_CLIENT,TS_MESSAGING client;
215+
```
24216
<!-- END_DIAGRAM_MICRO_SERVICE -->
25217

26218
### Transaction Lifecycle (Sequence)
27219
<!-- START_DIAGRAM_SEQUENCE_CREATE_TRANSFER -->
220+
```mermaid
221+
sequenceDiagram
222+
autonumber
223+
participant FE as Frontend App
224+
participant QS as Quote Service
225+
participant EXT as External FX API
226+
participant REDIS as Redis / Cache
227+
participant TS as Transfer Service
228+
participant TR as Transfer Repository
229+
participant US as User Service
230+
participant CS as Compliance Service
231+
participant KAFKA as Kafka (Event Bus)
232+
participant SS as Settlement Service
233+
participant NS as Notification Service
234+
235+
Note over FE, REDIS: Phase 1: Quote Flow
236+
FE->>QS: Request Quote
237+
QS->>EXT: Fetch FX Rate
238+
QS->>REDIS: Cache Quote
239+
QS-->>FE: Quote Response (Quote ID)
240+
241+
Note over FE, CS: Phase 2: Transfer Request
242+
FE->>TS: Create Transfer Request (Idempotency-Key)
243+
244+
rect rgb(240, 240, 240)
245+
Note right of TS: Idempotency Guard
246+
TS->>TR: Verify Idempotency Key
247+
TR-->>TS: Result (Existing / None)
248+
end
249+
250+
TS->>TR: Record Transfer (INITIATED)
251+
252+
rect rgb(232, 245, 233)
253+
Note over TS, CS: Resilience Layer (Circuit Breaker & Retry)
254+
255+
par Checks
256+
TS->>REDIS: Validate Quote (Cross-check Cache)
257+
TS->>US: Validate User
258+
US-->>TS: 200 OK (Active)
259+
TS->>CS: Verify Compliance
260+
CS-->>TS: 200 OK (Cleared)
261+
end
262+
end
263+
264+
TS->>TR: Update Transaction with Quote Details
265+
TS->>TR: Advance State = SETTLEMENT_IN_PROGRESS
266+
TS-->>FE: 202 Accepted (Transaction ID)
267+
268+
Note over TS, NS: Phase 3: Settlement & Notifications
269+
TS->>KAFKA: Publish TRANSFER_CREATED
270+
271+
par Async Processing
272+
KAFKA->>SS: Consume TRANSFER_CREATED
273+
KAFKA->>NS: Consume TRANSFER_CREATED
274+
NS->>NS: Send "Transfer Received" Email
275+
end
276+
277+
SS->>SS: Process Settlement (External Rails)
278+
SS->>KAFKA: Publish TRANSFER_SETTLED / TRANSFER_FAILED
279+
280+
par Async Updates
281+
KAFKA->>TS: Consume Settlement Result
282+
KAFKA->>NS: Consume Settlement Result
283+
NS->>NS: Send "Transfer Complete/Failed" Email
284+
end
285+
286+
TS->>TR: Update Status = COMPLETED / FAILED
287+
```
28288
<!-- END_DIAGRAM_SEQUENCE_CREATE_TRANSFER -->
29289

30290
### 🔄 The Remittance Lifecycle

0 commit comments

Comments
 (0)