# Archipelago Development Rules

## CRITICAL: Project Structure & Location

### NEVER Reference External Directories
- ❌ **NEVER** reference `/Users/tx1138/Code/Archipelago/` in code, scripts, or documentation
- ✅ **ALWAYS** use workspace-relative paths: `./`, `../`, or `$PROJECT_ROOT`
- ✅ The workspace at `/Users/tx1138/Archipelago` is the ONLY project location
- ✅ All files must be created in the workspace, never in external directories

### File Creation Rules
- ✅ Create files directly in the workspace using relative paths
- ❌ Never assume files exist elsewhere - check first, create if missing
- ✅ When copying from external sources, copy TO workspace, then update references

## Design System & Styling

### Tailwind CSS Rules
- ✅ **ALWAYS** create global utility classes in `neode-ui/src/style.css` or a dedicated `tailwind.css`
- ❌ **NEVER** use inline Tailwind classes directly in components
- ✅ Create semantic class names: `.glass-card`, `.glass-button`, `.nav-tab-active`
- ✅ Use CSS variables for design tokens: `--color-primary`, `--spacing-base`

### Design Standards (From Memory)
- **Font**: Avenir Next font family (preferred)
- **Padding**: 4px grid system, 16px default padding
- **Containers**: iOS-style glassmorphism
  - Background: `rgba(255,255,255,0.15)`
  - Backdrop blur: `20px`
  - Subtle white borders
- **Backgrounds**: Persistent background images (not dark themes)
- **Animations**: Smooth 2s splash screens with logo draw/glitch animations

### Example Global Classes
```css
.glass-card {
  background: rgba(255, 255, 255, 0.15);
  backdrop-filter: blur(20px);
  -webkit-backdrop-filter: blur(20px);
  border: 1px solid rgba(255, 255, 255, 0.2);
  border-radius: 16px;
  padding: 16px; /* 4px grid */
}

.glass-button {
  background: rgba(255, 255, 255, 0.1);
  backdrop-filter: blur(10px);
  border: 1px solid rgba(255, 255, 255, 0.15);
  transition: all 0.2s ease;
}

.glass-button:hover {
  background: rgba(255, 255, 255, 0.2);
}
```

## StartOS Independence

### Zero StartOS Dependencies
- ❌ **NEVER** import or reference StartOS-specific code
- ❌ **NEVER** copy StartOS patterns without refactoring
- ✅ **ALWAYS** create Archipelago-native implementations
- ✅ Use our own container orchestration (`core/container/`)
- ✅ Use our own security modules (`core/security/`)
- ✅ Use our own performance modules (`core/performance/`)

### Backend Architecture
- ✅ Use `archipelago-container` crate, not StartOS container code
- ✅ Use our RPC endpoints in `core/startos/src/container/`
- ⚠️ **TEMPORARY**: Using StartOS backend (`startbox`) as base - this is temporary
- ✅ **GOAL**: Build our own Archipelago backend binary that uses ONLY our modules
- ✅ Mark all StartOS-derived code with `// TODO: Refactor to Archipelago-native`
- ✅ For development: Use mock backend for UI work, avoid StartOS backend when possible
- ✅ All new features must use our modules (`archipelago-container`, `archipelago-security`, etc.)

## Container & App Development

### App Manifest Rules
- ✅ **ALWAYS** create manifests in `apps/{app-id}/manifest.yml`
- ✅ Follow the manifest specification in `docs/app-manifest-spec.md`
- ✅ Use semantic versioning: `MAJOR.MINOR.PATCH`
- ✅ Include security policies, resource limits, health checks

### Container Orchestration
- ✅ Use `archipelago_container::PodmanClient` for all container operations
- ✅ Use `archipelago_container::AppManifest` for manifest parsing
- ✅ Use `archipelago_container::DependencyResolver` for dependency management
- ❌ Never use Docker directly - always use Podman via our client

### Security First
- ✅ **ALWAYS** set `readonly_root: true` unless explicitly needed
- ✅ **ALWAYS** drop all capabilities, add only required ones
- ✅ **ALWAYS** use isolated networks unless host network is required
- ✅ **ALWAYS** verify container images with Cosign signatures
- ✅ Use AppArmor profiles from `core/security/`

## Frontend Development

### Vue.js Component Rules
- ✅ Use Composition API (`<script setup lang="ts">`)
- ✅ Use Pinia stores for state management
- ✅ Use TypeScript for all components
- ✅ Create reusable components in `neode-ui/src/components/`
- ✅ Use global Tailwind classes, not inline utilities

### API Client Rules
- ✅ Use `neode-ui/src/api/rpc-client.ts` for RPC calls
- ✅ Use `neode-ui/src/api/container-client.ts` for container operations
- ✅ **NEVER** hardcode API endpoints - use environment variables
- ✅ Handle errors gracefully with user-friendly messages

### State Management
- ✅ Use Pinia stores for all application state
- ✅ Keep stores focused and single-purpose
- ✅ Use TypeScript interfaces for store state
- ✅ Don't duplicate state - use computed properties

