Skip to content

Commit f9ba7b0

Browse files
tarrencevtarrencev
authored
Add CLAUDE.md (#1766)
1 parent afab7d9 commit f9ba7b0

File tree

3 files changed

+152
-64
lines changed

3 files changed

+152
-64
lines changed

‎.github/workflows/claude.yml‎

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -34,26 +34,25 @@ jobs:
3434
uses: anthropics/claude-code-action@beta
3535
with:
3636
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
37-
37+
3838
# Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4)
3939
# model: "claude-opus-4-20250514"
40-
40+
4141
# Optional: Customize the trigger phrase (default: @claude)
4242
# trigger_phrase: "/claude"
43-
43+
4444
# Optional: Trigger when specific user is assigned to an issue
45-
# assignee_trigger: "claude-bot"
46-
45+
assignee_trigger: "claude-bot"
46+
4747
# Optional: Allow Claude to run specific commands
48-
# allowed_tools: "Bash(npm install),Bash(npm run build),Bash(npm run test:*),Bash(npm run lint:*)"
49-
48+
allowed_tools: "Bash(pnpm install),Bash(pnpm run build),Bash(pnpm run test:*),Bash(pnpm run lint:*),Bash(pnpm run format),Bash(pnpm run dev),Bash(pnpm run storybook),Bash(pnpm run e2e:*),Bash(pnpm --filter *),Bash(pnpm run clean),Bash(corepack enable pnpm)"
49+
5050
# Optional: Add custom instructions for Claude to customize its behavior for your project
5151
# custom_instructions: |
5252
# Follow our coding standards
5353
# Ensure all new code has tests
5454
# Use TypeScript for new files
55-
55+
5656
# Optional: Custom environment variables for Claude
5757
# claude_env: |
5858
# NODE_ENV: test
59-

‎CLAUDE.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Development Commands
6+
7+
### Core Development
8+
9+
- `pnpm dev` - Starts all development servers in parallel:
10+
- localhost:3002 (Next.js example)
11+
- localhost:5174 (Svelte example)
12+
- localhost:3001 (Keychain)
13+
- localhost:3003 (Profile)
14+
- `pnpm build` - Builds all packages and dependencies
15+
- `pnpm storybook` - Launches Storybook for component development
16+
17+
### Testing
18+
19+
- `pnpm test` - Runs keychain test suite
20+
- `pnpm test:ci` - Runs tests in CI mode
21+
- `pnpm test:storybook` - Runs Storybook visual regression tests
22+
- `pnpm e2e` - Runs end-to-end tests with Playwright
23+
- `pnpm e2e:ui` - Runs E2E tests with UI
24+
25+
### Code Quality
26+
27+
- `pnpm lint` - Runs linting and format checking
28+
- `pnpm format` - Runs formatting and lint fixes
29+
30+
### Package Management
31+
32+
- `pnpm i` - Install dependencies
33+
- `pnpm clean` - Clean all build artifacts and prune store
34+
- `corepack enable pnpm` - Enable pnpm via corepack
35+
36+
## Architecture Overview
37+
38+
### Project Structure
39+
40+
This is a **monorepo** using **pnpm workspaces** and **Turbo** for build orchestration. The project implements a gaming-specific smart contract wallet ecosystem for StarkNet.
41+
42+
### Core Packages (`/packages/`)
43+
44+
**Primary Applications:**
45+
46+
- **`controller/`** - Main SDK implementing StarkNet account interfaces. Implements account abstractions and communicates with embedded keychain iframe for secure operations.
47+
- **`keychain/`** - Sandboxed React app (<https://x.cartridge.gg/>) responsible for sensitive operations like transaction signing, user authentication, and key management.
48+
- **`profile/`** - React app (<https://profile.cartridge.gg/>) for displaying account state, balances, activities, and achievements.
49+
- **`connector/`** - Lightweight connector interface for easy integration with StarkNet React applications.
50+
51+
**Supporting Packages:**
52+
53+
- **`eslint/`** - Shared ESLint configuration
54+
- **`tsconfig/`** - Shared TypeScript configuration
55+
- **`torii-config/`** - Token metadata configuration
56+
57+
### Integration Examples (`/examples/`)
58+
59+
- **`next/`** - Next.js integration example with full transaction signing
60+
- **`svelte/`** - Svelte integration example
61+
- **`node/`** - Node.js server-side usage example
62+
63+
### Technology Stack
64+
65+
- **Frontend**: React, TypeScript, Next.js, Svelte, TailwindCSS, Vite
66+
- **Blockchain**: StarkNet, starknet.js
67+
- **Testing**: Jest, Playwright, Storybook
68+
- **Build**: Turbo, pnpm workspaces
69+
- **Authentication**: WebAuthn/Passkeys, Session Tokens
70+
71+
### Security Architecture
72+
73+
The project uses an **iframe-based security model** where:
74+
75+
- Sensitive operations (key management, signing) occur in the sandboxed keychain iframe
76+
- Controller SDK communicates with keychain via secure postMessage
77+
- Session tokens enable seamless gaming UX while maintaining security
78+
- WebAuthn/Passkeys provide passwordless authentication
79+
80+
### Development Workflow
81+
82+
1. **Monorepo Dependencies**: `pnpm dev` automatically handles workspace dependencies
83+
2. **Visual Testing**: Storybook provides component isolation and visual regression testing
84+
3. **Account Import**: For local development, export accounts from production keychain using `window.cartridge.exportAccount()` and import with `window.cartridge.importAccount()`
85+
86+
### Key Integration Points
87+
88+
- **Multi-wallet Support**: Integrates with MetaMask, Solana wallets, etc.
89+
- **Session Management**: Gaming-optimized session tokens for reduced signing friction
90+
- **GraphQL Data Layer**: Account information and state management
91+
- **Stripe Integration**: Fiat payment processing
92+
- **Cross-platform**: Web, mobile WebView support
93+
94+
### File Architecture Notes
95+
96+
- **Storybook snapshots** in `__image_snapshots__/` for visual regression testing
97+
- **Example apps** demonstrate various integration patterns
98+
99+
## Claude Code Workflow Guidelines
100+
101+
### Code Quality Requirements
102+
103+
- **Always run linting/formatting** before committing: `pnpm lint` and `pnpm format`
104+
- **TypeScript compliance** - All TypeScript errors must be resolved
105+
- **Test coverage** - Run relevant tests after making changes: `pnpm test` for unit tests, `pnpm test:storybook` for visual regression
106+
107+
### Common Development Tasks
108+
109+
**Working with Components:**
110+
111+
- After modifying components, run `pnpm storybook` to verify visually
112+
- Update Storybook snapshots with `pnpm test:storybook:update` if needed
113+
114+
**Adding New Features:**
115+
116+
- Check existing patterns in `packages/controller/src/` for SDK features
117+
- For UI changes, update both keychain (`packages/keychain/`) and profile (`packages/profile/`) as needed
118+
- Test integration with examples in `examples/next/` or `examples/svelte/`
119+
120+
**Debugging Integration Issues:**
121+
122+
- Use browser dev tools with local keychain at <http://localhost:3001>
123+
- Account import/export via `window.cartridge.exportAccount()` and `window.cartridge.importAccount()`
124+
- Check iframe communication between controller and keychain
125+
126+
**Monorepo Navigation:**
127+
128+
- Use `pnpm --filter <package-name>` to run commands in specific packages
129+
- Common filters: `@cartridge/controller`, `@cartridge/keychain`, `@cartridge/profile`, `@cartridge/connector`
130+
- Dependencies are automatically linked via workspace protocol
131+
132+
### Testing Strategy
133+
134+
- **Unit tests** in individual packages (Jest)
135+
- **Visual regression** via Storybook snapshots
136+
- **E2E testing** with Playwright for full user flows
137+
- **Integration testing** via example applications
138+
139+
### Key Files to Check When Making Changes
140+
141+
- `packages/controller/src/index.ts` - Main SDK exports
142+
- `packages/keychain/src/components/` - UI components for wallet operations
143+
- `turbo.json` - Build dependencies and caching
144+
- `pnpm-workspace.yaml` - Package workspace configuration

‎README.md‎

Lines changed: 0 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -65,58 +65,3 @@ from the production keychain:
6565
```js
6666
window.cartridge.importAccount("EXPORTED ACCOUNT");
6767
```
68-
69-
### Contracts
70-
71-
#### Install cainome
72-
73-
```bash
74-
cargo install --git https://github.com/cartridge-gg/cainome --features="build-binary"
75-
```
76-
77-
#### Compiling the cairo code
78-
79-
To build rust you first have to compile cairo. Run
80-
81-
```bash
82-
make
83-
```
84-
85-
in the root directory.
86-
87-
#### Commiting changes
88-
89-
The compiled account is stored in the git repository in the
90-
`crates/account_sdk/artifacts/` folder. To make sure that the tests are run
91-
against the most reacent version of the code run `make` in the root repository.
92-
The `make` command should also be run before commiting any changes to ensure a
93-
valid state of the compiled code.
94-
95-
#### Running the tests
96-
97-
Note, that to run the tests you first have to
98-
[compile](#compiling-the-cairo-code) (to sierra and casm) the contract in the
99-
`controller` folder.
100-
101-
Starknet Foundry tests:
102-
103-
```bash
104-
snforge test -p controller
105-
```
106-
107-
Scarb tests:
108-
109-
```bash
110-
scarb test -p webauthn_*
111-
```
112-
113-
After the contract is compiled run the tests using `cargo`:
114-
115-
```bash
116-
cargo test
117-
```
118-
119-
The scarb builds the contract and saves the compiled code in the
120-
`controller/target` folder. The tests then fetch (at compile time) the comipled
121-
code and deploy it to the local network. Note that obviously the contract needs
122-
to be recompiled for any changes to be applied in the compiled code.

0 commit comments

Comments
 (0)