# Architectural Approach

This document captures the architectural approach for project development in the AIOS-Public system.

## Container Architecture

### Layered Approach
- Base containers provide foundational tools and libraries
- Specialized containers extend base functionality for specific use cases
- Each layer adds specific capabilities while maintaining consistency

### Naming Convention
- Use `RCEO-AIOS-Public-Tools-` prefix consistently
- Include descriptive suffixes indicating container purpose
- Follow pattern: `RCEO-AIOS-Public-Tools-[domain]-[type]`

### Security Patterns
- Minimize root usage during build and runtime
- Implement non-root users for all runtime operations
- Use UID/GID mapping for proper file permissions across environments
- Detect host user IDs automatically through file system inspection

### Operational Patterns
- Create thin wrapper scripts that handle environment setup
- Use consistent patterns for user ID detection and mapping
- Maintain same operational workflow across all containers
- Provide clear documentation in README files

### Organization Principles
- Separate COO mode (operational tasks) from CTO mode (R&D tasks) containers
- Create individual directories per container type
- Maintain disciplined file organization to prevent technical debt
- Keep repository root clean with project-specific files in subdirectories

## Documentation Requirements
- Each container must have comprehensive README
- Include usage examples and environment setup instructions
- Document security and permission handling
- Provide clear container mapping and purpose

## Implementation Workflow
1. Start with architectural design document
2. Create detailed implementation plan
3. Develop following established patterns
4. Test with sample data/usage
5. Document for end users
6. Commit with conventional commit messages