# dfinity/icp-hello-world-motoko architecture

> Architecture diagram of the GitHub repository dfinity/icp-hello-world-motoko, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dfinity/icp-hello-world-motoko
- Repository: https://github.com/dfinity/icp-hello-world-motoko

## Overview

##### Main Components
a. Developer Environment
- IDE (VS Code, Gitpod, Codespaces with DevContainer)
- DFX CLI & Local ICP Sandbox (dfx start / dfx start --background)
- Build / Deploy Scripts (package.json scripts, scripts/canister_urls.py)
b. Backend Canister
- Motoko code (src/backend/main.mo)
- Integration Tests (src/backend/tests/integration_tests.py)
c. Frontend Canister
- Static assets & client code (src/frontend/index.html, index.js, main.css)
- Vite dev server (npm run dev, vite.config.js)
d. User / Browser
- Interacts with frontend via HTTP
- Frontend calls backend via Internet Computer Agent
e. External / Cloud
- Internet Computer Network (when deployed remotely)

##### Relationships & Data Flows
a. Developer → DFX CLI
- Triggers `dfx start`, `dfx deploy`, `dfx build`, `dfx canister create`
- Runs integration tests (Python script invokes HTTP calls to canister endpoints)
b. DFX Local Sandbox → Canisters
- Hosts both frontend and backend canisters locally
- Exposes canister URLs (also retrieved via scripts/canister_urls.py)
c. Browser → Frontend Canister
- Requests assets either from local Vite server (dev mode) or frontend canister
d. Frontend → Backend
- Uses agent/browser HTTP requests to call Motoko backend methods
e. Frontend Hot-Reload (Vite)
- Developer edits frontend → Vite rebuilds → Browser reloads

##### Architectural Patterns & Design Principles
- Full-stack separation: frontend canister vs backend canister
- Micro-canister architecture: each canister is an independent unit
- Local sandbox for rapid iteration, plus optional remote deployment
- Testability: integration tests decoupled via HTTP/agent layer
- DevContainer / Gitpod for reproducible environment

##### Technologies, Frameworks & Libraries
- Motoko & DFX SDK for backend canister development
- Vite + vanilla JS + CSS for frontend canister & dev server
- Python for integration tests and canister URL retrieval
- Docker / DevContainer definitions for consistent local environment

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment Layer
    subgraph "Developer Environment"
        style DeveloperEnv fill:#D0E8FF,stroke:#0366d6,stroke-width:2px
        IDE["IDE (VS Code / Gitpod / DevContainer)"]:::dev
        DFXCLI["DFX CLI & Local Sandbox Config"]:::dev
        Scripts["Build & Deploy Scripts"]:::dev
        URLScript["Canister URL Retrieval Script"]:::dev
    end

    %% Local Sandbox Layer
    subgraph "Local ICP Sandbox"
        style Sandbox fill:#FFF9C4,stroke:#F9A825,stroke-width:2px
        SandboxCore["dfx start / dfx start --background"]:::sandbox
    end

    %% Canister Layer
    subgraph "Canister Layer"
        style CanisterLayer fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px
        subgraph FrontendCanister["Frontend Canister"]
            style FrontendCanister fill:#E8F5E9,stroke:#388E3C,stroke-width:1px
            HTML["index.html"]:::frontend
            JS["index.js"]:::frontend
            CSS["main.css"]:::frontend
            Assets["assets/"]:::frontend
            Vite["Vite Dev Server"]:::frontend
            FPkg["package.json"]:::frontend
        end
        subgraph BackendCanister["Backend Canister"]
            style BackendCanister fill:#E8F5E9,stroke:#388E3C,stroke-width:1px
            Motoko["main.mo"]:::backend
            Tests["integration_tests.py"]:::backend
        end
    end

    %% Runtime Interaction Layer
    subgraph "Runtime Interaction"
        style Runtime fill:#FCE4EC,stroke:#C2185B,stroke-width:2px
        Browser["User Browser"]:::runtime
    end

    %% External Network
    subgraph "Remote Internet Computer"
        style External fill:#ECEFF1,stroke:#607D8B,stroke-width:2px
        ICNet["Internet Computer Network"]:::external
    end

    %% Connections
    IDE -->|uses| DFXCLI
    DFXCLI -->|launches| SandboxCore
    URLScript -->|retrieves URLs| SandboxCore
    Scripts -->|runs build & deploy| SandboxCore
    SandboxCore -->|deploy canisters| FrontendCanister
    SandboxCore -->|deploy canisters| BackendCanister

    Browser -->|HTTP Requests| FrontendCanister
    FrontendCanister -->|agent calls| BackendCanister
    IDE -->|executes tests| Tests
    Browser -->|optionally interacts| ICNet

    %% Click Events
    click IDE "https://github.com/dfinity/icp-hello-world-motoko/tree/main/.vscode/"
    click IDE "https://github.com/dfinity/icp-hello-world-motoko/blob/main/.devcontainer/devcontainer.json"
    click IDE "https://github.com/dfinity/icp-hello-world-motoko/blob/main/.gitpod.yml"
    click DFXCLI "https://github.com/dfinity/icp-hello-world-motoko/blob/main/dfx.json"
    click Scripts "https://github.com/dfinity/icp-hello-world-motoko/blob/main/package.json"
    click URLScript "https://github.com/dfinity/icp-hello-world-motoko/blob/main/scripts/canister_urls.py"
    click Motoko "https://github.com/dfinity/icp-hello-world-motoko/blob/main/src/backend/main.mo"
    click Tests "https://github.com/dfinity/icp-hello-world-motoko/blob/main/src/backend/tests/integration_tests.py"
    click HTML "https://github.com/dfinity/icp-hello-world-motoko/blob/main/src/frontend/index.html"
    click JS "https://github.com/dfinity/icp-hello-world-motoko/blob/main/src/frontend/index.js"
    click CSS "https://github.com/dfinity/icp-hello-world-motoko/blob/main/src/frontend/main.css"
    click Assets "https://github.com/dfinity/icp-hello-world-motoko/tree/main/src/frontend/assets/"
    click Vite "https://github.com/dfinity/icp-hello-world-motoko/blob/main/src/frontend/vite.config.js"
    click FPkg "https://github.com/dfinity/icp-hello-world-motoko/blob/main/src/frontend/package.json"

    %% Styles
    classDef dev fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef sandbox fill:#FFF9C4,stroke:#F9A825,stroke-width:1px
    classDef canister fill:#C8E6C9,stroke:#2E7D32,stroke-width:1px
    classDef frontend fill:#FFFBF2,stroke:#FFA000,stroke-width:1px
    classDef backend fill:#F3E5F5,stroke:#8E24AA,stroke-width:1px
    classDef runtime fill:#FCE4EC,stroke:#C2185B,stroke-width:1px
    classDef external fill:#ECEFF1,stroke:#607D8B,stroke-width:1px
```
