dvirlabs/helmview
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
helmview/PROJECT_STRUCTURE.md
dvirlabs bcb87093fa First commit
2026-01-19 00:31:27 +02:00

9.9 KiB
Raw Blame History

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