docs: application architecture concept page

[marc0olo]

Summary

• concepts/app-architecture.md page covering how ICP applications are structured
• Covers the two-canister model, comparison tables (traditional web + Ethereum), architectural patterns, data storage, and frontend options
• Recommends single-canister as the default starting point for most apps (atomic operations, minimal overhead)
• Multi-canister (canister-per-service) for when separation of concerns is needed or platform limits are hit
• Canister-per-subnet for extreme throughput scenarios
• Removed canister-per-user pattern (misleading about sovereignty without controller ownership)
• Uses @icp-sdk/core/agent, distinguishes official vs community CDKs
• Correct terminology: "onchain"/"offchain" (no hyphens), asset canister is not system-provided, compilation happens locally

Sync recommendation

informed by dfinity/portal — application-architectures.mdx, app-architecture.mdx

[marc0olo]

Review: concepts/app-architecture.md — Changes Requested

Best page of the batch. Ethereum comparison table and architecture decision flowchart are excellent.

1. Wrong crate URL for ic-stable-structures

In the Data storage section:

Rust: ic-stable-structures provides StableBTreeMap

Links to docs.rs/ic-cdk — wrong crate. Should be https://docs.rs/ic-stable-structures/latest/ic_stable_structures/.

2. Broken link: stable-memory.md

Canisters store data in stable memory

docs/guides/backends/stable-memory.md does not exist — no stub was created. Check whether this should map to an existing page (e.g., ../guides/backends/persistence.md or similar), or file a page proposal issue.

✓ Verified

• All other internal links point to existing stubs
• multi-canister icskills tag is correct
• Architecture patterns are sound and well-explained

[marc0olo]

Review: concepts/app-architecture.md (round 2)

Must fix

• Wrong crate URL for ic-stable-structures — Links to https://docs.rs/ic-cdk/latest/ic_cdk/ (wrong crate). Should be https://docs.rs/ic-stable-structures/latest/ic_stable_structures/. (Flagged in round 1, still unfixed.)
• Broken link: ../guides/backends/stable-memory.md — This file does not exist. The closest match is ../guides/backends/data-persistence.md which covers stable structures and upgrade hooks. (Flagged in round 1, still unfixed.)

Suggestions

None beyond the two must-fix items.

Verified

• All other internal links resolve: canisters.md, network-overview.md, reverse-gas-model.md, chain-fusion.md, https-outcalls.md, ../guides/authentication/internet-identity.md, ../guides/canister-calls/onchain-calls.md, ../guides/frontends/asset-canister.md, ../getting-started/quickstart.md
• Motoko core library correctly links to https://mops.one/core/docs
• Factual accuracy confirmed: 500 GiB stable memory, ~1–2s finality, 2 MiB payload limit, Ethereum ~12s block time
• Architecture patterns and Ethereum comparison table are excellent
• No dfx references, no .mdx/JSX
• Frontmatter complete, multi-canister icskill tag correct

[marc0olo]

Feedback addressed:

• Fixed wrong crate URL: ic-stable-structures now links to docs.rs/ic-stable-structures (was docs.rs/ic-cdk)
• Fixed broken link ../guides/backends/stable-memory.md → ../guides/backends/data-persistence.md

[Copilot]

Pull request overview

Adds the missing “Application Architecture” concept page describing how ICP apps are structured (canisters + frontend), how requests flow through boundary nodes, and how to choose an architecture as an app scales.

Changes:

• Replaces the stub concepts/app-architecture.md with an end-to-end architecture overview.
• Adds comparison tables (traditional web and Ethereum) and a decision guide for selecting multi-canister patterns.
• Introduces sections on scaling patterns, data storage, and frontend hosting options.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[marc0olo]

Feedback addressed:

• Distinguished official CDKs (Motoko, Rust) from community-supported languages
• Fixed: asset canister is not system-provided, it's a standard canister you deploy
• Replaced @dfinity/agent with @icp-sdk/core/agent (superseded)
• Fixed stable memory wording: acknowledged heap vs stable memory distinction
• Fixed Motoko persistence: removed misleading "automatically" claim
• Fixed onchain/offchain spelling to no-hyphen convention
• Removed canister-per-user pattern entirely
• Removed "default" label from canister-per-service heading
• Reframed single canister as production-viable (atomic ops, less overhead)
• Fixed "network compiles" → compiled locally, executed by the network
• Softened finality claim with "typically"
• Updated architecture decision table to reflect new framing