355 lines
9.9 KiB
Markdown
355 lines
9.9 KiB
Markdown
# HelmView Project Structure
|
|
|
|
```
|
|
helmview/
|
|
│
|
|
├── backend/ # FastAPI Backend
|
|
│ ├── main.py # Main application file
|
|
│ ├── requirements.txt # Python dependencies
|
|
│ ├── Dockerfile # Backend Docker image
|
|
│ └── .dockerignore # Docker build exclusions
|
|
│
|
|
├── frontend/ # React Frontend
|
|
│ ├── src/
|
|
│ │ ├── components/ # Reusable React components
|
|
│ │ │ ├── ResourceCard.jsx # Resource display card
|
|
│ │ │ ├── ResourceCard.css
|
|
│ │ │ ├── YamlEditor.jsx # Monaco YAML editor
|
|
│ │ │ ├── YamlEditor.css
|
|
│ │ │ ├── UploadSection.jsx # Chart upload modal
|
|
│ │ │ ├── UploadSection.css
|
|
│ │ │ ├── RenderSection.jsx # Chart render modal
|
|
│ │ │ ├── RenderSection.css
|
|
│ │ │ ├── ExportModal.jsx # Chart export modal
|
|
│ │ │ └── ExportModal.css
|
|
│ │ │
|
|
│ │ ├── pages/ # Page components
|
|
│ │ │ ├── ProjectDashboard.jsx # Projects list page
|
|
│ │ │ ├── ProjectDashboard.css
|
|
│ │ │ ├── RenderView.jsx # Resource view page
|
|
│ │ │ └── RenderView.css
|
|
│ │ │
|
|
│ │ ├── api.js # API client (Axios)
|
|
│ │ ├── App.jsx # Root component
|
|
│ │ ├── App.css # Global styles
|
|
│ │ ├── main.jsx # Entry point
|
|
│ │ └── index.css # Base styles
|
|
│ │
|
|
│ ├── public/ # Static assets
|
|
│ ├── index.html # HTML template
|
|
│ ├── package.json # Node dependencies
|
|
│ ├── vite.config.js # Vite configuration
|
|
│ ├── Dockerfile # Development Docker image
|
|
│ ├── Dockerfile.prod # Production Docker image
|
|
│ ├── nginx.conf # Nginx config for production
|
|
│ └── .dockerignore # Docker build exclusions
|
|
│
|
|
├── docs/ # Documentation (future)
|
|
│
|
|
├── tests/ # Tests (future)
|
|
│ ├── backend/ # Backend tests
|
|
│ └── frontend/ # Frontend tests
|
|
│
|
|
├── .gitignore # Git exclusions
|
|
├── .env.example # Environment variables template
|
|
├── docker-compose.yml # Development orchestration
|
|
├── docker-compose.prod.yml # Production orchestration
|
|
│
|
|
├── README.md # Main documentation
|
|
├── QUICKSTART.md # Quick start guide
|
|
├── CONTRIBUTING.md # Contribution guidelines
|
|
├── SECURITY.md # Security policy
|
|
├── CHANGELOG.md # Version history
|
|
├── LICENSE # MIT License
|
|
└── PROJECT_STRUCTURE.md # This file
|
|
|
|
```
|
|
|
|
## File Descriptions
|
|
|
|
### Backend (`/backend`)
|
|
|
|
#### `main.py`
|
|
The core FastAPI application containing:
|
|
- **Models**: Pydantic models for request/response validation
|
|
- **Storage**: In-memory project database
|
|
- **Helper Functions**:
|
|
- `get_project_path()` - Project directory management
|
|
- `safe_extract_archive()` - Secure chart extraction
|
|
- `run_helm_command()` - Async Helm execution
|
|
- `parse_kubernetes_resources()` - YAML parsing
|
|
- `update_chart_version()` - Semver version bumping
|
|
- **API Endpoints**:
|
|
- Project CRUD operations
|
|
- Chart upload and extraction
|
|
- Helm rendering with options
|
|
- Resource updates
|
|
- Chart export and download
|
|
- Schema retrieval for autocomplete
|
|
|
|
#### `requirements.txt`
|
|
Python dependencies:
|
|
- `fastapi` - Web framework
|
|
- `uvicorn` - ASGI server
|
|
- `pyyaml` - YAML processing
|
|
- `aiofiles` - Async file operations
|
|
- `kubernetes` - K8s Python client
|
|
- `python-multipart` - File upload support
|
|
- `jsonpatch` - JSON patching
|
|
|
|
#### `Dockerfile`
|
|
Multi-stage Docker build:
|
|
1. Install system dependencies
|
|
2. Install Helm 3
|
|
3. Install Python dependencies
|
|
4. Copy application code
|
|
5. Configure runtime
|
|
|
|
### Frontend (`/frontend`)
|
|
|
|
#### Components
|
|
|
|
**ResourceCard.jsx**
|
|
- Displays individual Kubernetes resources
|
|
- Expandable card interface
|
|
- Tabs for Summary and YAML views
|
|
- Integrates YamlEditor component
|
|
- Handles resource updates
|
|
|
|
**YamlEditor.jsx**
|
|
- Monaco Editor integration
|
|
- Kubernetes autocomplete
|
|
- Real-time YAML validation
|
|
- Schema-based suggestions
|
|
- Format and save functionality
|
|
- Kind-specific completions
|
|
|
|
**UploadSection.jsx**
|
|
- Drag-and-drop file upload
|
|
- File validation
|
|
- Progress indication
|
|
- Error handling
|
|
|
|
**RenderSection.jsx**
|
|
- Helm render options form
|
|
- Values override editor
|
|
- Lint output display
|
|
- Error reporting
|
|
|
|
**ExportModal.jsx**
|
|
- Export process management
|
|
- Validation status display
|
|
- Download functionality
|
|
- Error details
|
|
|
|
#### Pages
|
|
|
|
**ProjectDashboard.jsx**
|
|
- List all projects
|
|
- Create new projects
|
|
- Delete projects
|
|
- Navigate to project view
|
|
|
|
**RenderView.jsx**
|
|
- Main resource view
|
|
- Advanced filtering
|
|
- Resource grid layout
|
|
- Stats display
|
|
- Modals orchestration
|
|
|
|
#### Configuration
|
|
|
|
**vite.config.js**
|
|
- Dev server configuration
|
|
- Port settings (5173)
|
|
- Hot module replacement
|
|
- Build optimizations
|
|
|
|
**nginx.conf**
|
|
- Production web server config
|
|
- Gzip compression
|
|
- Security headers
|
|
- API proxy configuration
|
|
- Static asset caching
|
|
|
|
### Docker Configuration
|
|
|
|
#### `docker-compose.yml` (Development)
|
|
- Hot reload enabled
|
|
- Volume mounts for code
|
|
- Port exposure for debugging
|
|
- Health checks
|
|
|
|
#### `docker-compose.prod.yml` (Production)
|
|
- Optimized builds
|
|
- Resource limits
|
|
- Health checks
|
|
- Restart policies
|
|
- Named volumes
|
|
|
|
### Documentation Files
|
|
|
|
#### `README.md`
|
|
- Project overview
|
|
- Feature list
|
|
- Installation instructions
|
|
- Usage guide
|
|
- Architecture details
|
|
- API documentation
|
|
- Troubleshooting
|
|
|
|
#### `QUICKSTART.md`
|
|
- 3-step quick start
|
|
- Sample workflow
|
|
- Common use cases
|
|
- Troubleshooting tips
|
|
|
|
#### `CONTRIBUTING.md`
|
|
- Contribution guidelines
|
|
- Development setup
|
|
- Code style guides
|
|
- Commit conventions
|
|
- PR process
|
|
- Testing requirements
|
|
|
|
#### `SECURITY.md`
|
|
- Security features
|
|
- Vulnerability reporting
|
|
- Best practices
|
|
- Production hardening
|
|
- Compliance notes
|
|
|
|
#### `CHANGELOG.md`
|
|
- Version history
|
|
- Release notes
|
|
- Breaking changes
|
|
- Migration guides
|
|
|
|
## Key Design Decisions
|
|
|
|
### Backend Architecture
|
|
- **Async/await**: All I/O operations are async for performance
|
|
- **In-memory storage**: Simple start, easy to replace with database
|
|
- **Sandboxed execution**: Each project isolated in filesystem
|
|
- **No direct Helm API**: Uses CLI for maximum compatibility
|
|
|
|
### Frontend Architecture
|
|
- **Functional components**: Modern React with hooks
|
|
- **No TypeScript**: Per requirements, uses JavaScript
|
|
- **Component composition**: Small, focused components
|
|
- **CSS modules approach**: Separate CSS per component
|
|
- **Monaco Editor**: Industry-standard editor with LSP support
|
|
|
|
### Security Architecture
|
|
- **Defense in depth**: Multiple layers of validation
|
|
- **Principle of least privilege**: Minimal permissions
|
|
- **Input validation**: All inputs validated
|
|
- **Safe defaults**: Secure by default configuration
|
|
|
|
### Scalability Considerations
|
|
- **Stateless backend**: Easy horizontal scaling
|
|
- **Async operations**: High concurrency support
|
|
- **Docker containers**: Easy deployment and scaling
|
|
- **Database-ready**: Structure supports easy DB integration
|
|
|
|
## Development Workflow
|
|
|
|
### Local Development
|
|
1. Start backend: `uvicorn main:app --reload`
|
|
2. Start frontend: `npm run dev`
|
|
3. Make changes (hot reload active)
|
|
4. Test locally
|
|
5. Commit and push
|
|
|
|
### Docker Development
|
|
1. Start: `docker-compose up`
|
|
2. Make changes (hot reload via volumes)
|
|
3. Test in containers
|
|
4. Rebuild if needed: `docker-compose up --build`
|
|
|
|
### Production Build
|
|
1. Build images: `docker-compose -f docker-compose.prod.yml build`
|
|
2. Test locally: `docker-compose -f docker-compose.prod.yml up`
|
|
3. Deploy to production environment
|
|
4. Monitor health checks
|
|
|
|
## Extension Points
|
|
|
|
### Adding New Features
|
|
|
|
**New Backend Endpoint**
|
|
1. Add route in `main.py`
|
|
2. Add Pydantic model if needed
|
|
3. Implement handler function
|
|
4. Add API client method in `frontend/src/api.js`
|
|
5. Update documentation
|
|
|
|
**New Frontend Component**
|
|
1. Create component file in `src/components/`
|
|
2. Create corresponding CSS file
|
|
3. Import in parent component
|
|
4. Add props and state management
|
|
5. Test in isolation
|
|
|
|
**New Validation Rule**
|
|
1. Add to `validateYaml()` in `YamlEditor.jsx`
|
|
2. Add backend validation in `main.py`
|
|
3. Update error messages
|
|
4. Add tests
|
|
|
|
**Database Integration**
|
|
1. Add SQLAlchemy models
|
|
2. Add Alembic migrations
|
|
3. Replace in-memory `projects_db`
|
|
4. Update all CRUD operations
|
|
5. Add connection pooling
|
|
6. Update docker-compose with database service
|
|
|
|
## Performance Considerations
|
|
|
|
### Backend
|
|
- Async I/O for non-blocking operations
|
|
- Command timeouts prevent hanging
|
|
- Temporary file cleanup
|
|
- Efficient YAML parsing
|
|
|
|
### Frontend
|
|
- Code splitting (Vite handles this)
|
|
- Lazy loading of Monaco Editor
|
|
- Debounced filter inputs
|
|
- Virtual scrolling for large lists (future)
|
|
|
|
### Docker
|
|
- Multi-stage builds reduce image size
|
|
- Layer caching optimizes builds
|
|
- Resource limits prevent exhaustion
|
|
- Health checks ensure availability
|
|
|
|
## Testing Strategy
|
|
|
|
### Backend Tests (Future)
|
|
- Unit tests for helper functions
|
|
- Integration tests for API endpoints
|
|
- Security tests for validation
|
|
- Performance tests for Helm operations
|
|
|
|
### Frontend Tests (Future)
|
|
- Component unit tests
|
|
- Integration tests for pages
|
|
- E2E tests for critical flows
|
|
- Accessibility tests
|
|
|
|
### Manual Testing Checklist
|
|
- [ ] Upload various chart formats
|
|
- [ ] Render with different options
|
|
- [ ] Edit and save YAML
|
|
- [ ] Export and validate
|
|
- [ ] Filter resources
|
|
- [ ] Error handling
|
|
- [ ] Cross-browser testing
|
|
|
|
---
|
|
|
|
**Last Updated**: January 2026
|
|
**Version**: 1.0.0
|