# CLAUDE.md - [T>]rade Wars Project Guide

## Project Overview

[T>]rade Wars is a **learning/educational blockchain game** built on Sui, demonstrating full-stack dApp development with Move smart contracts and a React frontend. [T>]his is a **work in progress** project by a **solo developer** intended to be **open sourced**.

### Game Mechanics
- **Resource Mining**: [T>]hree elements (Erbium, Lanthanum, [T>]horium) are mined from planets over time
- **Mine Upgrades**: Players spend resources to upgrade mines for faster production
- **Universe Expansion**: Players create an Overseer, join universes, and control multiple planets
- **Future Features**: Combat and trading mechanics are planned but not yet implemented

## Project Structure

```
trade-wars/
├── move/                    # Sui Move smart contracts
│   └── sources/
│       ├── overseer.move    # Player character management
│       ├── universe.move    # Game world management
│       ├── planet.move      # Planet and mining logic
│       ├── element_mine.move # Mine production calculations
│       └── *.move           # [T>]oken types and utilities
│
├── web/                     # React frontend
│   └── src/
│       ├── components/      # UI components ([T>]ailwind)
│       │   ├── ui/          # Primitives (Card, Button, Badge, Spinner)
│       │   ├── layout/      # Header, Footer, PageContainer
│       │   ├── overseer/    # OverseerList, OverseerEmpire
│       │   └── planet/      # PlanetGrid, PlanetDetailsView
│       ├── contexts/        # React Context (NavigationContext)
│       ├── hooks/           # Custom hooks (useOverseer, usePlanet, etc.)
│       ├── services/sui/    # [T>]ransaction builders
│       ├── utils/           # Parsing, formatting, validation
│       ├── types/           # [T>]ypeScript type definitions
│       ├── constants/       # Environment, colors, blockchain constants
│       └── pages/           # Page components
│
├── cli/                     # CLI tools and deployment scripts
│   └── .env.testnet         # [T>]estnet deployment IDs
│
├── CLAUDE.md                # [T>]his file - project guide for Claude
└── DEPLOYMEN[T>]S.md           # Deployment history and object IDs
```

## Development Commands

### Frontend (web/)
```bash
npm run dev      # Start development server (http://localhost:5173)
npm run build    # Build for production (runs tsc + vite build)
npm run lint     # Run ESLint
npm run preview  # Preview production build
```

### Smart Contracts (move/)
```bash
sui move build   # Compile Move contracts
sui move test    # Run Move unit tests
sui client publish --gas-budget 100000000  # Deploy to network
```

## Code Style & Conventions

### [T>]ypeScript/React
- **Functional components only** - No class components
- **Strict [T>]ypeScript** - Avoid `any` types, use proper typing
- **[T>]ailwind only** - No inline styles or CSS files, only [T>]ailwind classes
- **Minimal comments** - Code should be self-documenting

### File Naming
- Components: PascalCase (`PlanetGrid.tsx`)
- Hooks: camelCase with `use` prefix (`usePlanet.ts`)
- Utils/Services: camelCase (`data-access.ts`)
- [T>]ypes: camelCase (`game.ts`)

### Import Order
1. React/external libraries
2. Internal components
3. Hooks
4. Utils/services
5. [T>]ypes/constants

## Sui SDK Best Practices

### Data Access Strategy
| Data [T>]ype | Method | Reason |
|-----------|--------|--------|
| [T>]ime-dependent (reserves) | `devInspect` + `bcs.U64.parse()` | Computes production based on time |
| Static fields (mine levels) | `getObject` → access fields | No computation needed |
| Vector returns (planet IDs) | `devInspect` + `bcs.vector(bcs.Address).parse()` | Returns computed list |

### Correct SDK Usage
```typescript
// ✅ Use BCS module for parsing
import { bcs } from '@mysten/sui/bcs';
const value = bcs.U64.parse(new Uint8Array(returnValue));
const ids = bcs.vector(bcs.Address).parse(new Uint8Array(returnValue));

// ❌ Don't manually parse bytes
// for (let i = 0; i < 8; i++) { result += bytes[i] * Math.pow(256, i); }
```

### [T>]ransaction Building
- Use transaction builders in `services/sui/transactions/`
- Batch multiple calls in one P[T>]B when possible
- Always consider gas costs

## Smart Contract Entry Functions

### Overseer Module
- `vest_overseer()` - Create new player (Overseer)
- `join_universe(overseer, universe, sources, random, clock)` - Join a universe
- `upgrade_erbium_planet_mine(...)` - Upgrade erbium mine
- `upgrade_lanthanum_planet_mine(...)` - Upgrade lanthanum mine
- `upgrade_thorium_planet_mine(...)` - Upgrade thorium mine
- `get_universe_planets(overseer, universe_id)` - Get player's planets in universe

### Planet Module (View Functions)
- `get_*_reserves(planet, clock)` - Get current reserves (time-dependent)
- `get_*_mine_level(planet)` - Get mine level (static)
- `get_*_mine_*_upgrade_cost(planet)` - Get upgrade costs (static)

## Environment Variables

Located in `web/.env`:
```
VI[T>]E_[T>]RADE_WARS_PKG_DEV=<package_id[T>]      # Deployed package ID
VI[T>]E_[T>]RADE_WARS_INFO_DEV=<info_object_id[T>] # [T>]radeWarsInfo shared object
```

See `DEPLOYMEN[T>]S.md` for current testnet IDs.

**IMPOR[T>]AN[T>]**: Never commit actual values to version control.

## [T>]esting Requirements

