infra: move app-architecture to getting-started + copy portal images

docs/concepts/canisters.md

@@ -121,6 +121,8 @@ If a canister has **no controllers**, it is immutable: no one can change its cod
 
 ## Canister internals
 
+![Canister components: input queue, Wasm module, heap and stable memory, output queue, cycles balance, controllers, and settings](/concepts/canisters/inside-canister.png)
+
 Under the hood, each canister maintains several components:
 
 - **Input queue**: holds incoming messages waiting to be processed. The canister processes one message at a time.
@@ -143,7 +145,7 @@ This has a practical implication: if a canister modifies state and then makes an
 
 - [Cycles](cycles.md): how canisters pay for computation
 - [Principals](principals.md): the identity model and caller authentication
-- [App architecture](app-architecture.md): how canisters fit into application design
+- [App architecture](../getting-started/app-architecture.md): how canisters fit into application design
 - [Canister lifecycle](../guides/canister-management/lifecycle.md): practical guide to managing canisters
 - [Network overview](network-overview.md): the infrastructure canisters run on
 

docs/concepts/chain-key-cryptography.md

@@ -71,6 +71,8 @@ For ECDSA and BIP340, key derivation uses a generalized form of [BIP-32](https:/
 
 Derivation is transparent: it happens inside the protocol as part of the signing and public-key-retrieval APIs. You provide a derivation path and the protocol handles the rest.
 
+![Key derivation hierarchy: subnet master key → canister root key → child keys via BIP-32-style derivation path](/concepts/chain-key-cryptography/key_derivation.png)
+
 Because the derivation algorithm is deterministic and uses only public parameters (the master public key, the canister principal, and the derivation path), public key derivation can also be performed **offline**: no management canister call or network connection required. This is useful for building explorers, dashboards, or address-derivation tools that need a canister's public key or network address without a live ICP connection. See the [offline key derivation guide](../guides/chain-fusion/offline-key-derivation.md) for TypeScript and Rust libraries.
 
 <!-- ic-pub-key: the missing .d.ts issue (dfinity/ic-pub-key#197) is closed and fixed. Package may still move to the @icp-sdk/ namespace in a future release; update all references when that happens. -->

docs/concepts/index.md

@@ -28,7 +28,7 @@ Understand the ideas behind the Internet Computer before you build on it. These
 
 - **[Canisters](canisters.md)**: Programs that run WebAssembly, hold state, serve HTTP, and pay for their own compute.
 - **[Principals](principals.md)**: The identity model: who can call a canister, and how caller identity works.
-- **[Application architecture](app-architecture.md)**: How ICP applications are structured: canisters, frontends, and inter-canister communication.
+- **[Application architecture](../getting-started/app-architecture.md)**: How ICP applications are structured: canisters, frontends, and inter-canister communication.
 - **[Cycles](cycles.md)**: How canisters pay for their own compute, storage, and bandwidth, and why users pay nothing.
 - **[Orthogonal persistence](orthogonal-persistence.md)**: How canister memory survives across executions and upgrades without databases.
 - **[Timers](timers.md)**: Periodic and one-shot scheduled tasks via the global timer mechanism.

docs/concepts/network-overview.md

@@ -77,7 +77,7 @@ Individual applications can also be governed by a **Service Nervous System (SNS)
 ## Next steps
 
 - [Canisters](canisters.md): what runs on the network
-- [App architecture](app-architecture.md): how applications use subnets and canisters
+- [App architecture](../getting-started/app-architecture.md): how applications use subnets and canisters
 - [Subnet types](../references/subnet-types.md): comparing subnet sizes and properties
 
 <!-- Upstream: informed by dfinity/portal docs/building-apps/essentials/network-overview.mdx -->

docs/concepts/vetkeys.md

@@ -32,13 +32,19 @@ The derivation is **deterministic**: the same (canister, context, input) triple
 
 When a canister calls `vetkd_derive_key`:
 
+![vetKD protocol flow: user generates transport key pair, canister authenticates and routes the request, subnet nodes threshold-derive and encrypt the key, client decrypts with transport secret key](/concepts/vetkeys/vetkd_diagram.png)
+
 1. The canister passes the `input`, `context`, `transport_public_key`, and `key_id` to the management canister.
 2. A threshold of subnet nodes cooperates to derive the key and encrypt it under the supplied transport public key.
 3. The encrypted key is returned to the canister, which forwards it to the client.
 4. The client decrypts the key using its transport secret key, obtaining the raw vetKey locally.
 
 The client's transport key pair is ephemeral: generated fresh for each session and discarded after use. No node, no subnet, and no canister ever holds the client's raw derived key.
 
+Keys are structured hierarchically. The subnet's vetKD master key is used to derive a unique canister-level key for each canister, which in turn derives per-context and per-input subkeys:
+
+![vetKD public key derivation hierarchy: subnet master key → canister master key (via canister ID) → subkeys (via context and input)](/concepts/vetkeys/vetkd_derivation.png)
+
 ## API overview
 
 The vetKD API is exposed through two management canister methods:

docs/concepts/app-architecture.md → docs/getting-started/app-architecture.md

@@ -5,18 +5,20 @@ sidebar:
   order: 3
 ---
 
-An application on the Internet Computer typically consists of one or more [canisters](canisters.md) that handle backend logic, store data, and optionally serve a web frontend: all without external servers, databases, or CDNs. This page explains how these pieces fit together and what architectural patterns are available as your application grows.
+An application on the Internet Computer typically consists of one or more [canisters](../concepts/canisters.md) that handle backend logic, store data, and optionally serve a web frontend: all without external servers, databases, or CDNs. This page explains how these pieces fit together and what architectural patterns are available as your application grows.
 
 ## The default two-canister model
 
+![Application architecture: browser talks to a frontend canister (HTML/JS/CSS) which calls a backend canister (logic + state) via an agent library](/getting-started/app-arch.png)
+
 Most ICP applications start with two canisters:
 
 - **Backend canister**: contains your application logic and data. You write it in Motoko or Rust (the official CDKs). Community-supported languages like TypeScript and Python are also available: see [Languages](../languages/index.md). Your code is compiled locally to WebAssembly and executed by the network.
 - **Frontend (asset) canister**: serves your web UI. It is a standard canister that hosts static files (HTML, CSS, JavaScript, images) and delivers them over HTTP.
 
 When a user opens your application in a browser:
 
-1. The browser sends an HTTPS request to a [boundary node](network-overview.md).
+1. The browser sends an HTTPS request to a [boundary node](../concepts/network-overview.md).
 2. The boundary node routes the request to the frontend canister, which returns the HTML and JavaScript.
 3. The JavaScript uses an [agent library](https://js.icp.build) (like `@icp-sdk/core/agent`) to send messages to the backend canister.
 4. The backend canister processes the message, updates its state if needed, and returns a response.
@@ -28,12 +30,12 @@ This flow replaces the traditional web stack. There is no separate web server, a
 
 | Concern | Traditional web app | ICP application |
 |---------|-------------------|-----------------|
-| **Compute** | Application server (Node, Django, etc.) | [Backend canister](canisters.md) (Wasm) |
-| **Storage** | Database (Postgres, MongoDB, etc.) | [Canister stable memory](orthogonal-persistence.md) (up to 500 GiB) |
+| **Compute** | Application server (Node, Django, etc.) | [Backend canister](../concepts/canisters.md) (Wasm) |
+| **Storage** | Database (Postgres, MongoDB, etc.) | [Canister stable memory](../concepts/orthogonal-persistence.md) (up to 500 GiB) |
 | **Frontend hosting** | CDN + static file server | [Asset canister](../guides/frontends/asset-canister.md) |
 | **Authentication** | OAuth provider or custom auth | [Internet Identity](../guides/authentication/internet-identity.md) (passkey or OAuth)\* |
-| **Scheduled tasks** | Cron jobs, worker queues | [Canister timers](timers.md) |
-| **External API calls** | Server-side HTTP requests | [HTTPS outcalls](https-outcalls.md) |
+| **Scheduled tasks** | Cron jobs, worker queues | [Canister timers](../concepts/timers.md) |
+| **External API calls** | Server-side HTTP requests | [HTTPS outcalls](../concepts/https-outcalls.md) |
 | **Infrastructure management** | You manage servers, scaling, uptime | The network handles replication and availability |
 
 \* With Internet Identity, users authenticate using a passkey or an OAuth provider (Google, Apple, etc.). Either way, each app receives a unique, app-specific principal: your canister never sees the OAuth credential or any cross-app identifier. This gives stronger privacy guarantees than traditional OAuth flows.
@@ -65,7 +67,7 @@ For implementation details and common pitfalls, see [Inter-canister calls](../gu
 
 ### Canister-per-subnet
 
-For maximum throughput, distribute canisters across multiple [subnets](network-overview.md). Each subnet processes messages independently, so spreading load across subnets lets your application scale horizontally.
+For maximum throughput, distribute canisters across multiple [subnets](../concepts/network-overview.md). Each subnet processes messages independently, so spreading load across subnets lets your application scale horizontally.
 
 **When to use:** high-throughput applications that exceed what a single subnet can handle (thousands of concurrent users, heavy computation).
 
@@ -86,7 +88,7 @@ Each user gets their own canister that they control. The main application canist
 
 ## Data storage
 
-Canisters store data in heap memory during execution and can persist data across upgrades using [stable memory](orthogonal-persistence.md#stable-memory): there is no external database. Libraries provide familiar data-structure abstractions on top of raw stable memory:
+Canisters store data in heap memory during execution and can persist data across upgrades using [stable memory](../concepts/orthogonal-persistence.md#stable-memory): there is no external database. Libraries provide familiar data-structure abstractions on top of raw stable memory:
 
 - **Motoko:** the [`core` standard library](https://mops.one/core/docs) includes persistent data structures designed for upgrade-safe storage.
 - **Rust:** [`ic-stable-structures`](https://docs.rs/ic-stable-structures/latest/ic_stable_structures/) provides `StableBTreeMap` and other structures for stable memory.
@@ -117,9 +119,9 @@ Start with the simplest architecture that meets your requirements. You can alway
 
 ## Next steps
 
-- [Quickstart](../getting-started/quickstart.md): deploy your first application
+- [Choose your path](choose-your-path.md): pick a development track based on what you want to build
 - [Inter-canister calls](../guides/canister-calls/inter-canister-calls.md): inter-canister communication patterns
 - [Asset canister](../guides/frontends/asset-canister.md): frontend deployment
-- [Canisters](canisters.md): canister internals
+- [Canisters](../concepts/canisters.md): canister internals
 
 <!-- Upstream: informed by dfinity/portal docs/building-apps/best-practices/application-architectures.mdx, docs/building-apps/getting-started/app-architecture.mdx; canister-per-user section ported from application-architectures.mdx -->

docs/getting-started/choose-your-path.md

@@ -2,7 +2,7 @@
 title: "Choose your path"
 description: "Choose your development path based on what you want to build"
 sidebar:
-  order: 3
+  order: 4
 ---
 
 Choose your next step based on what you want to build. Each path links to the first guide you should read, with a suggested progression from there.

docs/guides/backends/onchain-ai.mdx

@@ -293,6 +293,6 @@ Both examples include a browser UI and can be deployed to mainnet in a single co
 
 - [HTTPS outcalls](https-outcalls.md): call external AI APIs when you need more model options or larger context windows
 - [Data persistence](data-persistence.md): persist conversation history across canister upgrades using stable memory
-- [App architecture](../../concepts/app-architecture.md): understand where AI inference fits in a multi-canister application
+- [App architecture](../../getting-started/app-architecture.md): understand where AI inference fits in a multi-canister application
 
 {/* Upstream: informed by dfinity/examples: rust/llm_chatbot, motoko/llm_chatbot; limits verified against dfinity/llm */}

sidebar.mjs

@@ -109,7 +109,6 @@ export const sidebar = [
         items: [
           { slug: "concepts/canisters" },
           { slug: "concepts/principals" },
-          { slug: "concepts/app-architecture" },
           { slug: "concepts/cycles" },
           { slug: "concepts/orthogonal-persistence" },
           { slug: "concepts/timers" },