272 lines
9.2 KiB
Plaintext
272 lines
9.2 KiB
Plaintext
# 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.
|