lfg2025/archy
1
0
Fork 0
Code Issues 24 Pull Requests 4 Actions Packages Projects Releases 73 Wiki Activity

Update archipelago: API, auth, container, parmanode, performance, security

Browse Source 
- API handler, RPC, and server updates
- Auth and coding rules
- Container data manager, dev orchestrator, health monitor, podman client
- Parmanode script runner
- Performance resource manager
- Security container policies and secrets manager
- Add build scripts and documentation
This commit is contained in:
Dorian
2026-01-27 22:27:17 +00:00
parent 0d073fa89e
commit 1c024c5d64
5332 changed files with 8978 additions and 24160 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursor/rules/Architecture.mdc
+169
View File
@@ -0,0 +1,169 @@
---
alwaysApply: true
---
# Archipelago Bitcoin Node OS - Architecture Documentation
## Overview
Archipelago is a next-generation Bitcoin Node OS built on Alpine Linux with Podman containerization, combining the modularity of Parmanode with the security and efficiency of a minimal server OS.
## System Architecture
```
┌─────────────────────────────────────────────────────────┐
│ Alpine Linux Base (130MB) │
│ - Minimal kernel │
│ - Hardened security │
│ - Read-only root filesystem │
└─────────────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌───────▼──────┐ ┌──────▼──────┐ ┌─────▼──────┐
│ Podman │ │ Rust Backend│ │ Vue.js UI │
│ (rootless) │ │ (core/) │ │ (neode-ui/) │
└───────┬──────┘ └──────┬──────┘ └─────────────┘
│ │
└───────┬───────┘
│
┌───────────▼───────────┐
│ Container Orchestration│
│ Layer (new) │
│ - Manifest parser │
│ - Podman client │
│ - Dependency resolver │
│ - Health monitor │
└───────────┬───────────┘
│
┌───────────▼───────────┐
│ Containerized Apps │
│ - Bitcoin Core │
│ - LND / CLN │
│ - BTCPay Server │
│ - Nostr Relays │
│ - Meshtastic │
│ - Web5 DWN │
└───────────────────────┘
```
## Key Components
### 1. Alpine Linux Base
- **Size**: ~130MB (vs 1.5GB+ for Umbrel/StartOS)
- **Security**: Hardened kernel, minimal attack surface
- **Multi-arch**: ARM64 (Raspberry Pi) and x86_64 support
### 2. Container Orchestration Layer
Located in `core/container/`:
- **manifest.rs**: Parses YAML app manifests
- **podman_client.rs**: Wraps Podman API for container management
- **dependency_resolver.rs**: Resolves app dependencies and conflicts
- **health_monitor.rs**: Monitors container health and auto-restarts
### 3. Backend API Extensions
New RPC endpoints in `core/startos/src/container/`:
- `container-install`: Install app from manifest
- `container-start/stop/remove`: Container lifecycle
- `container-status/logs`: Status and debugging
- `container-list`: List all containers
- `container-health`: Health status aggregation
### 4. Vue.js UI Integration
New components in `neode-ui/`:
- **ContainerApps.vue**: List of containerized apps
- **ContainerAppDetails.vue**: Detailed app view with logs
- **ContainerStatus.vue**: Status indicator component
- **container-client.ts**: API client for container operations
- **container.ts**: Pinia store for container state
### 5. App Manifest System
Standardized YAML format in `apps/`:
- Defines container image, resources, dependencies
- Security policies and health checks
- Bitcoin/Lightning/Web5 integration metadata
### 6. Parmanode Compatibility
Located in `core/parmanode/`:
- **script_runner.rs**: Executes Parmanode scripts in containers
- **converter.rs**: Converts Parmanode modules to app manifests
- **parmanode-wrapper.sh**: Shell wrapper for direct script execution
### 7. Security Modules
Located in `core/security/`:
- **container_policies.rs**: Generates AppArmor/SELinux profiles
- **secrets_manager.rs**: Encrypted secrets storage
- **image_verifier.rs**: Cosign signature verification
### 8. Performance Optimization
Located in `core/performance/`:
- **resource_manager.rs**: CPU/memory/disk allocation
- **optimize-alpine.sh**: OS-level optimizations
## App Categories
### Bitcoin & Lightning
- Bitcoin Core (full node)
- LND (Lightning Network Daemon)
- Core Lightning (CLN)
- BTCPay Server
- Mempool (blockchain explorer)
### Web5 & Decentralized Protocols
- Nostr relays (nostr-rs-relay, strfry)
- Web5 DWN (Decentralized Web Node)
- DID Wallet
- Bitcoin Domain Names
### Mesh Networking & Routing
- Meshtastic (LoRa mesh networking)
- Router (mesh routing, device discovery)
- Local network management
### Self-Hosted Services
- Home Assistant
- Grafana
- SearXNG
- OnlyOffice
- Ollama (local AI)
- Penpot
## Security Model
1. **OS Level**: Hardened Alpine, read-only root, minimal kernel
2. **Container Level**: Rootless Podman, capability dropping, network isolation
3. **Secrets**: Encrypted storage, runtime injection only
4. **Supply Chain**: Signed images (Cosign), SBOM generation
5. **Network**: Firewall, rate limiting, Tor integration
6. **Audit**: Immutable logs, configuration tracking
## Networking
- **Isolated Networks**: Each app on separate bridge network by default
- **Bitcoin Core**: Isolated network, explicit RPC access
- **Lightning Nodes**: Separate network, gRPC/REST exposed
- **Tor Integration**: Optional, default for privacy-sensitive apps
- **Mesh Networking**: Meshtastic and router support for decentralized communication
## Data Persistence
- **App Data**: `/var/lib/archipelago/{app-id}/`
- **Secrets**: `/var/lib/archipelago/secrets/{app-id}/` (encrypted)
- **Logs**: `/var/lib/archipelago/logs/{app-id}/`
- **Backups**: `/var/lib/archipelago/backups/`
## Future Enhancements
- Time-travel snapshots (ZFS/BTRFS)
- Decentralized app marketplace (IPFS + Nostr)
- Multi-node clustering
- Hardware attestation (TPM 2.0)
- Protocol-agnostic design (multi-chain support)
.cursor/rules/coding-rules.mdc
+585 -111
View File
@@ -1,17 +1,110 @@
# Archipelago Development Rules
## CRITICAL: Project Structure & Location
**Mission**: Build a production-ready, open-source Bitcoin Node OS that's secure, minimal, and user-friendly from day one.
### 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
**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
- ✅ When copying from external sources, copy TO workspace, then update references
- ✅ 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
@@ -54,9 +147,11 @@
}
```
## StartOS Independence
---
### Zero StartOS Dependencies
## Architecture & System Design
### StartOS Independence
- ❌ **NEVER** import or reference StartOS-specific code
- ❌ **NEVER** copy StartOS patterns without refactoring
- ✅ **ALWAYS** create Archipelago-native implementations
@@ -66,128 +161,369 @@
### 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
- ✅ Use our RPC endpoints in `core/archipelago/src/`
- ⚠️ **TEMPORARY**: Using StartOS backend as base during Phase 1
- 🎯 **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.)
- ✅ For development: Use mock backend for UI work when possible
- ✅ All new features must use our modules (`archipelago-*` crates)
## Container & App Development
### 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
### App Manifest Rules
### 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
### 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 unless host network is required
- ✅ **ALWAYS** verify container images with Cosign signatures
- ✅ Use AppArmor profiles from `core/security/`
- ✅ **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
## Frontend Development
#### 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">`)
- ✅ Use Composition API (`<script setup lang="ts">`) for all components
- ✅ Use Pinia stores for state management
- ✅ Use TypeScript for all components
- ✅ 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
### 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
## Backend Development
### 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
- ✅ Use `thiserror` for error types, `anyhow` for error handling
- ✅ 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
- ✅ Use `#[arg]` for parameters with validation
- ✅ Return `Result<T, Error>` for all endpoints
- ✅ Add endpoints to `core/startos/src/lib.rs` subcommands
- ✅ Validate all inputs before processing
- ✅ Document endpoints with `///` doc comments
- ✅ Include usage examples in documentation
### 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
### 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
### Scripts & Automation
- ✅ All scripts in `scripts/` directory
- ✅ Use `#!/bin/bash` with `set +e` (don't exit on first error)
- ✅ 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
- ✅ Use workspace-relative paths
- ✅ 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)
### Node.js & Dependencies
### Dependency Management
#### 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 `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
### Testing
- ✅ Write tests for all Rust modules
- ✅ Test container operations with mock Podman
- ✅ Test UI components with Vitest
- ✅ Test API endpoints with integration tests
#### 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
### Documentation
- ✅ Update `docs/` when adding features
- ✅ Document all public APIs
- ✅ Include examples in documentation
- ✅ Keep README.md up to date
### 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`)
## Common Mistakes to Avoid
### 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
### ❌ 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
## Common Mistakes
### ❌ NEVER DO:
1. **Hardcode absolute paths** - Use workspace-relative paths
2. **Use inline Tailwind classes** - Create global utility classes
3. **Import StartOS code directly** - Build Archipelago-native
4. **Skip security policies** - Security is mandatory
5. **Hardcode secrets/URLs** - Use environment variables
6. **Use `unwrap()` in production** - Handle errors properly
7. **Use Docker** - Use Podman via our client
8. **Skip tests** - Test coverage is required
9. **Commit secrets** - Use `.env` files (not committed)
10. **Leave TODOs** - Fix now or create issues
11. **Use `any` in TypeScript** - Use proper types
12. **Ignore compiler warnings** - Fix all warnings
13. **Use `latest` tag** - Pin specific versions
14. **Run as root** - Use non-root users
15. **Forget documentation** - Document as you code
### ✅ ALWAYS DO:
1. **Use workspace-relative paths** - Portable code
2. **Create global Tailwind classes** - Consistent styling
3. **Build Archipelago-native solutions** - No external dependencies
4. **Include security in all containers** - Security first
5. **Use environment variables** - Configurable deployments
6. **Add modules to Cargo.toml** - Workspace coherence
7. **Create reusable components** - DRY principle
8. **Use Podman via our client** - Consistent interface
9. **Handle all errors gracefully** - User-friendly messages
10. **Follow the architecture plan** - Consistency
11. **Write tests** - Prevent regressions
12. **Document code** - Help future contributors
13. **Review your own code** - Catch issues early
14. **Run CI checks locally** - Before pushing
15. **Think production first** - Build it right
## Architecture Adherence
@@ -213,59 +549,197 @@
- ✅ Enable hardware attestation
- ✅ Keep protocol-agnostic design
## Code Quality
---
### TypeScript
- ✅ Use strict mode
## 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` if needed
- ✅ Avoid `any` - use `unknown` or proper types
### Rust
- ✅ Use `clippy` for linting
- ✅ Use `rustfmt` for formatting
- ✅ Document public APIs with `///`
- ✅ Use `#[derive(Debug)]` for error 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)
### General
- ✅ Keep functions small and focused
- ✅ Use descriptive variable names
- ✅ Comment complex logic
- ✅ Remove dead code
- ✅ Follow existing code style
### Testing (Production Requirement)
- 🎯 **CRITICAL**: All features must have tests
## Performance
#### 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
### Optimization Rules
- ✅ Use resource limits in all containers
- ✅ Implement caching where appropriate
- ✅ Lazy load components when possible
- ✅ Optimize images and assets
#### 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
- ✅ Log important events
- ✅ Track container resource usage
- ✅ Monitor health checks
- ✅ Alert on failures
### Monitoring & Observability (Production Requirement)
- 📊 **CRITICAL**: Production requires comprehensive monitoring
## Security
#### 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
### Always Implement
- ✅ Image signature verification
- ✅ Secrets encryption
- ✅ AppArmor/SELinux profiles
- ✅ Network isolation
- ✅ Capability dropping
- ✅ Read-only root filesystems
#### 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)
### Never Skip
- ❌ Security policies in manifests
- ❌ Image verification
- ❌ Secrets management
- ❌ Network isolation
- ❌ Resource limits
#### 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, not StartOS. Build it right, build it secure, build it our way.
**Mission**: A production-ready, open-source Bitcoin Node OS that anyone can trust, deploy, and contribute to.