# 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