[{"data":1,"prerenderedAt":835},["ShallowReactive",2],{"page-\u002Fv1\u002Fcore\u002Fgolden-flow":3},{"id":4,"title":5,"body":6,"description":828,"extension":829,"meta":830,"navigation":100,"path":831,"seo":832,"stem":833,"__hash__":834},"content\u002Fv1\u002Fcore\u002Fgolden-flow.md","Golden flow",{"type":7,"value":8,"toc":818},"minimark",[9,13,21,24,29,223,355,359,398,440,444,596,601,681,685,691,695,699,755,759,800,814],[10,11,5],"h1",{"id":12},"golden-flow",[14,15,16,20],"p",{},[17,18,19],"strong",{},"Purpose:"," show the exact ordered path of one request inside a single module (e.g. Ordering placing an order).",[14,22,23],{},"The compact “cycle” diagram often confuses readers by mixing descent and ascent. Below they are separated, then a sequence shows time order.",[25,26,28],"h2",{"id":27},"_1-request-descent-inward","1. Request descent (inward)",[30,31,36],"pre",{"className":32,"code":33,"language":34,"meta":35,"style":35},"language-mermaid shiki shiki-themes github-light github-dark","flowchart TD\n    subgraph Step1[\"1 — Delivery\"]\n        HTTP[HTTP request]\n        CTRL[UI Controller]\n        REQ[Input validation\u003Cbr\u002F>shape only]\n        HTTP --> CTRL\n        CTRL -->|authorize + validate| REQ\n        REQ -->|validated data| CTRL\n    end\n\n    subgraph Step2[\"2 — Application boundary\"]\n        DTO[Application DTO]\n        UC[First-level Use Case]\n        CTRL -->|map validated → DTO| DTO\n        CTRL -->|invoke| UC\n        DTO --> UC\n    end\n\n    subgraph Step3[\"3 — Domain work\"]\n        ENT[Domain Entities \u002F Services]\n        PORT[Domain Port interface]\n        UC --> ENT\n        UC -->|depends on interface only| PORT\n    end\n\n    subgraph Step4[\"4 — Infrastructure\"]\n        ADAPTER[Adapter implementation]\n        EXT[(Database \u002F peer \u002F external API)]\n        PORT -.->|bound in composition root| ADAPTER\n        ADAPTER --> EXT\n    end\n","mermaid","",[37,38,39,47,53,59,65,71,77,83,89,95,102,108,114,120,126,132,138,143,148,154,160,166,172,178,183,188,194,200,206,212,218],"code",{"__ignoreMap":35},[40,41,44],"span",{"class":42,"line":43},"line",1,[40,45,46],{},"flowchart TD\n",[40,48,50],{"class":42,"line":49},2,[40,51,52],{},"    subgraph Step1[\"1 — Delivery\"]\n",[40,54,56],{"class":42,"line":55},3,[40,57,58],{},"        HTTP[HTTP request]\n",[40,60,62],{"class":42,"line":61},4,[40,63,64],{},"        CTRL[UI Controller]\n",[40,66,68],{"class":42,"line":67},5,[40,69,70],{},"        REQ[Input validation\u003Cbr\u002F>shape only]\n",[40,72,74],{"class":42,"line":73},6,[40,75,76],{},"        HTTP --> CTRL\n",[40,78,80],{"class":42,"line":79},7,[40,81,82],{},"        CTRL -->|authorize + validate| REQ\n",[40,84,86],{"class":42,"line":85},8,[40,87,88],{},"        REQ -->|validated data| CTRL\n",[40,90,92],{"class":42,"line":91},9,[40,93,94],{},"    end\n",[40,96,98],{"class":42,"line":97},10,[40,99,101],{"emptyLinePlaceholder":100},true,"\n",[40,103,105],{"class":42,"line":104},11,[40,106,107],{},"    subgraph Step2[\"2 — Application boundary\"]\n",[40,109,111],{"class":42,"line":110},12,[40,112,113],{},"        DTO[Application DTO]\n",[40,115,117],{"class":42,"line":116},13,[40,118,119],{},"        UC[First-level Use Case]\n",[40,121,123],{"class":42,"line":122},14,[40,124,125],{},"        CTRL -->|map validated → DTO| DTO\n",[40,127,129],{"class":42,"line":128},15,[40,130,131],{},"        CTRL -->|invoke| UC\n",[40,133,135],{"class":42,"line":134},16,[40,136,137],{},"        DTO --> UC\n",[40,139,141],{"class":42,"line":140},17,[40,142,94],{},[40,144,146],{"class":42,"line":145},18,[40,147,101],{"emptyLinePlaceholder":100},[40,149,151],{"class":42,"line":150},19,[40,152,153],{},"    subgraph Step3[\"3 — Domain work\"]\n",[40,155,157],{"class":42,"line":156},20,[40,158,159],{},"        ENT[Domain Entities \u002F Services]\n",[40,161,163],{"class":42,"line":162},21,[40,164,165],{},"        PORT[Domain Port interface]\n",[40,167,169],{"class":42,"line":168},22,[40,170,171],{},"        UC --> ENT\n",[40,173,175],{"class":42,"line":174},23,[40,176,177],{},"        UC -->|depends on interface only| PORT\n",[40,179,181],{"class":42,"line":180},24,[40,182,94],{},[40,184,186],{"class":42,"line":185},25,[40,187,101],{"emptyLinePlaceholder":100},[40,189,191],{"class":42,"line":190},26,[40,192,193],{},"    subgraph Step4[\"4 — Infrastructure\"]\n",[40,195,197],{"class":42,"line":196},27,[40,198,199],{},"        ADAPTER[Adapter implementation]\n",[40,201,203],{"class":42,"line":202},28,[40,204,205],{},"        EXT[(Database \u002F peer \u002F external API)]\n",[40,207,209],{"class":42,"line":208},29,[40,210,211],{},"        PORT -.->|bound in composition root| ADAPTER\n",[40,213,215],{"class":42,"line":214},30,[40,216,217],{},"        ADAPTER --> EXT\n",[40,219,221],{"class":42,"line":220},31,[40,222,94],{},[224,225,226,245],"table",{},[227,228,229],"thead",{},[230,231,232,236,239,242],"tr",{},[233,234,235],"th",{},"Step",[233,237,238],{},"Component",[233,240,241],{},"Responsibility",[233,243,244],{},"Must not",[246,247,248,263,280,294,314,328,341],"tbody",{},[230,249,250,254,257,260],{},[251,252,253],"td",{},"1",[251,255,256],{},"Controller",[251,258,259],{},"Pick Use Case, map input → DTO, map result → response",[251,261,262],{},"Contain eligibility \u002F reservation \u002F peer rules",[230,264,265,267,270,277],{},[251,266,253],{},[251,268,269],{},"Input validation",[251,271,272,273,276],{},"Validate ",[17,274,275],{},"format"," (types, required, max length)",[251,278,279],{},"Encode business policy",[230,281,282,285,288,291],{},[251,283,284],{},"2",[251,286,287],{},"Application DTO",[251,289,290],{},"Typed carrier of UI input",[251,292,293],{},"Know ORM or HTTP transport details",[230,295,296,298,301,308],{},[251,297,284],{},[251,299,300],{},"Use Case",[251,302,303,304,307],{},"Orchestrate the feature (",[37,305,306],{},"__invoke",")",[251,309,310,311],{},"Call ORM directly, facades, or foreign ",[37,312,313],{},"*ModuleInterface",[230,315,316,319,322,325],{},[251,317,318],{},"3",[251,320,321],{},"Entity \u002F Domain service",[251,323,324],{},"Business meaning and invariants",[251,326,327],{},"Import host framework or other modules",[230,329,330,332,335,338],{},[251,331,318],{},[251,333,334],{},"Port interface",[251,336,337],{},"Declare I\u002FO in Domain language",[251,339,340],{},"Mention ORM class names",[230,342,343,346,349,352],{},[251,344,345],{},"4",[251,347,348],{},"Adapter",[251,350,351],{},"Talk to DB \u002F peer \u002F HTTP; map to Domain types",[251,353,354],{},"Leak ORM models back to the Use Case",[25,356,358],{"id":357},"_2-response-ascent-outward","2. Response ascent (outward)",[30,360,362],{"className":32,"code":361,"language":34,"meta":35,"style":35},"flowchart TD\n    EXT[(Database \u002F peer \u002F API)] --> ADAPTER[Infrastructure adapter]\n    ADAPTER -->|Entity \u002F Domain DTO| PORT[Port interface]\n    PORT --> UC[Use Case]\n    UC -->|Entity \u002F result| CTRL[UI Controller]\n    CTRL -->|map| RES[Response \u002F Resource]\n    RES --> HTTP[HTTP response]\n",[37,363,364,368,373,378,383,388,393],{"__ignoreMap":35},[40,365,366],{"class":42,"line":43},[40,367,46],{},[40,369,370],{"class":42,"line":49},[40,371,372],{},"    EXT[(Database \u002F peer \u002F API)] --> ADAPTER[Infrastructure adapter]\n",[40,374,375],{"class":42,"line":55},[40,376,377],{},"    ADAPTER -->|Entity \u002F Domain DTO| PORT[Port interface]\n",[40,379,380],{"class":42,"line":61},[40,381,382],{},"    PORT --> UC[Use Case]\n",[40,384,385],{"class":42,"line":67},[40,386,387],{},"    UC -->|Entity \u002F result| CTRL[UI Controller]\n",[40,389,390],{"class":42,"line":73},[40,391,392],{},"    CTRL -->|map| RES[Response \u002F Resource]\n",[40,394,395],{"class":42,"line":79},[40,396,397],{},"    RES --> HTTP[HTTP response]\n",[224,399,400,410],{},[227,401,402],{},[230,403,404,407],{},[233,405,406],{},"Direction",[233,408,409],{},"Allowed types",[246,411,412,424,432],{},[230,413,414,417],{},[251,415,416],{},"Infrastructure → Application",[251,418,419,420,423],{},"Domain Entity, Domain DTO, scalars — ",[17,421,422],{},"never"," ORM models",[230,425,426,429],{},[251,427,428],{},"Application → UI",[251,430,431],{},"Same Domain result (or a small Application result object)",[230,433,434,437],{},[251,435,436],{},"UI → Client",[251,438,439],{},"Resource \u002F array \u002F response envelope only",[25,441,443],{"id":442},"_3-full-lifecycle-sequence","3. Full lifecycle sequence",[30,445,447],{"className":32,"code":446,"language":34,"meta":35,"style":35},"sequenceDiagram\n    autonumber\n    actor Client\n    participant Ctrl as UI Controller\n    participant Val as Input validation\n    participant UC as Use Case\n    participant Dom as Domain Entity \u002F Service\n    participant Port as Domain Port\n    participant Infra as Infrastructure Adapter\n    participant DB as Database \u002F External\n\n    Client->>Ctrl: HTTP POST\n    Ctrl->>Val: validate\n    Val-->>Ctrl: validated data\n    Ctrl->>Ctrl: map → Application DTO\n    Ctrl->>UC: __invoke(dto)\n\n    UC->>Dom: create \u002F mutate\n    UC->>Port: save \u002F find \u002F quote…\n    Note over Port,Infra: Container resolves Port → Adapter\n    Port->>Infra: same method call\n    Infra->>Infra: map Entity ↔ persistence record\n    Infra->>DB: SQL \u002F HTTP \u002F in-process peer\n    DB-->>Infra: raw result\n    Infra-->>Port: Domain Entity \u002F DTO\n    Port-->>UC: Domain Entity \u002F DTO\n\n    UC-->>Ctrl: Domain result\n    Ctrl->>Ctrl: map to response\n    Ctrl-->>Client: 200\u002F201\n",[37,448,449,454,459,464,469,474,479,484,489,494,499,503,508,513,518,523,528,532,537,542,547,552,557,562,567,572,577,581,586,591],{"__ignoreMap":35},[40,450,451],{"class":42,"line":43},[40,452,453],{},"sequenceDiagram\n",[40,455,456],{"class":42,"line":49},[40,457,458],{},"    autonumber\n",[40,460,461],{"class":42,"line":55},[40,462,463],{},"    actor Client\n",[40,465,466],{"class":42,"line":61},[40,467,468],{},"    participant Ctrl as UI Controller\n",[40,470,471],{"class":42,"line":67},[40,472,473],{},"    participant Val as Input validation\n",[40,475,476],{"class":42,"line":73},[40,477,478],{},"    participant UC as Use Case\n",[40,480,481],{"class":42,"line":79},[40,482,483],{},"    participant Dom as Domain Entity \u002F Service\n",[40,485,486],{"class":42,"line":85},[40,487,488],{},"    participant Port as Domain Port\n",[40,490,491],{"class":42,"line":91},[40,492,493],{},"    participant Infra as Infrastructure Adapter\n",[40,495,496],{"class":42,"line":97},[40,497,498],{},"    participant DB as Database \u002F External\n",[40,500,501],{"class":42,"line":104},[40,502,101],{"emptyLinePlaceholder":100},[40,504,505],{"class":42,"line":110},[40,506,507],{},"    Client->>Ctrl: HTTP POST\n",[40,509,510],{"class":42,"line":116},[40,511,512],{},"    Ctrl->>Val: validate\n",[40,514,515],{"class":42,"line":122},[40,516,517],{},"    Val-->>Ctrl: validated data\n",[40,519,520],{"class":42,"line":128},[40,521,522],{},"    Ctrl->>Ctrl: map → Application DTO\n",[40,524,525],{"class":42,"line":134},[40,526,527],{},"    Ctrl->>UC: __invoke(dto)\n",[40,529,530],{"class":42,"line":140},[40,531,101],{"emptyLinePlaceholder":100},[40,533,534],{"class":42,"line":145},[40,535,536],{},"    UC->>Dom: create \u002F mutate\n",[40,538,539],{"class":42,"line":150},[40,540,541],{},"    UC->>Port: save \u002F find \u002F quote…\n",[40,543,544],{"class":42,"line":156},[40,545,546],{},"    Note over Port,Infra: Container resolves Port → Adapter\n",[40,548,549],{"class":42,"line":162},[40,550,551],{},"    Port->>Infra: same method call\n",[40,553,554],{"class":42,"line":168},[40,555,556],{},"    Infra->>Infra: map Entity ↔ persistence record\n",[40,558,559],{"class":42,"line":174},[40,560,561],{},"    Infra->>DB: SQL \u002F HTTP \u002F in-process peer\n",[40,563,564],{"class":42,"line":180},[40,565,566],{},"    DB-->>Infra: raw result\n",[40,568,569],{"class":42,"line":185},[40,570,571],{},"    Infra-->>Port: Domain Entity \u002F DTO\n",[40,573,574],{"class":42,"line":190},[40,575,576],{},"    Port-->>UC: Domain Entity \u002F DTO\n",[40,578,579],{"class":42,"line":196},[40,580,101],{"emptyLinePlaceholder":100},[40,582,583],{"class":42,"line":202},[40,584,585],{},"    UC-->>Ctrl: Domain result\n",[40,587,588],{"class":42,"line":208},[40,589,590],{},"    Ctrl->>Ctrl: map to response\n",[40,592,593],{"class":42,"line":214},[40,594,595],{},"    Ctrl-->>Client: 200\u002F201\n",[597,598,600],"h3",{"id":599},"ordering-place-order-mapping","Ordering “place order” mapping",[224,602,603,613],{},[227,604,605],{},[230,606,607,610],{},[233,608,609],{},"Sequence step",[233,611,612],{},"Concrete class (illustrative)",[246,614,615,626,636,645,656,670],{},[230,616,617,620],{},[251,618,619],{},"Validation",[251,621,622,625],{},[37,623,624],{},"PlaceOrderRequest"," (or equivalent)",[230,627,628,630],{},[251,629,287],{},[251,631,632,635],{},[37,633,634],{},"PlaceOrderDTO"," + line DTOs",[230,637,638,640],{},[251,639,300],{},[251,641,642],{},[37,643,644],{},"PlaceOrderUseCase",[230,646,647,650],{},[251,648,649],{},"Nested helper",[251,651,652,655],{},[37,653,654],{},"PrepareOrderLines"," (not called by UI)",[230,657,658,661],{},[251,659,660],{},"Ports",[251,662,663,666,667],{},[37,664,665],{},"OrderRepositoryInterface",", ",[37,668,669],{},"WarehouseAvailabilityPortInterface",[230,671,672,675],{},[251,673,674],{},"Adapters",[251,676,677,678],{},"Persistence repository, ",[37,679,680],{},"WarehouseAvailabilityAclAdapter",[25,682,684],{"id":683},"delivery-wording","Delivery wording",[14,686,687,690],{},[17,688,689],{},"UI adapter"," (controller, request handler, admin action, console command) validates input shape, builds an Application DTO, invokes the Use Case, then maps the Domain result to a response.",[692,693],"host-examples",{"topic":694},"ui",[25,696,698],{"id":697},"common-mistakes","Common mistakes",[224,700,701,711],{},[227,702,703],{},[230,704,705,708],{},[233,706,707],{},"Mistake",[233,709,710],{},"Fix",[246,712,713,721,731,739,747],{},[230,714,715,718],{},[251,716,717],{},"Controller calls repository \u002F ORM directly",[251,719,720],{},"Controller → Use Case only",[230,722,723,726],{},[251,724,725],{},"Use Case creates \u002F queries ORM records directly",[251,727,728,729],{},"Inject ",[37,730,665],{},[230,732,733,736],{},[251,734,735],{},"Validation layer invokes Use Case",[251,737,738],{},"Controller invokes Use Case",[230,740,741,744],{},[251,742,743],{},"Repository returns ORM models to Use Case",[251,745,746],{},"Map to Entity in Infrastructure",[230,748,749,752],{},[251,750,751],{},"Peer module’s controller calls this Use Case",[251,753,754],{},"Peer uses ACL or Events only",[25,756,758],{"id":757},"checklist-before-merge","Checklist before merge",[760,761,764,774,782,788,794],"ul",{"className":762},[763],"contains-task-list",[765,766,769,773],"li",{"className":767},[768],"task-list-item",[770,771],"input",{"disabled":100,"type":772},"checkbox"," One first-level Use Case is the only entry from UI for this action",[765,775,777,779,780],{"className":776},[768],[770,778],{"disabled":100,"type":772}," Application DTO is the only input type into ",[37,781,306],{},[765,783,785,787],{"className":784},[768],[770,786],{"disabled":100,"type":772}," All I\u002FO goes through Domain ports",[765,789,791,793],{"className":790},[768],[770,792],{"disabled":100,"type":772}," No ORM types in Application \u002F Domain",[765,795,797,799],{"className":796},[768],[770,798],{"disabled":100,"type":772}," Response mapping stays in UI",[14,801,802,803,808,809,813],{},"Next: ",[804,805,807],"a",{"href":806},"\u002Fv1\u002Fcore\u002Fuse-cases-and-dtos","use cases & DTOs"," · ",[804,810,812],{"href":811},"\u002Fv1\u002Fcore\u002Fports-and-persistence","ports & persistence",".",[815,816,817],"style",{},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":35,"searchDepth":49,"depth":49,"links":819},[820,821,822,825,826,827],{"id":27,"depth":49,"text":28},{"id":357,"depth":49,"text":358},{"id":442,"depth":49,"text":443,"children":823},[824],{"id":599,"depth":55,"text":600},{"id":683,"depth":49,"text":684},{"id":697,"depth":49,"text":698},{"id":757,"depth":49,"text":758},"Ordered path of one request — UI to Use Case to Domain port to adapter and back.","md",{},"\u002Fv1\u002Fcore\u002Fgolden-flow",{"title":5,"description":828},"v1\u002Fcore\u002Fgolden-flow","DKSDbdNSnROWSn8kbyi7h0dSbF09VUaYDiy1M7LjwzY",1786241411630]