Developer Documentation

Welcome to the Hello World Co-Op DAO developer documentation. This guide covers everything you need to contribute to our platform built on the Internet Computer Protocol (ICP).

Quick Links

Section	Description
Workspace Setup	Clone repos, install tools, verify your environment
API Reference	Candid interface documentation for all canisters
Components	React component documentation (FolderTree, etc.)
Testing	Testing strategies for visualization, E2E, unit tests
Contributing	Code style, PR process, commit conventions
Architecture	System design, canister responsibilities, data flows
Game Systems	Otter Camp Phaser.js game systems (Combat, Quests)
Canister Monitoring	Cycle balance monitoring, health checks, top-up procedures

Platform Overview

The Hello World Co-Op DAO platform spans multiple repositories:

11 Rust canisters running on the Internet Computer
6 React suite frontends deployed to IC asset canisters -- see FAS Architecture
3 shared npm packages (@hello-world-co-op/api, auth, ui) on GitHub Packages
1 Oracle bridge (Node.js off-chain service)
2 Infrastructure repos (ops-infra, docs)

Technology Stack

Layer	Technology
Backend	Rust, ic-cdk 0.13, Candid 0.10
Frontend	React 18/19, Vite 5, TypeScript 5.6, Tailwind 3
Testing	PocketIC 6, Vitest 1.6, React Testing Library, Playwright
Auth	Internet Identity, Email/Password, OAuth providers
Standards	ICRC-1/2 (tokens), ICRC-7/37 (NFTs)

Getting Started

1. Prerequisites

Before you begin, ensure you have:

Rust 1.70+ with wasm32-unknown-unknown target
Node.js 20.x LTS
dfx (IC SDK) - latest stable version
PocketIC binary for integration testing
Git for version control

See Workspace Setup for installation instructions.

2. Clone the Workspace

bash

# Clone the workspace repository
git clone https://github.com/Hello-World-Co-Op/hello-world-workspace.git
cd hello-world-workspace

# Clone all component repositories
# See the full clone script in Workspace Setup

3. Build and Test

bash

# Build all Rust canisters
./ops-infra/scripts/build-wasm.sh

# Run backend tests
cd <canister-repo>
cargo test

# Run frontend suite tests
cd <suite-name>
npm test

Repository Structure

hello-world-workspace/
├── hello-world-workspace/  # VS Code workspace config
├── docs/                   # Documentation (you are here)
├── oracle-bridge/          # Off-chain Node.js service
├── ops-infra/              # DevOps, CI/CD, scripts
├── Suite Frontends:
│   ├── foundery-os-suite/  # FounderyOS productivity app (4,642 tests)
│   ├── governance-suite/   # DAO governance & voting (867 + 69 E2E tests)
│   ├── marketing-suite/    # Public marketing site with SEO (83 tests)
│   ├── otter-camp-suite/   # Otter Camp game UI (2,115 + 7 E2E tests)
│   ├── dao-suite/          # Member dashboard (806 tests)
│   └── dao-admin-suite/    # Admin dashboard with RBAC (115 tests)
├── Shared Packages:
│   ├── api/                # @hello-world-co-op/api
│   ├── auth/               # @hello-world-co-op/auth
│   └── ui/                 # @hello-world-co-op/ui
└── Canisters:
    ├── auth-service/       # Session management
    ├── user-service/       # User registration
    ├── membership/         # ICRC-7 SBT credentials
    ├── dom-token/          # ICRC-1/2 token ledger
    ├── governance/         # Proposal system
    ├── treasury/           # Role-gated payouts
    ├── identity-gateway/   # Internet Identity
    ├── otter-camp/         # Crowdfunding
    ├── marketplace/        # Vendor registry
    ├── proof-nfts/         # Deployment rewards
    └── education/          # Educator registry

Key Concepts

Canisters

Canisters are smart contracts on the Internet Computer. Each canister:

Has a unique principal ID
Runs WebAssembly (compiled from Rust)
Exposes a Candid interface (.did file)
Can make inter-canister calls

ICRC Standards

We implement several ICRC standards:

