Reverse Engineering Your Software program Structure with Claude Code to Assist Claude Code – O’Reilly

I’ve been utilizing Claude Code for a wide range of functions, and one factor I’ve realized is that the extra it understands in regards to the performance of the system (the area, the use instances, the end-to-end flows), the extra it could possibly assist me.

For instance, after I paste a manufacturing error log, Claude can learn the stack hint, determine the affected code, and inform me if there’s a bug. However when the problem is extra advanced, like a buyer assist ticket, and there’s no stack hint, Claude is much less helpful.

The principle problem is that end-to-end processes are lengthy and complicated, spanning many code repositories. So simply asking Claude Code to investigate a single repository wasn’t going to work (and the default /init wasn’t producing adequate element even for this single codebase).

So I made a decision to make use of Claude Code to investigate the system to map out the end-to-end flows related to the area I work in in order that Claude Code (and people) can use this to deal with extra advanced challenges.

This put up shares what I knocked collectively in someday, constructing on data and tooling I’ve already gained from actual work examples and experiments.

That is one put up in a collection. You will discover the opposite posts right here.

This put up was written 100% by me. I requested Claude to generate the anonymized instance on the finish mirroring the kind of content material and elegance utilized in the true examples I created.

Setting the Preliminary Context

To start my venture, I created a really mild necessities doc:

# AI Structure Evaluation

This doc accommodates the directions for an necessary activity - utilizing AI to outline the structure of this technique, in order that it may be utilized by people and AI brokers to extra simply perceive the system.

## Goal

Map out all the flows that this software is concerned in (use sub brokers the place essential to work in parallel). A movement ought to map out the end-to-process from an motion within the UI (within the [readacted] repo) to a BFF, to backend APIs, or flows which can be triggered by occasions.

Flows ought to be documented in Mermaid format to permit AI brokers to know, for versioning (in git), and for simple visualization.

## Necessities

Every movement ought to have a descriptive title and will embrace:

1. The URL path of the web page the place the interplay is triggered
2. The URL path of the BFF endpoint (and the repository it lives in)
3. The URL path of calls made to downstream providers
4. Any database interactions
5. Any occasions produced or consumed (full title of occasion e.g. orders.orderPlaced)
6. Customers of occasions (if straightforward to determine)
7. Any workflows triggered (just like the synchronizeOrder)

To do that, you will want to look in different repositories, which could be discovered within the mother or father folder. The GitHub shopper will also be used if obligatory.

The listing of flows ought to dwell in ../flows/index.md and every particular person movement ought to be outlined in a separate folder.

# The place to seek out info

- /docs/structure accommodates varied folders describing the design of this technique and area data
- Every API venture on this repository ([redacted], [redacted]) has an openapi.json. This have to be used to determine all flows and validate. The [redacted] and [redacted] repositories even have openapi spec recordsdata
- The entities within the area [redacted], [redacted] [redacted] have methodology that clearly describe the area operations that may be carried out on them. Equally, every operation is invoke from a use case that clearly describes the use case

The output I would like is end-to-end flows like:
UI -> BFF -> API -> replace DB -> publish occasion -> handler -> use case -> publish occasion -> …

I don’t need 10 completely different sorts of structure diagrams and completely different ranges of element. I would like Claude Code to know the habits of the system so it could possibly determine anomalies (by manufacturing information and logs) and analyze the affect of potential adjustments.

I additionally created some mild details about the system in these two recordsdata:

The area ideas file explains the entities within the system. Very temporary clarification. The system overview file explains the connection between this codebase and different repositories, which is essential. Once more, it’s very mild—a bullet listing of repository names and one or two sentences describing their relationship to this one.

Looking out throughout a number of repositories

The directions for this activity dwell inside the principle repository of the area I work in. That is the middle of the universe for this agent, nevertheless it wants to have the ability to learn different repositories to affix up the end-to-end movement.

The answer I take advantage of for that is within the description above:

To do that, you will want to look in different repositories which could be discovered within the mother or father folder. The GitHub shopper will also be used if obligatory.

I give Claude the next permissions in .claude/settings.native.json and it could possibly then entry all of the repositories on machine or use the GitHub shopper if it thinks there are repositories I don’t have obtainable domestically:

