archy/.cursor/rules/coding-rules.mdc

# Archipelago Development Rules

**Mission**: Build a production-ready, open-source Bitcoin Node OS that's secure, minimal, and user-friendly from day one.

**Philosophy**: Code in development should mirror production quality. Write it right the first time.

---

## Table of Contents
1. [Project Structure & Location](#project-structure--location)
2. [Open Source & Licensing](#open-source--licensing)
3. [Production-Ready Development](#production-ready-development)
4. [Architecture & System Design](#architecture--system-design)
5. [Backend Development (Rust)](#backend-development-rust)
6. [Frontend Development (Vue.js)](#frontend-development-vuejs)
7. [Container & Security](#container--security)
8. [Code Quality & Testing](#code-quality--testing)
9. [Documentation](#documentation)
10. [Common Mistakes](#common-mistakes)

---

## Project Structure & Location

### CRITICAL: Workspace-Relative Paths Only
- ❌ **NEVER** reference absolute user paths (`/Users/username/...`) in code, scripts, or documentation
- ✅ **ALWAYS** use workspace-relative paths: `./`, `../`, or environment variables
- ✅ All files must be created in the workspace, never in external directories
- ✅ When copying from external sources, copy TO workspace, then update all references

### File Creation Rules
- ✅ Create files directly in the workspace using relative paths
- ❌ Never assume files exist elsewhere - check first, create if missing
- ✅ Use environment variables for paths that change between environments
- ✅ Document all path dependencies in README or setup guides

---

## Open Source & Licensing

### License Compliance
- ✅ Project is **open source** under [specify license: MIT/Apache 2.0/GPL]
- ✅ All dependencies must be compatible with our license
- ✅ Check license compatibility before adding dependencies
- ✅ Document all third-party licenses in `LICENSES.md` or `THIRD_PARTY_NOTICES.md`

### Third-Party Code
- ✅ Use permissive licenses (MIT, Apache 2.0, BSD) when possible
- ⚠️ Be cautious with GPL/AGPL dependencies (viral licensing)
- ✅ Always include license headers in source files
- ✅ Document attribution for copied/adapted code

### Community Standards
- ✅ Follow [Contributor Covenant](https://www.contributor-covenant.org/) code of conduct
- ✅ Provide clear CONTRIBUTING.md with guidelines
- ✅ Use semantic versioning (SemVer) for releases
- ✅ Maintain comprehensive changelog (CHANGELOG.md)
- ✅ Accept community contributions via pull requests
- ✅ Respond to issues and PRs within reasonable timeframes

### Open Source Best Practices
- ✅ Never commit secrets, API keys, or credentials
- ✅ Use `.gitignore` to exclude sensitive/generated files
- ✅ Keep commit messages clear and descriptive
- ✅ Write documentation as if explaining to new contributors
- ✅ Include setup/installation scripts for easy onboarding

---

## Production-Ready Development

### Development = Production Mindset
- 🎯 **CRITICAL**: Write production-quality code from the start
- ✅ No "TODO: Fix before production" comments - fix it now
- ✅ No hardcoded values - use configuration from day one
- ✅ No "works on my machine" - test in clean environments
- ✅ Security is NOT optional - implement it in development

### Configuration Management
- ✅ Use `.env` files for environment-specific configuration
- ✅ Provide `.env.example` with all required variables
- ✅ Never commit `.env` files to git
- ✅ Validate configuration at startup with clear error messages
- ✅ Support multiple environments: dev, staging, production

### Infrastructure as Code
- ✅ All infrastructure should be reproducible from code
- ✅ Container definitions = production-ready from first commit
- ✅ Scripts should work on fresh systems (document prerequisites)
- ✅ Use Alpine Linux base for containers (production-ready minimal OS)
- ✅ Test multi-arch builds early (ARM64, x86_64)

### Development Environments
- ✅ Provide dev containers or Docker Compose setups
- ✅ Mock external services for local development
- ✅ Minimize differences between dev and production
- ✅ Document all system prerequisites clearly
- ✅ Use version managers for language runtimes (rustup, nvm)

### Continuous Integration Preparation
- ✅ Write code that can be automatically tested
- ✅ Keep builds fast (parallelize, cache dependencies)
- ✅ Lint and format code automatically
- ✅ Run security checks on dependencies
- ✅ Test on multiple platforms (Linux, macOS, ARM64)

---

## 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);
}
```

---

## Architecture & System Design

### Docker & Podman Architecture
- ✅ **Development**: Use Docker Compose with official Docker images
- ✅ **Production**: Use Podman with same Docker images on Alpine Linux
- ✅ **ALWAYS** use standard Docker Hub images (never proprietary formats)
- ✅ 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 for container management
- ✅ Use our RPC endpoints in `core/archipelago/src/`
- ✅ For development: Use mock backend for UI work when possible
- ✅ All new features must use our modules (`archipelago-*` crates)
- ✅ Build Archipelago-native implementations, not wrappers

### System Architecture Principles
- ✅ **Alpine Linux Base**: 130MB minimal, secure, multi-arch
- ✅ **Podman Only**: Rootless containers, no Docker dependencies
- ✅ **Manifest-Driven**: All apps defined by YAML manifests
- ✅ **Security First**: Read-only filesystems, capability dropping, network isolation
- ✅ **Dependency Resolution**: Automatic dependency management between apps
- ✅ **Health Monitoring**: Built-in health checks and auto-restart

### Multi-Architecture Support
- ✅ Support both ARM64 (Raspberry Pi) and x86_64 from day one
- ✅ Test builds on both architectures regularly
- ✅ Use multi-arch container images
- ✅ Document architecture-specific differences

### Modular Design
- ✅ Each crate in `core/` should be independent and reusable
- ✅ Minimize coupling between modules
- ✅ Define clear interfaces between components
- ✅ Use traits for abstraction and testability

---

## Container & Security

### App Manifest Rules (Production Standards)
- ✅ **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
- ✅ Define explicit dependencies with version constraints
- ✅ Include license information and attribution
- ✅ Document configuration options clearly
- ✅ Provide default values that are secure

### 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
- ✅ Implement graceful shutdown (handle SIGTERM)
- ✅ Set resource limits (CPU, memory, disk)
- ✅ Monitor container health continuously

### Security First (CRITICAL - Production Requirement)
- 🔒 **Security is NOT optional** - every container must be hardened

#### Container Security
- ✅ **ALWAYS** set `readonly_root: true` unless explicitly needed
- ✅ **ALWAYS** drop all capabilities, add only required ones
- ✅ **ALWAYS** use isolated networks (never `host` network unless required)
- ✅ **ALWAYS** run as non-root user (UID > 1000)
- ✅ **ALWAYS** set `no-new-privileges: true`
- ✅ Use AppArmor/SELinux profiles from `core/security/`
- ✅ Implement seccomp profiles to restrict syscalls

#### Image Security
- ✅ **ALWAYS** verify container images with Cosign signatures
- ✅ Use official base images from trusted registries
- ✅ Pin image versions (never use `latest` tag)
- ✅ Scan images for vulnerabilities (Trivy, Grype)
- ✅ Rebuild images regularly for security updates
- ✅ Generate and publish SBOM (Software Bill of Materials)

#### Secrets Management
- ✅ **NEVER** hardcode secrets in code or config files
- ✅ Use encrypted secrets storage (`core/security/secrets_manager.rs`)
- ✅ Inject secrets at runtime only (environment variables or mounted files)
- ✅ Rotate secrets regularly
- ✅ Use minimal secret scopes (principle of least privilege)
- ✅ Clear secrets from memory after use
- ✅ Log secret access for audit trails (without logging values)

#### Network Security
- ✅ Use isolated bridge networks per app
- ✅ Implement firewall rules (iptables/nftables)
- ✅ Rate limit API endpoints
- ✅ Use TLS for all external communication
- ✅ Support Tor for privacy-sensitive apps
- ✅ Implement intrusion detection (fail2ban)

#### Data Security
- ✅ Encrypt sensitive data at rest
- ✅ Use encrypted volumes for secrets
- ✅ Implement secure backup/restore
- ✅ Sanitize logs (no secrets in logs)
- ✅ Implement data retention policies
- ✅ Support secure data deletion

---

## Frontend Development (Vue.js)

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

### Production-Ready Frontend Code
- ✅ Handle loading states for all async operations
- ✅ Handle error states with user-friendly messages
- ✅ Implement retry logic for failed requests
- ✅ Show loading skeletons, not just spinners
- ✅ Debounce user inputs (search, filters)
- ✅ Implement infinite scroll/pagination for large lists
- ✅ Optimize images (WebP, lazy loading)
- ✅ Use Vue's `Suspense` for async components

### 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
- ✅ Implement request timeouts (default: 30s)
- ✅ Retry failed requests with exponential backoff
- ✅ Cancel in-flight requests when component unmounts
- ✅ Handle errors gracefully with user-friendly messages
- ✅ Log errors to monitoring service (in production)

### State Management (Production Standards)
- ✅ 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
- ✅ Persist auth state to localStorage/sessionStorage
- ✅ Clear sensitive data on logout
- ✅ Implement optimistic updates for better UX
- ✅ Handle state hydration errors gracefully

### TypeScript Frontend Best Practices
- ✅ Enable strict mode in `tsconfig.json`
- ✅ Define interfaces for all API responses
- ✅ Use type guards for runtime type checking
- ✅ Avoid `any` - use `unknown` or proper types
- ✅ Use discriminated unions for state machines
- ✅ Export types from dedicated `.types.ts` files
- ✅ Use Zod or similar for runtime validation

### Accessibility (A11y) - Production Requirement
- ✅ All interactive elements must be keyboard accessible
- ✅ Use semantic HTML (`<button>`, `<nav>`, `<main>`)
- ✅ Include ARIA labels where needed
- ✅ Maintain proper heading hierarchy (h1 → h2 → h3)
- ✅ Ensure color contrast meets WCAG AA standards
- ✅ Test with screen readers (VoiceOver, NVDA)
- ✅ Support light/dark mode (via CSS variables)

### Performance Optimization
- ✅ Lazy load routes and heavy components
- ✅ Use `v-memo` for expensive list renders
- ✅ Implement virtual scrolling for long lists
- ✅ Minimize bundle size (analyze with `vite-bundle-visualizer`)
- ✅ Use dynamic imports for code splitting
- ✅ Optimize assets (images, fonts, icons)
- ✅ Enable gzip/brotli compression in production

---

## Backend Development (Rust)

### 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
- ✅ Keep crates small and focused (single responsibility)
- ✅ Use `lib.rs` for public APIs, keep implementation in separate files

### Production-Ready Rust Code
- ✅ **No `unwrap()` or `expect()` in production code** - handle all errors properly
- ✅ Use `?` operator for error propagation
- ✅ Implement `Debug`, `Clone`, `PartialEq` where appropriate
- ✅ Use `#[non_exhaustive]` for public enums/structs that may evolve
- ✅ Add `#[must_use]` to functions whose return value should be checked
- ✅ Use `#[inline]` for small hot-path functions

### Error Handling (Production Standards)
- ✅ Use `thiserror` for library error types
- ✅ Use `anyhow` for application-level error handling
- ✅ Create custom error types per module: `{module}::Error`
- ✅ Include context in errors: `.context("What failed and why")`
- ✅ Return user-friendly error messages (no internal details)
- ✅ Log errors with appropriate levels: `error!`, `warn!`, `info!`, `debug!`, `trace!`
- ✅ Never expose stack traces to users (log internally only)

### RPC Endpoint Rules
- ✅ Use `rpc_toolkit::command` macro for all endpoints
- ✅ Use `#[context] ctx: RpcContext` for context
- ✅ Use `#[arg]` for parameters with validation
- ✅ Return `Result<T, Error>` for all endpoints
- ✅ Validate all inputs before processing
- ✅ Document endpoints with `///` doc comments
- ✅ Include usage examples in documentation

### Async Rust Best Practices
- ✅ Use `tokio` runtime consistently (don't mix with other runtimes)
- ✅ Prefer `async/await` over manual futures
- ✅ Use channels (`mpsc`, `oneshot`) for inter-task communication
- ✅ Set timeouts on all external operations
- ✅ Use `select!` for racing futures with timeouts
- ✅ Handle shutdown gracefully with cancellation tokens

### Memory Safety & Performance
- ✅ Minimize allocations in hot paths
- ✅ Use `Arc` for shared ownership, `Rc` for single-threaded
- ✅ Use `Cow` for potentially borrowed data
- ✅ Prefer zero-copy when possible (slices, references)
- ✅ Run `clippy` with `--all-targets --all-features`
- ✅ Fix all clippy warnings before committing

### Testing (Production Standards)
- ✅ Write unit tests for all public functions
- ✅ Write integration tests for API endpoints
- ✅ Use `#[cfg(test)]` for test-only code
- ✅ Mock external dependencies (filesystem, network, time)
- ✅ Test error cases, not just happy paths
- ✅ Use property-based testing for complex logic (proptest)
- ✅ Aim for >80% code coverage on core logic

### Logging & Observability
- ✅ Use `tracing` for structured logging
- ✅ Include context in log messages: `tracing::info!(user_id = %id, "Action")`
- ✅ Use appropriate log levels consistently
- ✅ Don't log sensitive data (passwords, keys, tokens)
- ✅ Include request IDs for tracing across services
- ✅ Emit metrics for monitoring (response times, error rates)

---

## Documentation

### Documentation Standards (Production Requirement)
- 📖 **CRITICAL**: Documentation is as important as code

### Code Documentation
- ✅ Document all public APIs (Rust `///`, JSDoc for TypeScript)
- ✅ Include usage examples in documentation
- ✅ Explain edge cases and error conditions
- ✅ Document panics/unwraps (should be none in production)
- ✅ Keep documentation in sync with code

### Project Documentation
- ✅ Keep `README.md` up to date with installation instructions
- ✅ Update `docs/` when adding features
- ✅ Document architecture decisions (ADRs in `docs/architecture/`)
- ✅ Maintain changelog (`CHANGELOG.md`) with every release
- ✅ Document breaking changes prominently
- ✅ Include troubleshooting guide (`docs/troubleshooting.md`)

### User Documentation
- ✅ Write user-facing documentation for all features
- ✅ Include screenshots/screencasts where helpful
- ✅ Document configuration options with examples
- ✅ Provide step-by-step tutorials
- ✅ Keep FAQ updated with common questions

### API Documentation
- ✅ Document all RPC endpoints with examples
- ✅ Include request/response schemas
- ✅ Document error codes and meanings
- ✅ Provide API versioning strategy
- ✅ Auto-generate API docs from code (cargo doc, TypeDoc)

### Contributing Documentation
- ✅ Provide `CONTRIBUTING.md` with guidelines
- ✅ Document development setup in detail
- ✅ Explain project structure
- ✅ Include code style guidelines
- ✅ Document release process

---

## Development Workflow

### Backend: always build on the dev server (never on macOS)
- **CRITICAL**: The Rust backend **must** be built **on the Linux dev server**, not on macOS. Deploy by **rsync then build**:
  1. **Rsync** source to server: `sshpass -p "archipelago" rsync -avz --exclude target --exclude .git -e "ssh -o StrictHostKeyChecking=no" core/ archipelago@192.168.1.228:~/archy/core/`
  2. **Build and deploy on server**: `sshpass -p "archipelago" ssh -o StrictHostKeyChecking=no archipelago@192.168.1.228 'source ~/.cargo/env && cd ~/archy/core/archipelago && cargo build --release && sudo systemctl stop archipelago && sudo cp ~/archy/core/target/release/archipelago /usr/local/bin/ && sudo systemctl start archipelago'`
- When making backend changes, **action the build**: run the rsync + SSH build/deploy steps above. Do not build the binary locally and copy it (causes Exec format error on Linux).
- Dev server: `archipelago@192.168.1.228`, password: `archipelago`.

### Scripts & Automation
- ✅ All scripts in `scripts/` directory
- ✅ Use `#!/usr/bin/env bash` for portability
- ✅ Use `set -euo pipefail` (exit on error, undefined vars, pipe failures)
- ✅ Check for prerequisites before running
- ✅ Provide clear error messages with solutions
- ✅ Use workspace-relative paths (never absolute)
- ✅ Make scripts idempotent (safe to run multiple times)
- ✅ Log what the script is doing (with timestamps)

### Dependency Management

#### Node.js & Dependencies
- ⚠️ **Node.js Version**: Requires Node.js 20.19+ or 22.12+ for Vite 7
- ✅ Use `nvm` or `fnm` for Node.js version management
- ✅ Commit `package-lock.json` (ensures reproducible builds)
- ✅ Use `npm ci` for CI/CD (clean install from lock file)
- ✅ Run `npm audit` regularly and fix vulnerabilities
- ✅ Keep dependencies up to date (use Dependabot/Renovate)
- ✅ Document any dependencies that must be at specific versions

#### Rust Dependencies
- ✅ Keep `Cargo.lock` committed (ensures reproducible builds)
- ✅ Use `cargo update` carefully (test after updating)
- ✅ Run `cargo audit` regularly for security vulnerabilities
- ✅ Prefer well-maintained crates with active communities
- ✅ Check license compatibility before adding dependencies
- ✅ Document why specific versions are required

### Git Workflow
- ✅ Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`
- ✅ Write clear, descriptive commit messages
- ✅ Keep commits atomic (one logical change per commit)
- ✅ Rebase feature branches before merging
- ✅ Never commit secrets, API keys, or credentials
- ✅ Use `.gitignore` for generated files
- ✅ Tag releases with semantic versions (`v1.2.3`)

### Branch Strategy
- ✅ `main` branch is production-ready at all times
- ✅ Feature branches: `feature/description`
- ✅ Bug fixes: `fix/description`
- ✅ Use pull requests for all changes
- ✅ Require CI passing before merge
- ✅ Delete branches after merging

---

## Common Mistakes

### ❌ NEVER DO:
1. **Hardcode absolute paths** - Use workspace-relative paths
2. **Use inline Tailwind classes** - Create global utility classes
3. **Skip security policies** - Security is mandatory
4. **Hardcode secrets/URLs** - Use environment variables
5. **Use `unwrap()` in production** - Handle errors properly
6. **Skip tests** - Test coverage is required
7. **Commit secrets** - Use `.env` files (not committed)
8. **Leave TODOs** - Fix now or create issues
9. **Use `any` in TypeScript** - Use proper types
10. **Ignore compiler warnings** - Fix all warnings
11. **Use `latest` tag** - Pin specific versions
12. **Run as root** - Use non-root users
13. **Forget documentation** - Document as you code
14. **Use proprietary package formats** - Use standard Docker images
15. **Depend on external registries** - Host our own or use Docker Hub

### ✅ ALWAYS DO:
1. **Build backend on the dev server** - Rsync `core/` to `archipelago@192.168.1.228:~/archy/core/`, then SSH in and run `cargo build --release` and deploy the binary. Never build the Rust binary on macOS for deployment.
2. **Use workspace-relative paths** - Portable code
3. **Create global Tailwind classes** - Consistent styling
4. **Build Archipelago-native solutions** - Clean architecture
5. **Include security in all containers** - Security first
6. **Use environment variables** - Configurable deployments
7. **Add modules to Cargo.toml** - Workspace coherence
8. **Create reusable components** - DRY principle
9. **Use Docker (dev) or Podman (prod)** - Standard containers
10. **Handle all errors gracefully** - User-friendly messages
11. **Follow the architecture plan** - Consistency
12. **Write tests** - Prevent regressions
13. **Document code** - Help future contributors
14. **Review your own code** - Catch issues early
15. **Run CI checks locally** - Before pushing
16. **Think production first** - Build it right

## 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 & Testing

### Code Quality Standards (Production Requirement)
- 🎯 **CRITICAL**: All code must pass CI checks before merging
- ✅ Zero compiler warnings (Rust and TypeScript)
- ✅ Zero linter errors (clippy, eslint)
- ✅ Consistent formatting (rustfmt, prettier)
- ✅ No commented-out code in commits
- ✅ Remove `TODO`/`FIXME` or create issues for them

### Rust Code Quality
- ✅ Run `cargo clippy --all-targets --all-features` before commit
- ✅ Run `cargo fmt --all` before commit
- ✅ Run `cargo test --all-features` before commit
- ✅ Use `#[deny(clippy::all)]` and `#[warn(clippy::pedantic)]` in lib.rs
- ✅ Document all public APIs with `///` doc comments
- ✅ Include usage examples in documentation
- ✅ Use `#[derive(Debug)]` for all types where possible

### TypeScript Code Quality
- ✅ Enable strict mode in `tsconfig.json`
- ✅ Run `npm run lint` before commit
- ✅ Run `npm run type-check` before commit
- ✅ Fix all ESLint warnings, not just errors
- ✅ Use Prettier for consistent formatting
- ✅ Define interfaces for all data structures
- ✅ Use type guards for runtime checks
- ✅ Avoid `any` - use `unknown` or proper types

### General Code Quality
- ✅ Keep functions small (<50 lines) and focused (single responsibility)
- ✅ Use descriptive variable names (no `x`, `tmp`, `data`)
- ✅ Comment WHY, not WHAT (code should be self-documenting)
- ✅ Extract magic numbers to named constants
- ✅ Remove dead code (don't comment it out)
- ✅ Follow existing code style in the file
- ✅ DRY principle: Don't Repeat Yourself (extract common logic)

### Testing (Production Requirement)
- 🎯 **CRITICAL**: All features must have tests

#### Rust Testing
- ✅ Write unit tests for all public functions
- ✅ Write integration tests for API endpoints
- ✅ Test error cases, not just happy paths
- ✅ Use `#[cfg(test)]` for test-only code
- ✅ Mock external dependencies (filesystem, network)
- ✅ Test concurrency/race conditions
- ✅ Use property-based testing for complex logic (proptest)
- ✅ Aim for >80% code coverage on core logic

#### Frontend Testing
- ✅ Test UI components with Vitest
- ✅ Test user interactions (clicks, inputs)
- ✅ Test accessibility (ARIA, keyboard navigation)
- ✅ Test error states and edge cases
- ✅ Mock API calls in component tests
- ✅ Use snapshot testing sparingly (they break often)

#### Integration Testing
- ✅ Test full user flows end-to-end
- ✅ Test container lifecycle (install, start, stop, remove)
- ✅ Test dependency resolution
- ✅ Test backup/restore functionality
- ✅ Test upgrade scenarios
- ✅ Test multi-user scenarios (if applicable)

### Code Review Standards
- ✅ All code must be reviewed by at least one other developer
- ✅ Reviewer must test the changes locally
- ✅ Check for security vulnerabilities
- ✅ Verify tests are comprehensive
- ✅ Ensure documentation is updated
- ✅ Look for performance issues

---

## Performance & Monitoring

### Performance Optimization (Production Standards)
- ✅ Set resource limits in all containers (CPU, memory, disk I/O)
- ✅ Implement caching at multiple layers (API, database, assets)
- ✅ Use connection pooling for databases
- ✅ Lazy load components and routes
- ✅ Optimize images (WebP, responsive sizes)
- ✅ Enable compression (gzip, brotli)
- ✅ Use CDN for static assets (in production)
- ✅ Implement database indexes on queried fields
- ✅ Profile before optimizing (don't guess)
- ✅ Set up performance budgets (load time, bundle size)

### Monitoring & Observability (Production Requirement)
- 📊 **CRITICAL**: Production requires comprehensive monitoring

#### Logging
- ✅ Use structured logging (JSON format)
- ✅ Include context (request ID, user ID, timestamps)
- ✅ Log at appropriate levels (error, warn, info, debug)
- ✅ Aggregate logs centrally (Loki, Elasticsearch)
- ✅ Set up log retention policies
- ✅ Never log secrets or sensitive data

#### Metrics
- ✅ Track container resource usage (CPU, memory, disk)
- ✅ Monitor API response times
- ✅ Track error rates and types
- ✅ Monitor health check status
- ✅ Track user actions (anonymized)
- ✅ Set up dashboards (Grafana)

#### Alerting
- ✅ Alert on container failures
- ✅ Alert on high resource usage
- ✅ Alert on error rate spikes
- ✅ Alert on health check failures
- ✅ Use appropriate alert channels (email, Slack, PagerDuty)
- ✅ Document incident response procedures

#### Health Checks
- ✅ Implement liveness probes (is container running?)
- ✅ Implement readiness probes (is container ready for traffic?)
- ✅ Set appropriate timeouts and intervals
- ✅ Restart containers on health check failures
- ✅ Expose health endpoints (`/health`, `/ready`)

---

## Production Deployment

### Pre-Production Checklist
- ✅ All tests passing (unit, integration, e2e)
- ✅ All linters passing (no warnings)
- ✅ Security audit completed
- ✅ Performance testing completed
- ✅ Load testing completed
- ✅ Documentation updated
- ✅ Changelog updated
- ✅ Migration scripts tested
- ✅ Rollback plan documented
- ✅ Monitoring configured

### Deployment Strategy
- ✅ Use blue-green or canary deployments
- ✅ Test in staging environment first
- ✅ Deploy during low-traffic windows
- ✅ Monitor metrics closely after deployment
- ✅ Have rollback plan ready
- ✅ Communicate with users about maintenance

### Post-Deployment
- ✅ Verify all services are healthy
- ✅ Check logs for errors
- ✅ Monitor metrics for anomalies
- ✅ Test critical user flows
- ✅ Document any issues encountered
- ✅ Update status page

---

## Final Principles

### The Archipelago Way

1. **Production-Ready from Day One**
   - Write code as if it's going to production tomorrow
   - No "we'll fix it later" - fix it now

2. **Open Source First**
   - Code in the open, collaborate freely
   - Document everything for community contributors
   - Respect licenses and attribution

3. **Security is Not Optional**
   - Every container is hardened
   - Every secret is encrypted
   - Every network is isolated

4. **Simplicity Over Complexity**
   - Minimal codebase, maximum functionality
   - Alpine Linux base: 130MB, not 1.5GB
   - Clear architecture, no magic

5. **Community-Driven**
   - Listen to users and contributors
   - Accept feedback graciously
   - Build what the community needs

---

**Remember**: This is Archipelago - a clean, modern Bitcoin Node OS built with standard Docker containers, Alpine Linux, and Podman.

**Mission**: A production-ready, open-source Bitcoin Node OS that anyone can trust, deploy, and contribute to.