Developer Guide

Information for developers contributing to flux9s

Architecture

flux9s follows a modified Elm Architecture pattern with async task spawning:

Model

App struct holds all application state in a centralized location.

Update

handle_key() processes events and updates state synchronously.

View

render() displays current state using stateless components.

Async Layer

Spawned tasks + oneshot channels handle I/O operations without blocking the UI.

Project Structure

flux9s/
├── src/
│   ├── cli/          # CLI command parsing
│   ├── config/       # Configuration management
│   ├── kube/         # Kubernetes client wrapper
│   ├── models/       # Generated and custom models
│   ├── trace/        # Resource tracing
│   ├── tui/          # Terminal UI
│   └── watcher/      # Resource watching
├── crds/             # Flux CRD files
├── tests/            # Integration tests
└── docs/             # Documentation

Development Setup

1. Clone the Repository

git clone https://github.com/dgunzy/flux9s.git
cd flux9s

2. Install Dependencies

cargo build

3. Run Tests

make ci

This runs:

  • cargo fmt - Format code
  • cargo clippy - Lint code
  • cargo test - Run tests

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Key Principles

  • Zero-maintenance model updates: Use code generation over manual types
  • Non-blocking operations: Keep UI responsive with async task spawning
  • Graceful degradation: Log errors, don’t crash
  • K9s alignment: Follow K9s conventions for keybindings and UX

License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.

Last modified December 12, 2025: Website and CI fixes (1dd6ede)