"permissions": {
   "enable": [
     ...
     "Read(//Users/nicktune/code/**)",
     ...

Telling Claude where to look

You’ll notice the requirements also give Claude tips on where to look for key information like Open API spec files, which are like an index of the operations the application supports.

This is useful as a validation mechanism later in the flow. I would ask Claude, “List all of the API endpoints and events produced or consumed by this application—are there any that aren’t part of any flows.” I can then see if we may have missed anything important.

Mapping the First Flow

I put Claude in plan mode and asked it to read the file. It then popped up a short questionnaire asking me about my needs and preferences. One of the questions it asked was process related: Should we map out the whole system in parallel, work step-by-step, etc.?

I said, let’s do the first one together and use this as a template for the others to follow.

It took about two hours to build the first flow as I reviewed what Claude produced and gave feedback on what I needed. For example, at first it created a sequence diagram which looked nice but was too hard to read for complex flows that involve many repositories.

Eventually, we settled on horizontal flow diagrams where each repository is a container and we defined what steps could be. At first, it went too granular with the steps adding individual method calls.

### diagram.mermaid Requirements
**CRITICAL RULES:**
1. **File Format**: Must be pure Mermaid syntax with `.mermaid` extension- NO markdown headers
 - NO markdown code fences (no ` ```mermaid ` wrapper)
 - Starts directly with `flowchart LR`
2. **Use Swimlane Format**: `flowchart LR` (left-to-right with horizontal swimlanes)
 - Each repository is a horizontal swimlane (subgraph)
 - Flow progresses left to right
 - Swimlane labels should be prominent (use emoji for visibility)
 - Example: `subgraph systemA["🔧 systemA"]`
3. **Programs as Containers**:
 - Every repository MUST be a `subgraph` (horizontal swimlane)
 - Repository title is the subgraph label
 - Operations are nodes contained in the subgraph
 - Use `course LR` inside every subgraph
4. **Legitimate Step Sorts** - A step within the diagram can ONLY be one of many following:
 - **HTTP Endpoint**: Full endpoint path (e.g., `POST /blah/{blahId}/subblah`)
 - **Combination Technique Name**: Area methodology on an combination (e.g., `Order.place`, `Delivery.organiz`)
 - **Database Operation**: Proven with cylinder form `[(Database: INSERT order)]`
 - **Occasion Publication**: (e.g., `Publish: non-public.ordering.order.positioned`)
 - **Workflow Set off**: Should be labeled as workflow (e.g., `⚙️ Workflow: syncOrders`)
 - **Workflow Step**: Any step inside a workflow MUST embrace the workflow title as prefix (e.g., `syncOrderWorkflow: Replace legacy order`, `updateOrderInfo: POST /legacy/fill-order`)
 - **Lambda Invocation**: (e.g., `Lambda: blah-blah-lambda-blah-blah`)
 - **UI Actions**: Consumer interactions (e.g., `Present modal kind`, `Consumer enters firstName, lastName`)

I’ve added an anonymized movement on the finish of this doc.

I additionally had so as to add some corrections to Claude to make sure it was wanting in all the correct locations and understanding what sure ideas imply in different elements of our system; we weren’t simply iterating on the diagram for 2 hours.

Selecting the Subsequent Circulation

After the primary movement, the subsequent flows went a lot quicker. I verified the output of every movement and gave Claude suggestions, however usually round quarter-hour, and more often than not it was working so I may do different issues whereas ready.

One of many attention-grabbing challenges was deciding which flows are literally wanted? What’s a movement? The place ought to a movement begin and finish? What about relationships between flows?

Right here I used to be within the driving seat fairly a bit. I requested Claude to suggest flows (simply listing them earlier than analyzing) after which I requested it to point out me how every API endpoint and occasion match into the flows, and we used that to iterate a bit.

One of many issues I needed to do after Claude had produced the primary draft is to ask, “Are you certain there aren’t any different customers for these occasions that aren’t listed right here?” It will then do a extra thorough search and typically discover customers in repositories I didn’t have domestically. (It will use GitHub search.)

Studying worth

As I reviewed every use case, I used to be studying issues in regards to the system that I didn’t totally perceive or possibly there have been nuances I wasn’t conscious of. This alone would have justified all the hassle I spent on this.

Then I began to think about the worth for people who find themselves new to a codebase or a legacy system that no one understands anymore. Or possibly somebody who works in a unique crew and desires to determine how a bug or a change of their area is said to different domains.

Evolving the Necessities

As we went by way of the method, I frequently advised Claude to replace the necessities file. So after we’d completed the primary movement we had directions like this added to the file:

## Documentation Construction

Every movement have to be documented in a separate folder with the next construction:

```
docs/structure/flows/[flow-name]/
├── README.md              # Full documentation (all content material in a single file)
└── diagram.mermaid        # Mermaid diagram
```

**IMPORTANT**: Use ONLY these two recordsdata. Do NOT create separate diagram-notes.md or different recordsdata. Maintain all documentation consolidated in README.md for simpler upkeep.

### README.md Contents

**Use the blueprint as a template**: `docs/structure/flows/[redacted]/`

The file is now 449 traces lengthy.

One of many causes I did this was in order that I may begin a brand new Claude session, now or sooner or later, and not using a fully clear context window and execute the method to get related outcomes.

I did really use a brand new session to map every new movement to validate that the necessities had been considerably repeatable. On the whole they had been, however typically Claude would ignore some elements of the necessities. So on the finish, I advised it to assessment the necessities and examine the outputs, and it will normally determine a lot of the errors it had made and repair them.

Right here’s an instance of a few of the guidelines that began to construct up. Some had been to make sure Claude produced the correct kind of output, and a few had been to assist Claude keep away from widespread errors like Mermaid syntax errors.

### 2. Hint Workflows to Their Last Occasion
**Drawback**: Lacking occasions since you do not learn the precise workflow implementation.
**Rule**: While you encounter a workflow, you MUST:
1. Discover the workflow definition file (normally `.asl.json` for AWS Step Capabilities)
2. Learn the ENTIRE workflow to see ALL occasions it publishes
3. Doc EVERY occasion in sequence
**Instance from our blueprint**:
- We initially thought `[readacted]` ended with `[readacted]`
- Studying `[redacted].asl.json` revealed it really ends with `[readacted]`
- This occasion was CRITICAL to the movement persevering with
**File areas**:
- Integrations workflows: `[another-repo]/domains/*/workflows/*.asl.json`
- Search for `SendEvent` or `publish` actions within the workflow steps

Claude Code by no means follows each instruction as described. However including these guidelines does appear to extend the standard and scale back the variety of iterations wanted.

Testing the Output

After I mapped out 4 or 5 of the flows, I made a decision it was time to try it out—Does this info really assist Claude Code, or is it primarily only a human viewers that advantages from the outputs?

So I went into our assist ticket system and picked a ticket that seemed advanced. I requested my investigation agent to have a look at the ticket and determine the issue. However this time I added an additional step into its directions:

4. Determine the affected flows in /docs/structure/flows

As a part of its evaluation, it stated:

Let me discover the structure flows to know how [redacted] and [redacted] ought to be dealt with:

Then it produced its evaluation accurately figuring out the movement and anticipated behaviors:

## Affected Circulation

**[BlahA Upload and BlahB History Thing](../structure/flows/[redacted]/README.md)**

The [redacted] workflow ought to populate [redacted] information by way of:
- [redacted] choice ([redacted] customary OR [redacted] enhanced based mostly on `[redacted]` flag)
- Parallel execution of: DomainA, DomainB, DomainC, DomainD
- Publishing `order.blahBlahed` occasion on completion
…

And for the subsequent steps, it needed to question the occasions printed by the system to confirm that what really occurred matched the anticipated behaviors outlined within the movement:

### Step 1: Question [redacted] Occasions for Each [redacted]
**Goal:** Evaluate occasion historical past to determine what occurred otherwise between outdated and new [redacted]
**What to search for:**
- `[redacted event name]` - Did [redacted] full for brand new [redacted]?
- `[redacted event name]` - Have been [redacted] created?
- `[redacted event name]` - Have been [redacted] created?
- `[redacted event name]` - Did workflow full for brand new [redacted]?
- `[redacted event name]` - Last affirmation occasion
- Any error/failure occasions associated to the workflow

Beforehand, Claude would have needed to analyze the codebase to work out what ought to have occurred. It takes a very long time and takes up lots of context window for advanced duties, and the evaluation needs to be verified.

Now, Claude is aware of instantly in regards to the particular workflow and affected behaviors and may instantly start planning an investigation (if the documentation is correct sufficient). This evaluation is structured with the important thing info that I must see. I don’t must iterate with Claude to provide an evaluation within the format I would like.

On this case, Claude didn’t resolve the issue instantly, however the dialog was extra like I may need with a crew member—somebody who has a deeper understanding of how the system works and what may be fallacious right here relatively than simply utilizing Claude to investigate patterns in information, learn stack traces, or summarize textual content descriptions of the issue.

Accuracy and Hallucinations

I do suppose it’s proper to be involved about accuracy. We don’t need to make necessary decisions about our system based mostly on incomplete or incorrect particulars. And there have been vital inaccuracies that I needed to spot and proper. (Think about if I didn’t know they had been fallacious.)

I explored the problem of accuracy in this later put updisplaying how we will use deterministic instruments like ts-morph to construct the mannequin that people and AI can each profit from.

So right here’s what I’m pondering:

1. Typically we don’t want excellent accuracy. So long as the agent picks the correct path, it could possibly reinspect sure particulars or dive deeper as wanted.
2. We will construct checks and steps in into our CI pipelines to replace issues.
3. Often destroy and regenerate the flows (as soon as 1 / 4?).
4. Construct verification brokers or swarms.

After I noticed an error and requested a brand new agent to investigate the movement for inaccuracies, it rescanned the code and located what I noticed. So I believe choice 4 could be very credible—it’s simply extra effort to construct a verification system (which may make the general effort not price it).

However I’m undecided that is the optimum means of approaching the state of affairs. As an alternative…

The Subsequent Part of Platform Engineering

Avoiding the necessity to reverse engineer these flows might be key. And I’m beginning to suppose it will develop into the principle problem for platform engineering groups: How can we construct frameworks and tooling that expose our system as a graph of dependencies? Constructed into our platform in order that AI brokers don’t must reverse engineer; they will simply seek the advice of the supply of fact.

Issues ought to all occur transparently for software program engineers—you comply with the platform paved path, and every thing simply works. Corporations that do that, and particularly startups with no legacy, may immensely revenue from AI brokers.

Instruments like EventCatalog are in a robust place right here.

Instance Circulation

I simply requested Claude to translate considered one of my firm’s area flows right into a boring ecommerce instance. The design and naming will not be necessary; the kind of info and the visualization is what I’m making an attempt to convey.

Keep in mind, that is based mostly on someday of hacking round. I’m certain there are many enchancment alternatives right here. Let me know when you’ve got seen something higher.

The README

# Place Order with Cost and Success

**Standing**: Lively
**Kind**: Write Operation
**Complexity**: Excessive
**Final Up to date**: 2025-10-19

## Overview

This movement paperwork the method of putting an order in an ecommerce system, together with cost authorization, stock reservation, and cargo creation. That is the baseline order placement expertise the place:
- Orders begin with `standing: 'pending'`
- Cost is permitted earlier than stock reservation
- Stock is reserved upon profitable cost
- Cargo is created after stock reservation

## Circulation Boundaries

**Begin**: Buyer clicks "Place Order" button on checkout web page

**Finish**: Publication of `transport.shipment-created` occasion (public occasion with `DOMAIN` scope)

**Scope**: This movement covers your complete course of from preliminary order submission by way of cost authorization, stock reservation, cargo creation, and all asynchronous unwanted effects triggered by these operations.

## Fast Reference

### API Endpoints

| Endpoint | Technique | Repository | Goal |
|----------|--------|------------|---------|
| `/checkout` | GET | storefront-app | Checkout web page |
| `/api/orders` | POST | order-api | Creates order |
| `/api/funds/authorize` | POST | payment-api | Authorizes cost |
| `/api/stock/reserve` | POST | inventory-api | Reserves stock |
| `/api/shipments` | POST | shipping-api | Creates cargo |
| `/api/orders/{orderId}/standing` | GET | order-api | Frontend polls for order standing |

### Occasions Reference

| Occasion Title | Area | Topic | Goal | Customers |
|------------|--------|---------|---------|-----------|
| `non-public.orders.order.created` | ORDERS | order | Order creation | PaymentHandler, AnalyticsHandler |
| `non-public.funds.cost.licensed` | PAYMENTS | cost | Cost licensed | InventoryReservationHandler |
| `non-public.funds.cost.failed` | PAYMENTS | cost | Cost failed | OrderCancellationHandler |
| `non-public.stock.inventory.reserved` | INVENTORY | inventory | Stock reserved | ShipmentCreationHandler |
| `non-public.stock.inventory.inadequate` | INVENTORY | inventory | Inadequate inventory | OrderCancellationHandler |
| `non-public.transport.cargo.created` | SHIPPING | cargo | Cargo created | NotificationHandler |
| `transport.shipment-created` | SHIPPING | cargo | **PUBLIC** Cargo created | Exterior customers |

### Database Tables

| Desk | Operation | Key Fields | Goal |
|-------|-----------|------------|---------|
| `orders` | INSERT | orderId, customerId, standing="pending", totalAmount | Order combination storage |
| `order_items` | INSERT | orderItemId, orderId, productId, amount, value | Order line gadgets |
| `funds` | INSERT | paymentId, orderId, quantity, standing="licensed" | Cost combination storage |
| `inventory_reservations` | INSERT | reservationId, orderId, productId, amount | Stock reservation monitoring |
| `shipments` | INSERT | shipmentId, orderId, trackingNumber, standing="pending" | Cargo combination storage |

### Area Operations

| Combination | Technique | Goal |
|-----------|--------|---------|
| Order | `Order.create()` | Creates new order with pending standing |
| Order | `Order.confirmPayment()` | Marks cost as confirmed |
| Order | `Order.cancel()` | Cancels order as a result of cost or stock failure |
| Cost | `Cost.authorize()` | Authorizes cost for order |
| Cost | `Cost.seize()` | Captures licensed cost |
| Stock | `Stock.reserve()` | Reserves inventory for order |
| Cargo | `Cargo.create()` | Creates cargo for order |

## Key Traits

| Side | Worth |
|--------|-------|
| Order Standing | Makes use of `standing` subject: `'pending'` → `'confirmed'` → `'shipped'` |
| Cost Standing | Makes use of `standing` subject: `'pending'` → `'licensed'` → `'captured'` |
| Stock Technique | Reserve-on-payment strategy |
| Cargo Standing | Makes use of `standing` subject: `'pending'` → `'prepared'` → `'shipped'` |

## Circulation Steps

1. **Buyer** navigates to checkout web page in storefront-app (`/checkout`)
2. **Buyer** opinions order particulars and clicks "Place Order" button
3. **storefront-app UI** reveals loading state with order affirmation message
4. **storefront-app** sends POST request to order-api (`/api/orders`)
  - Request contains: customerId, gadgets (productId, amount, value), shippingAddress, billingAddress
5. **order-api** creates Order combination with `standing: 'pending'` and persists to database
6. **order-api** creates OrderItem data for every merchandise within the order
7. **order-api** publishes `non-public.orders.order.created` occasion
8. **order-api** returns orderId and order particulars to storefront-app
9. **storefront-app** redirects buyer to order affirmation web page

### Asynchronous Facet Results - Cost Processing

10. **order-events-consumer** receives `non-public.orders.order.created` occasion
11. **PaymentHandler** processes the occasion
   - Calls payment-api to authorize cost
12. **payment-api** calls exterior cost gateway (Stripe, PayPal, and so forth.)
13. **payment-api** creates Cost combination with `standing: 'licensed'` and persists to database
14. **payment-api** publishes `non-public.funds.cost.licensed` occasion (on success)
   - OR publishes `non-public.funds.cost.failed` occasion (on failure)

### Asynchronous Facet Results - Stock Reservation

15. **payment-events-consumer** receives `non-public.funds.cost.licensed` occasion
16. **InventoryReservationHandler** processes the occasion
   - Calls inventory-api to order inventory
17. **inventory-api** masses Stock combination for every product
18. **inventory-api** calls `Stock.reserve()` for every order merchandise
   - Validates adequate inventory obtainable
   - Creates reservation report
   - Decrements obtainable inventory
19. **inventory-api** creates InventoryReservation data and persists to database
20. **inventory-api** publishes `non-public.stock.inventory.reserved` occasion (on success)
   - OR publishes `non-public.stock.inventory.inadequate` occasion (on failure)

### Asynchronous Facet Results - Cargo Creation

21. **inventory-events-consumer** receives `non-public.stock.inventory.reserved` occasion
22. **ShipmentCreationHandler** processes the occasion
   - Calls shipping-api to create cargo
23. **shipping-api** creates Cargo combination with `standing: 'pending'` and persists to database
24. **shipping-api** calls exterior transport provider API to generate monitoring quantity
25. **shipping-api** updates Cargo with trackingNumber
26. **shipping-api** publishes `non-public.transport.cargo.created` occasion
27. **shipping-events-consumer** receives `non-public.transport.cargo.created` occasion
   - **ShipmentCreatedPublicHandler** processes the occasion
   - Hundreds cargo from repository to get full cargo particulars
   - Publishes public occasion: `transport.shipment-created`
   - **This marks the END of the movement**

### Order Standing Updates

28. All through the movement, order-api receives occasions and updates order standing:
   - On `non-public.funds.cost.licensed`: Updates order with paymentId
   - On `non-public.stock.inventory.reserved`: Updates order to `standing: 'confirmed'`
   - On `non-public.transport.cargo.created`: Updates order to `standing: 'shipped'`

### Failure Situations

**Cost Failure**:
- On `non-public.funds.cost.failed`: OrderCancellationHandler cancels order
- Order standing up to date to `'cancelled'`
- Buyer notified by way of e mail

**Stock Failure**:
- On `non-public.stock.inventory.inadequate`: OrderCancellationHandler cancels order
- Cost authorization is voided
- Order standing up to date to `'cancelled'`
- Buyer notified by way of e mail with choice to backorder

## Repositories Concerned

- **storefront-app**: Frontend UI
- **order-api**: Order area
- **payment-api**: Cost area
- **inventory-api**: Stock area
- **shipping-api**: Delivery and success area
- **notification-api**: Buyer notifications

## Associated Flows

- **Course of Refund**: Circulation for dealing with order refunds and returns
- **Replace Cargo Standing**: Circulation for monitoring cargo supply standing
- **Stock Reconciliation**: Circulation for syncing stock counts with warehouse methods

## Occasions Produced

| Occasion | Goal |
|-------|---------|
| `non-public.orders.order.created` | Notifies {that a} new order has been created |
| `non-public.funds.cost.licensed` | Notifies that cost has been licensed |
| `non-public.funds.cost.failed` | Notifies that cost authorization failed |
| `non-public.stock.inventory.reserved` | Notifies that stock has been reserved |
| `non-public.stock.inventory.inadequate` | Notifies that inadequate stock is on the market |
| `non-public.transport.cargo.created` | Inner occasion that cargo has been created |
| `transport.shipment-created` | **Public occasion** that cargo is created and prepared for provider pickup |

## Occasion Customers

### `non-public.orders.order.created` Customers

#### 1. order-events-consumer

**Handler**: `PaymentHandler`

**Goal**: Initiates cost authorization course of

**Actions**:
- Subscribes to occasion
- Calls `AuthorizePayment` use case
- Invokes payment-api to authorize cost with cost gateway
- Publishes cost consequence occasion

#### 2. order-events-consumer

**Handler**: `AnalyticsHandler`

**Goal**: Tracks order creation for analytics

**Actions**:
- Subscribes to occasion
- Sends order information to analytics platform
- Updates conversion monitoring

### `non-public.funds.cost.licensed` Client

#### payment-events-consumer

**Handler**: `InventoryReservationHandler`

**Goal**: Reserves stock after profitable cost

**Actions**:
- Subscribes to occasion
- Calls `ReserveInventory` use case
- Hundreds order particulars
- Calls inventory-api to order inventory for every merchandise
- Publishes stock reservation consequence occasion

### `non-public.funds.cost.failed` Client

#### payment-events-consumer

**Handler**: `OrderCancellationHandler`

**Goal**: Cancels order when cost fails

**Actions**:
- Subscribes to occasion
- Calls `CancelOrder` use case
- Updates order standing to 'cancelled'
- Triggers buyer notification

### `non-public.stock.inventory.reserved` Client

#### inventory-events-consumer

**Handler**: `ShipmentCreationHandler`

**Goal**: Creates cargo after stock reservation

**Actions**:
- Subscribes to occasion
- Calls `CreateShipment` use case
- Calls shipping-api to create cargo report
- Integrates with transport provider API for monitoring quantity
- Publishes cargo created occasion

### `non-public.stock.inventory.inadequate` Client

#### inventory-events-consumer

**Handler**: `OrderCancellationHandler`

**Goal**: Cancels order when stock is inadequate

**Actions**:
- Subscribes to occasion
- Calls `CancelOrder` use case
- Voids cost authorization
- Updates order standing to 'cancelled'
- Triggers buyer notification with backorder choice

### `non-public.transport.cargo.created` Client

#### shipping-events-consumer

**Handler**: `ShipmentCreatedPublicHandler`

**Goal**: Converts non-public cargo occasion to public occasion

**Actions**:
- Subscribes to `non-public.transport.cargo.created` occasion
- Hundreds cargo from repository
- Publishes public occasion: `transport.shipment-created`

**Handler**: `NotificationHandler`

**Goal**: Notifies buyer of cargo creation

**Actions**:
- Subscribes to occasion
- Sends affirmation e mail with monitoring quantity
- Sends SMS notification (if opted in)

## Database Operations

### orders Desk
- **Operation**: INSERT (by way of upsert)
- **Key Fields**: orderId, customerId, standing="pending", totalAmount, createdAt
- **Repository**: `OrderRepository`

### order_items Desk
- **Operation**: INSERT (batch)
- **Key Fields**: orderItemId, orderId, productId, amount, value
- **Repository**: `OrderItemRepository`

### funds Desk
- **Operation**: INSERT (by way of upsert)
- **Key Fields**: paymentId, orderId, quantity, standing="licensed", gatewayTransactionId
- **Repository**: `PaymentRepository`

### inventory_reservations Desk
- **Operation**: INSERT (by way of upsert)
- **Key Fields**: reservationId, orderId, productId, amount, reservedAt
- **Repository**: `InventoryReservationRepository`

### shipments Desk
- **Operation**: INSERT (by way of upsert)
- **Key Fields**: shipmentId, orderId, trackingNumber, standing="pending", provider
- **Repository**: `ShipmentRepository`

## Exterior Integrations

- **Cost Gateway Integration**: Authorizes and captures funds by way of Stripe API
 - Endpoint: `/v1/payment_intents`
 - Synchronous name throughout cost authorization

- **Delivery Provider Integration**: Generates monitoring numbers by way of provider API
 - Endpoint: `/api/v1/shipments`
 - Synchronous name throughout cargo creation

## What Occurs After This Circulation

This movement ends with the publication of the `transport.shipment-created` public occasion, which marks the order as totally processed and prepared for provider pickup.

### State at Circulation Completion
- Order: `standing: 'shipped'`
- Cost: `standing: 'licensed'` (might be captured on precise cargo)
- Stock: Inventory reserved and decremented
- Cargo: `standing: 'pending'`, trackingNumber assigned

### Subsequent Steps
After this movement completes:
- Warehouse crew picks and packs the order
- Provider picks up the cargo
- Delivery standing updates movement tracks supply
- Cost is captured upon confirmed cargo
- Buyer can observe order by way of monitoring quantity

### Exterior System Integration
As soon as the `transport.shipment-created` occasion is printed:
- Warehouse administration system begins choose/pack course of
- Buyer notification system sends monitoring updates
- Logistics companions obtain cargo manifest
- Analytics methods observe success metrics

## Diagram

See [diagram.mermaid](./diagram.mermaid) for the whole visible movement displaying the development by way of methods with horizontal swim lanes for every service.

The Mermaid:

flowchart LR
   Begin([Customer clicks Place Order
on checkout page])

   subgraph storefront["🌐 storefront-app"]
       course LR
       ShowCheckout[Show checkout page]
       CustomerReview[Customer reviews order]
       ShowConfirmation[Show order
confirmation page]
   finish

 CustomerWaitsForShipment([Customer receives
shipment notification])

subgraph orderService["📦 order-api"]
       course LR
       CreateOrderEndpoint["POST /api/orders"]
       OrderCreate[Order.create]
       OrderDB[(Database:
INSERT orders,
order_items)]
       PublishOrderCreated["Publish: private.orders
.order.created"]
       ReceivePaymentAuth["Receive: private.payments
.payment.authorized"]
       UpdateOrderPayment[Update order
with paymentId]
       ReceiveStockReserved["Receive: private.inventory
.stock.reserved"]
       OrderConfirm[Order.confirmPayment]
       UpdateOrderConfirmed[(Database:
UPDATE orders
status="confirmed")]
       ReceiveShipmentCreated["Receive: private.shipping
.shipment.created"]
       UpdateOrderShipped[(Database:
UPDATE orders
status="shipped")]
   finish

 subgraph paymentService["💳 payment-api"]
       course LR
       ReceiveOrderCreated["Receive: private.orders
.order.created"]
       AuthorizeEndpoint["POST /api/payments/
authorize"]
       PaymentGateway["External: Payment
Gateway API
(Stripe)"]
       PaymentAuthorize[Payment.authorize]
       PaymentDB[(Database:
INSERT payments)]
       PublishPaymentAuth["Publish: private.payments
.payment.authorized"]
   finish

 subgraph inventoryService["📊 inventory-api"]
       course LR
       ReceivePaymentAuth2["Receive: private.payments
.payment.authorized"]
       ReserveEndpoint["POST /api/inventory/
reserve"]
       InventoryReserve[Inventory.reserve]
       InventoryDB[(Database:
INSERT inventory_reservations
UPDATE product stock)]
       PublishStockReserved["Publish: private.inventory
.stock.reserved"]
   finish

 subgraph shippingService["🚚 shipping-api"]
       course LR
       ReceiveStockReserved2["Receive: private.inventory
.stock.reserved"]
       CreateShipmentEndpoint["POST /api/shipments"]
       CarrierAPI["External: Shipping
Carrier API
(FedEx/UPS)"]
       ShipmentCreate[Shipment.create]
       ShipmentDB[(Database:
INSERT shipments)]
       PublishShipmentCreated["Publish: private.shipping
.shipment.created"]
       ReceiveShipmentCreatedPrivate["Receive: private.shipping
.shipment.created"]
       LoadShipment[Load shipment
from repository]
       PublishPublicEvent["Publish: shipping
.shipment-created"]
       FlowEnd([Flow End:
Public event published])
   finish

   Begin --> ShowCheckout
   ShowCheckout --> CustomerReview
   CustomerReview --> CreateOrderEndpoint
   CreateOrderEndpoint --> OrderCreate
   OrderCreate --> OrderDB
   OrderDB --> PublishOrderCreated
   PublishOrderCreated --> ShowConfirmation

   PublishOrderCreated -.-> ReceiveOrderCreated
   ReceiveOrderCreated --> AuthorizeEndpoint
   AuthorizeEndpoint --> PaymentGateway
   PaymentGateway --> PaymentAuthorize
   PaymentAuthorize --> PaymentDB
   PaymentDB --> PublishPaymentAuth

   PublishPaymentAuth -.-> ReceivePaymentAuth
   ReceivePaymentAuth --> UpdateOrderPayment

   PublishPaymentAuth -.-> ReceivePaymentAuth2
   ReceivePaymentAuth2 --> ReserveEndpoint
   ReserveEndpoint --> InventoryReserve
   InventoryReserve --> InventoryDB
   InventoryDB --> PublishStockReserved

   PublishStockReserved -.-> ReceiveStockReserved
   ReceiveStockReserved --> OrderConfirm
   OrderConfirm --> UpdateOrderConfirmed

   PublishStockReserved -.-> ReceiveStockReserved2
   ReceiveStockReserved2 --> CreateShipmentEndpoint
   CreateShipmentEndpoint --> CarrierAPI
   CarrierAPI --> ShipmentCreate
   ShipmentCreate --> ShipmentDB
   ShipmentDB --> PublishShipmentCreated

   PublishShipmentCreated -.-> ReceiveShipmentCreated
   ReceiveShipmentCreated --> UpdateOrderShipped

   PublishShipmentCreated -.-> ReceiveShipmentCreatedPrivate
   ReceiveShipmentCreatedPrivate --> LoadShipment
   LoadShipment --> PublishPublicEvent
   PublishPublicEvent --> FlowEnd

   FlowEnd -.-> CustomerWaitsForShipment

   type Begin fill:#e1f5e1
   type FlowEnd fill:#ffe1e1
   type CustomerWaitsForShipment fill:#e1f5e1
   type PublishOrderCreated fill:#fff4e1
   type PublishPaymentAuth fill:#fff4e1
   type PublishStockReserved fill:#fff4e1
   type PublishShipmentCreated fill:#fff4e1
   type PublishPublicEvent fill:#fff4e1
   type OrderDB fill:#e1f0ff
   type PaymentDB fill:#e1f0ff
   type InventoryDB fill:#e1f0ff
   type ShipmentDB fill:#e1f0ff
   type UpdateOrderConfirmed fill:#e1f0ff
   type UpdateOrderShipped fill:#e1f0ff
   type PaymentGateway fill:#ffe1f5
   type CarrierAPI fill:#ffe1f5