Standard	Purpose	Used By
ICRC-1	Fungible tokens	dom-token
ICRC-2	Token approvals	dom-token
ICRC-7	NFTs	membership, governance, proof-nfts, education
ICRC-37	NFT metadata	membership, governance, proof-nfts, education

Authentication

The platform supports multiple authentication methods:

Internet Identity - Passwordless, device-based
Email/Password - Traditional auth with Argon2id hashing
OAuth Providers - Google, Apple, Microsoft, GitHub, Discord

Development Workflow

Pick a story from the sprint backlog
Read the story context for technical details
Implement following our coding patterns
Write tests (PocketIC for backend, Vitest for frontend)
Run validations to ensure no regressions
Submit PR following our contributing guidelines

Frontend Application Split (FAS)

The FAS project decomposes the monolithic frontend into 6 independently deployable suites consuming 3 shared packages published to GitHub Packages.

Total: 8,628 tests across 6 suites (0 failures, 0 skipped).

Document	Description
FAS Architecture Overview	Package/suite architecture, 3 auth patterns, dependency diagrams, CI/CD pipeline, cross-suite auth
FAS Repository Map	All 6 suites + 3 packages + template, "where do I make changes?" reference, package dependency tooling
FAS Local Setup Guide	GitHub Packages auth, suite-specific setup (all 6 suites), oracle-bridge, npm link workflow
FAS Suite Creation Guide	Creating new suites, real-world examples, suite patterns, production deployment checklist
FAS Troubleshooting	Issues from FAS-1 through FAS-8.1: GitHub Packages, CI/CD, builds, SEO, Phaser.js, SSO, CSP, deployment
FAS Cross-Suite Auth Debugging	Cookie domain verification, session validation, redirect loop diagnosis, logout testing, DevTools inspection
FAS Rollback Procedures	Suite-specific rollback, package rollback, DNS rollback, verification checklists

New Developer Onboarding Path

Follow this path to make your first PR within 1 week (NFR16):

Day 1: Understand the architecture
- Read FAS Architecture Overview -- understand the suite/package model and 3 auth patterns
- Read FAS Repository Map -- find the right repo for your task
Day 2: Set up your local environment
- Follow FAS Local Setup Guide -- get one suite running locally
- Run tests: npm test -- verify everything passes
Day 3-4: Make your first change
- Pick a small task (component fix, test addition, documentation update)
- Edit code, write or update tests, run npm test
- Use the Troubleshooting Guide if you get stuck
Day 5: Create your PR
- Commit your changes with a conventional commit message
- Push to a feature branch and create a pull request
- Address code review feedback
Day 6-7: Iterate and land
- Respond to reviewer comments
- Ensure CI passes (lint, typecheck, test, build)
- Merge when approved

Goal: First PR merged within 1 week of onboarding.

FAS Quick Start

bash

# 1. Configure GitHub Packages auth
echo "@hello-world-co-op:registry=https://npm.pkg.github.com" >> ~/.npmrc
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT" >> ~/.npmrc

# 2. Clone and run a suite
git clone https://github.com/Hello-World-Co-Op/foundery-os-suite.git
cd foundery-os-suite
cp .env.example .env.local
npm install && npm run dev

See the FAS Local Setup Guide for detailed instructions including suite-specific requirements.

Need Help?

Check the FAQ for common questions
Review FAS Troubleshooting for frontend issues
Review FAS Auth Debugging for SSO issues
Consult Architecture for system context
See Environment Variables for configuration

Developer Documentation ​

Quick Links ​

Platform Overview ​

Technology Stack ​

Getting Started ​

1. Prerequisites ​

2. Clone the Workspace ​

3. Build and Test ​

Repository Structure ​

Key Concepts ​

Canisters ​

ICRC Standards ​

Authentication ​

Development Workflow ​

Frontend Application Split (FAS) ​

New Developer Onboarding Path ​

FAS Quick Start ​

Need Help? ​

Developer Documentation

Quick Links

Platform Overview

Technology Stack

Getting Started

1. Prerequisites

2. Clone the Workspace

3. Build and Test

Repository Structure

Key Concepts

Canisters

ICRC Standards

Authentication

Development Workflow

Frontend Application Split (FAS)

New Developer Onboarding Path

FAS Quick Start

Need Help?