[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M74G64H4BCMSB8VCKSA0SCZS":3,"skill-same:01M74G64H4BCMSB8VCKSA0SCZS":50},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M74G64H4BCMSB8VCKSA0SCZS","integration-design",null,"Design integration between two services — sync vs async, API gateway \u002F BFF placement, anti-corruption layer, contract + versioning, ports-and-adapters, and backpressure handling.","MohammadBafkar\u002Fpolymath","MohammadBafkar","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F34940462?v=4","01M74G540TQFZWK6KVAPKFVGNR","Mohammad Bafkar","01M74G541HG19QP9V5DQCJVKYE",0,"MIT","https:\u002F\u002Fgithub.com\u002FMohammadBafkar\u002Fpolymath\u002Fblob\u002Fmain\u002Fplugins\u002Fpolymath-architecture\u002Fskills\u002Fintegration-design\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: integration-design\ndescription: Design integration between two services — sync vs async, API gateway \u002F BFF placement, anti-corruption layer, contract + versioning, ports-and-adapters, and backpressure handling.\n---\n\n# integration-design\n\n> The contract between two services outlives both implementations. Design the seam — sync or async, who owns the schema, how it evolves — before the first call is wired.\n\n**Mode:** analytical — judgment inside a fixed frame. Keep the output shape; every verdict cites its evidence; unknowns are marked `[TBD]` or `[VERIFY]`, never filled in.\n\n## When to use\n\n- Two services (or a client tier and services) need to talk and you are choosing the integration style.\n- A client is making many chatty calls, or an upstream model is leaking into a downstream service.\n- A workflow invokes `polymath-architecture:integration-design`.\n\nNot this when: the flow is an asynchronous business process with compensation — that is `event-driven-design`. For the REST resource\u002Fverb\u002Fstatus-code details of one endpoint, that is `polymath-backend:api-design-rest`.\n\n## Inputs\n\n- The two parties, what data\u002Foperations cross the boundary, and the coupling\u002Flatency tolerance.\n- Whether either party is legacy or third-party (drives the anti-corruption layer).\n\n## Procedure\n\n1. **Sync vs async**: request\u002Fresponse (REST\u002FgRPC) when the caller needs an answer now and the callee is fast and available; messaging\u002Fevents when you want temporal decoupling, buffering, or fan-out. State the choice per interaction, not per system.\n2. **Place a gateway \u002F BFF** where it earns its keep: an API gateway for cross-cutting concerns (auth, rate-limit, routing) at the edge; a *Backend-for-Frontend* when distinct clients (web\u002Fmobile) need tailored aggregation — avoids chatty clients and leaking N services to the UI.\n3. **Add an anti-corruption layer** whenever you integrate with a legacy or third-party model: translate at the boundary so their model never becomes your model. This is the ports-and-adapters \u002F hexagonal seam — the domain talks to a port, the adapter speaks their dialect.\n4. **Define the contract explicitly**: schema (OpenAPI\u002Fprotobuf\u002Fevent schema), ownership (who can change it), and a compatibility rule (additive-only, consumer-driven contracts, or versioned). Breaking changes need a versioning + deprecation path.\n5. **Decide error & partial-failure semantics**: timeouts, retries, and what a caller does when the callee is degraded (hand off to `resilience-design` for the parameters).\n6. **Handle backpressure** for async edges: bounded queues, consumer lag monitoring, and what happens when the consumer can't keep up (drop, slow the producer, scale out) — never an unbounded buffer.\n7. **Minimize coupling**: prefer a narrow, stable contract over a wide one; flag any integration that requires sharing a database.\n\n## Output\n\n```text\nIntegration spec: mobile app ↔ order platform ↔ legacy ERP\n\nInteraction             Sync\u002Fasync  Why\napp → order status      sync REST   user waits for an answer; p99 120 ms\norder → ERP invoice     async       ERP is slow (p99 4 s) and down nightly; buffer it\n\nGateway\u002FBFF: mobile BFF aggregates order + shipment + payment (3 calls → 1); auth + rate-limit at the edge gateway\nACL: erp-adapter translates ERP \"DocType 14\" ↔ our Invoice; the domain only sees the InvoicePort\nContract: orders API OpenAPI v2 · owner: checkout team · additive-only, breaking → \u002Fv3 + 6-month deprecation\nErrors: BFF timeout 800 ms per downstream; partial response with `shipment: unavailable` (see resilience-design)\nBackpressure: invoice queue bounded at 50k; consumer-lag alert at 10 min; on full → producer gets 503, retries later\nCoupling flags: none — no shared database\n```\n\nInline by default; when a workflow step or the user wants it kept, write it to `docs\u002Farchitecture\u002F\u003Cslug>-integration.md` (slug from the system or context name, lowercased, non-`a-z0-9` runs → `-`).\n\n## Quality bar\n\n- Each interaction's sync\u002Fasync choice is justified by need, not habit.\n- Every cross-boundary contract names an owner and an evolution rule.\n- Integration with legacy\u002Fthird-party goes through an anti-corruption layer.\n- No async edge has an unbounded queue; backpressure behavior is defined.\n","# integration-design\n\n> The contract between two services outlives both implementations. Design the seam — sync or async, who owns the schema, how it evolves — before the first call is wired.\n\n**Mode:** analytical — judgment inside a fixed frame. Keep the output shape; every verdict cites its evidence; unknowns are marked `[TBD]` or `[VERIFY]`, never filled in.\n\n## When to use\n\n- Two services (or a client tier and services) need to talk and you are choosing the integration style.\n- A client is making many chatty calls, or an upstream model is leaking into a downstream service.\n- A workflow invokes `polymath-architecture:integration-design`.\n\nNot this when: the flow is an asynchronous business process with compensation — that is `event-driven-design`. For the REST resource\u002Fverb\u002Fstatus-code details of one endpoint, that is `polymath-backend:api-design-rest`.\n\n## Inputs\n\n- The two parties, what data\u002Foperations cross the boundary, and the coupling\u002Flatency tolerance.\n- Whether either party is legacy or third-party (drives the anti-corruption layer).\n\n## Procedure\n\n1. **Sync vs async**: request\u002Fresponse (REST\u002FgRPC) when the caller needs an answer now and the callee is fast and available; messaging\u002Fevents when you want temporal decoupling, buffering, or fan-out. State the choice per interaction, not per system.\n2. **Place a gateway \u002F BFF** where it earns its keep: an API gateway for cross-cutting concerns (auth, rate-limit, routing) at the edge; a *Backend-for-Frontend* when distinct clients (web\u002Fmobile) need tailored aggregation — avoids chatty clients and leaking N services to the UI.\n3. **Add an anti-corruption layer** whenever you integrate with a legacy or third-party model: translate at the boundary so their model never becomes your model. This is the ports-and-adapters \u002F hexagonal seam — the domain talks to a port, the adapter speaks their dialect.\n4. **Define the contract explicitly**: schema (OpenAPI\u002Fprotobuf\u002Fevent schema), ownership (who can change it), and a compatibility rule (additive-only, consumer-driven contracts, or versioned). Breaking changes need a versioning + deprecation path.\n5. **Decide error & partial-failure semantics**: timeouts, retries, and what a caller does when the callee is degraded (hand off to `resilience-design` for the parameters).\n6. **Handle backpressure** for async edges: bounded queues, consumer lag monitoring, and what happens when the consumer can't keep up (drop, slow the producer, scale out) — never an unbounded buffer.\n7. **Minimize coupling**: prefer a narrow, stable contract over a wide one; flag any integration that requires sharing a database.\n\n## Output\n\n```text\nIntegration spec: mobile app ↔ order platform ↔ legacy ERP\n\nInteraction             Sync\u002Fasync  Why\napp → order status      sync REST   user waits for an answer; p99 120 ms\norder → ERP invoice     async       ERP is slow (p99 4 s) and down nightly; buffer it\n\nGateway\u002FBFF: mobile BFF aggregates order + shipment + payment (3 calls → 1); auth + rate-limit at the edge gateway\nACL: erp-adapter translates ERP \"DocType 14\" ↔ our Invoice; the domain only sees the InvoicePort\nContract: orders API OpenAPI v2 · owner: checkout team · additive-only, breaking → \u002Fv3 + 6-month deprecation\nErrors: BFF timeout 800 ms per downstream; partial response with `shipment: unavailable` (see resilience-design)\nBackpressure: invoice queue bounded at 50k; consumer-lag alert at 10 min; on full → producer gets 503, retries later\nCoupling flags: none — no shared database\n```\n\nInline by default; when a workflow step or the user wants it kept, write it to `docs\u002Farchitecture\u002F\u003Cslug>-integration.md` (slug from the system or context name, lowercased, non-`a-z0-9` runs → `-`).\n\n## Quality bar\n\n- Each interaction's sync\u002Fasync choice is justified by need, not habit.\n- Every cross-boundary contract names an owner and an evolution rule.\n- Integration with legacy\u002Fthird-party goes through an anti-corruption layer.\n- No async edge has an unbounded queue; backpressure behavior is defined.\n",{"name":5,"description":7},"main","23f6e21841a39580c9da2b5ec941f39dda17cd86","plugins\u002Fpolymath-architecture\u002Fskills\u002Fintegration-design","https:\u002F\u002Fgithub.com\u002FMohammadBafkar\u002Fpolymath","https:\u002F\u002Fgithub.com\u002FMohammadBafkar","2026-10-29 18:34:59",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add MohammadBafkar\u002Fpolymath --skill integration-design",{"tool":36,"command":37},"bunx","bunx skills add MohammadBafkar\u002Fpolymath --skill integration-design",{"tool":39,"command":40},"pnpm","pnpm dlx skills add MohammadBafkar\u002Fpolymath --skill integration-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FMohammadBafkar\u002Fpolymath\u002Fblob\u002Fmain\u002Fplugins\u002Fpolymath-architecture\u002Fskills\u002Fintegration-design\u002FSKILL.md",true,[44],{"path":45,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":48,"sourceHtmlUrl":49},"routing.yaml","REFERENCE","参考文档",499,"https:\u002F\u002Fgithub.com\u002FMohammadBafkar\u002Fpolymath\u002Fblob\u002Fmain\u002Fplugins\u002Fpolymath-architecture\u002Fskills\u002Fintegration-design\u002Frouting.yaml",[51,58,65,72,79,86],{"skillNo":52,"name":53,"nameZh":6,"description":54,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":55,"categories":56,"keywords":57,"publishedAt":19},"01M74GN87EBRHM9N87M7AP1HDD","runbook","Write or refresh an operational runbook for an alert\u002Fsymptom; structured as TL;DR + Pre-checks + Steps + Verification + Rollback + Escalation.","https:\u002F\u002Fgithub.com\u002FMohammadBafkar\u002Fpolymath\u002Fblob\u002Fmain\u002Fplugins\u002Fpolymath-writing\u002Fskills\u002Frunbook\u002FSKILL.md",[],[],{"skillNo":59,"name":60,"nameZh":6,"description":61,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":19},"01M74GN5GPKEC1JEKP2DFQNEQJ","rfc","Draft a lightweight design RFC to docs\u002Frfcs\u002F\u003Cslug>.md; Summary, Motivation, Detailed design, Drawbacks, Alternatives, Unresolved questions. A proposal to debate, not a recorded decision (adr).","https:\u002F\u002Fgithub.com\u002FMohammadBafkar\u002Fpolymath\u002Fblob\u002Fmain\u002Fplugins\u002Fpolymath-writing\u002Fskills\u002Frfc\u002FSKILL.md",[],[],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":19},"01M74GN2F4CWPMV4X09TG4E304","editorial-pass","Review and tighten prose in a Markdown artifact for a target tone (terse, formal, friendly) without dropping information; preserve quotations and load-bearing constraints.","https:\u002F\u002Fgithub.com\u002FMohammadBafkar\u002Fpolymath\u002Fblob\u002Fmain\u002Fplugins\u002Fpolymath-writing\u002Fskills\u002Feditorial-pass\u002FSKILL.md",[],[],{"skillNo":73,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":19},"01M74GMZWGYMZ37C4DYGT6P23G","architecture-review-facilitation","Run an architecture review as a process — entry criteria, reviewer checklist, decision log, and follow-up actions — pairing the design artifact with a red-team pass.","https:\u002F\u002Fgithub.com\u002FMohammadBafkar\u002Fpolymath\u002Fblob\u002Fmain\u002Fplugins\u002Fpolymath-writing\u002Fskills\u002Farchitecture-review-facilitation\u002FSKILL.md",[],[],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":19},"01M74GMXVX0YX3ETDXS527XDGM","architecture-doc","Write a C4-style architecture document; System Context + Containers (+ Components when interesting) with mermaid diagrams. Describes structure, not a decision (adr) or proposal (rfc).","https:\u002F\u002Fgithub.com\u002FMohammadBafkar\u002Fpolymath\u002Fblob\u002Fmain\u002Fplugins\u002Fpolymath-writing\u002Fskills\u002Farchitecture-doc\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":19},"01M74GMVG1WSMCK066S3KE6V5K","adr","Write an Architecture Decision Record (Michael Nygard format) to docs\u002Fadrs\u002FNNNN-\u003Cslug>.md; frontmatter validated by the ADR artifact schema. Records a made decision, not a proposal to debate (rfc).","https:\u002F\u002Fgithub.com\u002FMohammadBafkar\u002Fpolymath\u002Fblob\u002Fmain\u002Fplugins\u002Fpolymath-writing\u002Fskills\u002Fadr\u002FSKILL.md",[],[]]