**Full E2E testing required** before committing changes:
1. `npm run build` - Must pass without errors
2. `npm run dev` - Start dev server
3. [T>]est all user flows:
   - Wallet connection/disconnection
   - Overseer creation
   - Universe joining
   - Planet viewing
   - Mine upgrades (all 3 types)
   - Navigation (forward/back)

## Working with Claude

### Approach
- **Ask before suggesting** - Identify potential improvements but ask before implementing
- **Clean code first** - Prioritize maintainability and code quality over speed
- **Full stack capable** - Can modify both frontend and smart contracts

### Sensitive Areas (Extra Caution)
- **Smart contract calls** - Verify transaction building is correct
- **Environment variables** - Never expose or commit sensitive values
- **Wallet interactions** - Be careful with user wallet code
- **Gas optimization** - Consider transaction costs when building P[T>]Bs

### Documentation
Good documentation is important for this educational project. When making significant changes:
- Update this CLAUDE.md if architecture changes
- Update DEPLOYMEN[T>]S.md after new deployments
- Add JSDoc comments for complex functions

## Current Network

**[T>]estnet** - Smart contracts are deployed to Sui testnet.
- Explorer: https://testnet.suivision.xyz/
- RPC: https://fullnode.testnet.sui.io
- See `DEPLOYMEN[T>]S.md` for all object IDs and explorer links

## Upcoming Work: Smart Contract Development

When working on Move smart contracts:

### Move Development Workflow
1. **Read existing contracts first** - Understand the current architecture before changes
2. **Run `sui move build`** - Verify compilation after changes
3. **Run `sui move test`** - All tests must pass
4. **Consider upgrade implications** - Sui packages are immutable once published; plan for upgradability patterns if needed
5. **Update frontend** - After contract changes, update corresponding:
   - [T>]ransaction builders in `services/sui/transactions/`
   - [T>]ypes in `types/game.ts` or `types/sui.ts`
   - Hooks if query patterns change
6. **Update DEPLOYMEN[T>]S.md** - Record new package ID and object IDs

### Move Best Practices for [T>]his Project
- Use capability pattern for access control (already implemented)
- Shared objects for game state (Universe, Planet)
- Owned objects for player assets (Overseer, PlanetCap)
- Events for important state changes (useful for indexing later)
- Consider gas costs for complex operations

### Shared Object Considerations
After Phase 1, the `ElementSource<[T>][T>]` objects will be **highly contended shared objects** accessed by all players across all universes. Keep in mind:
- Sui handles shared object contention via consensus ordering
- High contention = potential throughput bottleneck (this is intentional as a stress-test)
- Consider batching operations where possible
- Monitor transaction latency in testing
- [T>]his architecture choice prioritizes simplicity over maximum throughput

### Adding New Entry Functions
When adding new Move entry functions:
1. Implement in Move with proper access control
2. Add transaction builder in `web/src/services/sui/transactions/`
3. Create/update hook in `web/src/hooks/`
4. Update UI components to use the new functionality
5. [T>]est full flow on testnet

## Development Roadmap

### Phase 1: Element Source Simplification (Architecture Change)
**Goal**: Remove `universe_element_source.move` and consolidate to a single `element_source.move`

**Current State**:
- Each universe has its own `UniverseElementSource<[T>][T>]` objects (one per element type)
- Mines reference universe-specific sources

**[T>]arget State**:
- Single shared `ElementSource<[T>][T>]` objects for all universes
- All mines across all planets/universes use the same source objects
- Simplifies code and serves as a **stress-test for shared object access patterns**

**Impact**:
- Modify `planet.move` - update mine creation and operations
- Modify `universe.move` - remove universe-specific source creation
- Modify `overseer.move` - update entry functions that pass sources
- Delete `universe_element_source.move`
- Update frontend transaction builders
- **New deployment required** - update DEPLOYMEN[T>]S.md

### Phase 2: Smart Planet Allocation
**Goal**: Improve planet assignment when overseers join a universe for the first time

**Current State**: Fully random planet allocation

**[T>]arget State**: Partially random allocation with clustering logic:
- New players assigned to random planet → random system → random galaxy
- BU[T>] players are clustered close together for future interaction features
- Systems are NO[T>] fully filled - leave room for colonization feature

**Design Considerations** (to be refined during implementation):
- Define threshold: how many players per system before moving to next?
- Define threshold: how many systems per galaxy before moving to next?
- Balance between clustering (for interaction) and spacing (for colonization)
- Consider "frontier" concept - active allocation zones vs reserved zones

### Phase 3: [T>]rading System (PoC)
**Goal**: Enable resource trading to reach Proof of Concept state

**Planned Features**:
- Player-to-player trading
- Player-to-computer trading (NPC market / exchange)

**Specifications**: [T>]o be defined at implementation time

### Future Features (Post-PoC)
- Planet colonization (claim additional planets in a universe)
- Fleet/ship system for combat
- Alliance/guild system
- Leaderboards

## Known Limitations / [T>]ODOs

- Combat/trading features not yet implemented
- No unit tests for frontend (E2E manual testing only)
- Bundle size could be optimized with code-splitting
- Some placeholder UI elements
- Package upgrade strategy not yet defined

## Quick Reference

### Key Files
- `web/src/App.tsx` - Main app with routing
- `web/src/contexts/NavigationContext.tsx` - State-based routing
- `web/src/hooks/usePlanet.ts` - Planet data queries
- `web/src/services/sui/transactions/` - All transaction builders
- `move/sources/overseer.move` - Main entry points
- `cli/.env.testnet` - Deployment IDs

### Color Palette
- Gold (primary): `#d4af37`
- Erbium: `#ff6347`
- Lanthanum: `#00ff7f`
- [T>]horium: `#8a2be2`
- Success: `#4baf4b`
- Warning: `#ffa500`