Skip to content

Commit 5d2ef2a

Browse files
Web3NLclaude
Web3NL
and
claude
committed
docs: add CLAUDE.md project guide for AI agents
Structured project map, commands reference, component relationships, testing architecture, and conventions — optimized for AI agent consumption. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 3d84d7f commit 5d2ef2a

2 files changed

Lines changed: 172 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# Project Guide
2+
3+
Monorepo for building user-owned canister dapps on the Internet Computer. Users create and own canisters from a browser using ICP + Internet Identity — no CLI needed.
4+
5+
## Project Map
6+
7+
```
8+
packages-rs/ Publishable Rust crates (crates.io)
9+
my-canister-dashboard/ Dashboard UI + management endpoints (embedded in user canisters)
10+
frontend/ Svelte dashboard app (compiled into the Rust crate)
11+
my-canister-frontend/ Certified HTTP asset serving with security headers + gzip
12+
canister-dapp-test/ Acceptance test harness — validates any dapp wasm via PocketIC
13+
14+
packages-js/ Publishable npm packages
15+
my-canister-dashboard-js/ JS utilities for interacting with dashboard endpoints
16+
vite-plugin-canister-dapp/ Vite plugin for dev/prod environment detection
17+
18+
canisters/ Deployable canisters
19+
my-canister-app/ Installer app — SvelteKit frontend hosted as asset canister
20+
wasm-registry/ On-chain registry storing dapp wasms for installation
21+
22+
examples/ Example dapps (used for testing and as developer templates)
23+
my-hello-world/ Minimal example — Rust backend + Svelte frontend
24+
my-notepad/ Notepad example — persistent storage
25+
26+
scripts/ Shell scripts for build, test, deploy, publish
27+
tests/ E2E tests (Playwright) + shared helpers
28+
declarations/ Generated Candid interface bindings (icp-index)
29+
test-fixtures/ Test setup (II configuration)
30+
test-output/ Runtime test artifacts (derived principals, etc.)
31+
wasm/ Built wasm files for deployment/testing
32+
bin/ Binary tools (didc)
33+
.github/workflows/ CI/CD pipelines
34+
```
35+
36+
## Component Relationships
37+
38+
```
39+
Developer builds a dapp using:
40+
my-canister-frontend (Rust) ── certified asset serving
41+
my-canister-dashboard (Rust) ── embeds dashboard UI + management API
42+
43+
User installs dapp via:
44+
my-canister-app (installer) ── browses wasm-registry, creates canister, installs wasm
45+
46+
Testing validates via:
47+
canister-dapp-test ── loads any wasm into PocketIC, runs acceptance checks
48+
Playwright E2E ── tests full flows against local ICP network
49+
```
50+
51+
## Tech Stack
52+
53+
- **Backend**: Rust, ic-cdk, ic-http-certification, ic-asset-certification
54+
- **Frontend**: Svelte 5, SvelteKit, Vite 7, TypeScript
55+
- **Canister tooling**: icp-cli (`icp` command), PocketIC, ic-wasm
56+
- **Testing**: Vitest (unit), cargo test (Rust unit), canister-dapp-test (acceptance), Playwright (E2E)
57+
- **CI**: GitHub Actions on ubuntu-latest with local ICP network
58+
- **Package management**: npm workspaces + Cargo workspace
59+
60+
## Commands
61+
62+
### Development
63+
64+
```sh
65+
npm run dev:app # Run installer app (my-canister-app) dev server
66+
npm run dev:dashboard # Run dashboard frontend dev server
67+
```
68+
69+
### Building
70+
71+
```sh
72+
npm run build # Build all JS workspace packages
73+
cargo build # Build all Rust workspace crates
74+
npm run build:app # Build just my-canister-app
75+
npm run build:docs # Build TypeDoc API docs for JS packages
76+
```
77+
78+
### Quality Checks
79+
80+
```sh
81+
npm run check # Lint + format + typecheck all JS workspaces
82+
npm run deps:check # syncpack lint + knip dead code detection
83+
npm run fix # Auto-fix lint + format issues
84+
npm run deps:fix # Auto-fix dependency consistency
85+
./scripts/rust-lint-format.sh # cargo fmt + cargo clippy for Rust
86+
./scripts/check.sh # Full prerelease validation (npm ci, build, check, deps:check, rust lint)
87+
```
88+
89+
### Testing
90+
91+
```sh
92+
./scripts/run-test.sh # All unit tests (JS vitest + Rust cargo test + acceptance)
93+
./scripts/run-test-e2e.sh # E2E tests only (Playwright, requires running local network)
94+
./validate-and-test-all.sh # Full pipeline: checks + local network + deploy + all tests
95+
```
96+
97+
**validate-and-test-all.sh flags:**
98+
- `--clean` — clean build artifacts first
99+
- `--skip-checks` — skip lint/format/typecheck
100+
- `--skip-bootstrap` — skip local network setup (reuse existing)
101+
- `--skip-e2e` — skip E2E tests
102+
103+
### Publishing
104+
105+
```sh
106+
npm run changeset # Create a changeset for version bumping
107+
npm run release:version # Apply changesets → bump versions
108+
npm run release:publish # Publish npm packages + push git tags
109+
./scripts/deploy-app.sh <patch|minor|major> # Deploy my-canister-app to IC mainnet + tag
110+
```
111+
112+
### Utility Scripts
113+
114+
```sh
115+
./scripts/setup-identity.sh # Create test identities
116+
./scripts/write-test-env.sh # Write tests/test.env with canister IDs
117+
./scripts/setup-dashboard-dev-env.sh # Configure dashboard for local dev
118+
./scripts/upload-wasm-to-registry.sh # Upload a wasm to the registry canister
119+
./scripts/copy-example-wasm.sh # Copy example wasm to wasm/ directory
120+
./scripts/generate-declarations.sh # Regenerate Candid declarations
121+
./scripts/clean.sh # Remove build artifacts
122+
```
123+
124+
## CI/CD
125+
126+
| Workflow | Trigger | Purpose |
127+
|----------|---------|---------|
128+
| `pr.yml` | Pull requests to main | Full validation (build + test + E2E) |
129+
| `ci.yml` | Git tags / manual | Release build (same validation) |
130+
| `publish-docs.yml` | npm package tags | Build TypeDoc + deploy to GitHub Pages |
131+
132+
All use `shared-build.yml` which runs `./validate-and-test-all.sh` on ubuntu-latest with icp-cli and a local ICP network (PocketIC with NNS + II).
133+
134+
## Testing Architecture
135+
136+
**Unit tests** — run in isolation, no network needed:
137+
- JS: `vitest` per workspace (dashboard-js, vite-plugin, dashboard-frontend, my-canister-app)
138+
- Rust: `cargo test` per crate (my-canister-dashboard, my-canister-frontend)
139+
140+
**Acceptance tests** — validate wasm behavior via PocketIC:
141+
- `cargo run -p canister-dapp-test -- wasm/<name>.wasm.gz`
142+
- Tests HTTP responses, security headers, dashboard endpoints
143+
144+
**E2E tests** — full browser flows against local ICP network:
145+
- Batch 1: Vite dev server (dashboard + installer app)
146+
- Batch 2: Canister-served (dashboard + hello-world frontend)
147+
- Requires: local network running, canisters deployed, II configured
148+
- Test env vars in `tests/test.env` (auto-generated by setup scripts)
149+
150+
## Conventions
151+
152+
- **Changesets** for versioning — `npm run changeset` before PRs with publishable changes
153+
- **syncpack** enforces consistent dependency versions across workspaces
154+
- **knip** detects unused exports and dependencies
155+
- **icp-cli** (`icp` command) replaces dfx for all canister operations
156+
- Config: `icp.yaml` (canister definitions), `Cargo.toml` (Rust workspace), `package.json` (npm workspaces)
157+
- Local network: PocketIC on port 8080 with NNS + II enabled
158+
- Canister URLs: `http://<canister-id>.localhost:8080`
159+
160+
## Key Files
161+
162+
- `icp.yaml` — canister definitions and network config
163+
- `Cargo.toml` — Rust workspace members and shared dependencies
164+
- `package.json` — npm workspace definitions and root scripts
165+
- `playwright.config.ts` — E2E test project configuration
166+
- `validate-and-test-all.sh` — orchestrates the full build/test pipeline
167+
- `scripts/constants.sh` — shared variables (cycle amounts, canister names, origins)
168+
- `tests/test.env` — auto-generated env vars for test runs (canister IDs, II URL)

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,10 @@ Developers can submit their dapps to the registry, or users can install custom w
9595
| [@web3nl/my-canister-dashboard](https://www.npmjs.com/package/@web3nl/my-canister-dashboard) | npm | Dashboard interaction utilities |
9696
| [@web3nl/vite-plugin-canister-dapp](https://www.npmjs.com/package/@web3nl/vite-plugin-canister-dapp) | npm | Vite plugin for environment config |
9797

98+
## Development
99+
100+
See [CLAUDE.md](CLAUDE.md) for the full project map, commands, and architecture details.
101+
98102
## License
99103

100104
MIT

0 commit comments

Comments
 (0)