## Backend Development

### Rust Code Organization
- ✅ New modules go in `core/{module-name}/`
- ✅ Use workspace structure: add to `core/Cargo.toml` members
- ✅ Follow Rust naming conventions: `snake_case` for modules/files
- ✅ Use `thiserror` for error types, `anyhow` for error handling

### RPC Endpoint Rules
- ✅ Use `rpc_toolkit::command` macro for all endpoints
- ✅ Use `#[context] ctx: RpcContext` for context
- ✅ Use `#[arg]` for parameters
- ✅ Return `Result<T, Error>` for all endpoints
- ✅ Add endpoints to `core/startos/src/lib.rs` subcommands

### Error Handling
- ✅ Use `crate::Error` and `crate::ErrorKind` for errors
- ✅ Provide context with `.context()` or `.with_kind()`
- ✅ Log errors with `tracing::error!` or `log::error!`
- ✅ Return user-friendly error messages

## Development Workflow

### Scripts & Automation
- ✅ All scripts in `scripts/` directory
- ✅ Use `#!/bin/bash` with `set +e` (don't exit on first error)
- ✅ Check for prerequisites before running
- ✅ Provide clear error messages
- ✅ Use workspace-relative paths

### Node.js & Dependencies
- ⚠️ **Node.js Version**: Requires Node.js 20.19+ or 22.12+ for Vite 7
- ✅ If dependencies are broken, delete `node_modules` and `package-lock.json`, then `npm install`
- ✅ Always verify `node_modules/.bin/` executables work after install
- ✅ Use `npm ci` for CI/CD (clean install from lock file)

### Testing
- ✅ Write tests for all Rust modules
- ✅ Test container operations with mock Podman
- ✅ Test UI components with Vitest
- ✅ Test API endpoints with integration tests

### Documentation
- ✅ Update `docs/` when adding features
- ✅ Document all public APIs
- ✅ Include examples in documentation
- ✅ Keep README.md up to date

## Common Mistakes to Avoid

### ❌ DON'T:
1. Reference `/Users/tx1138/Code/Archipelago/` anywhere
2. Create files outside the workspace
3. Use inline Tailwind classes
4. Import StartOS code directly
5. Skip security policies in manifests
6. Hardcode paths or URLs
7. Forget to add new modules to Cargo.toml
8. Create components without global styles
9. Use Docker instead of Podman
10. Skip error handling

### ✅ DO:
1. Always use workspace-relative paths
2. Create global Tailwind utility classes
3. Build Archipelago-native solutions
4. Include security in all containers
5. Use environment variables for configuration
6. Add modules to workspace Cargo.toml
7. Create reusable styled components
8. Use Podman via our client wrapper
9. Handle all errors gracefully
10. Follow the architecture plan

## Architecture Adherence

### Stick to the Plan
- ✅ Follow `docs/architecture.md` for system design
- ✅ Use Alpine Linux base (not Ubuntu/Debian)
- ✅ Use Podman (not Docker)
- ✅ Use rootless containers
- ✅ Implement security hardening
- ✅ Support multi-arch (ARM64, x86_64)

### Container Orchestration
- ✅ Use manifest-based app definitions
- ✅ Implement dependency resolution
- ✅ Monitor container health
- ✅ Support Parmanode compatibility
- ✅ Enable secrets management

### Future-Proofing
- ✅ Design for time-travel snapshots
- ✅ Plan for decentralized marketplace
- ✅ Support multi-node clustering
- ✅ Enable hardware attestation
- ✅ Keep protocol-agnostic design

## Code Quality

### TypeScript
- ✅ Use strict mode
- ✅ Define interfaces for all data structures
- ✅ Use type guards for runtime checks
- ✅ Avoid `any` - use `unknown` if needed

### Rust
- ✅ Use `clippy` for linting
- ✅ Use `rustfmt` for formatting
- ✅ Document public APIs with `///`
- ✅ Use `#[derive(Debug)]` for error types

### General
- ✅ Keep functions small and focused
- ✅ Use descriptive variable names
- ✅ Comment complex logic
- ✅ Remove dead code
- ✅ Follow existing code style

## Performance

### Optimization Rules
- ✅ Use resource limits in all containers
- ✅ Implement caching where appropriate
- ✅ Lazy load components when possible
- ✅ Optimize images and assets
- ✅ Use connection pooling for databases

### Monitoring
- ✅ Log important events
- ✅ Track container resource usage
- ✅ Monitor health checks
- ✅ Alert on failures

## Security

### Always Implement
- ✅ Image signature verification
- ✅ Secrets encryption
- ✅ AppArmor/SELinux profiles
- ✅ Network isolation
- ✅ Capability dropping
- ✅ Read-only root filesystems

### Never Skip
- ❌ Security policies in manifests
- ❌ Image verification
- ❌ Secrets management
- ❌ Network isolation
- ❌ Resource limits

---

**Remember**: This is Archipelago, not StartOS. Build it right, build it secure, build it our way.