Enterprise Grade GUI Framework with Dockable Widgets as first class Citizens
A software stack for building Enterprise GUI applications featuring a frontend-backend architecture featuring core services out of the box and a visual designer for creating complex, dockable UIs.
There are two principle qualities of desktop enterprise applications that set them apart from web technology based applications. One is the need for complex, resizable, and dockable UIs that can accommodate multiple tools and views simultaneously; the other is threading and performance considerations that arise from the need to handle intensive computations, data processing, and real-time updates without blocking the user interface.
Citizen addresses these needs by providing a robust framework that combines a high-performance Rust backend with a flexible PySide6 frontend. Citizen has tremendous versatility for future evolution, as the Rust backend can be paired with other frontends such as egui or webassembly (WASM) in the future.
This project is in early development and not recommended for production use yet. It is probably good for initial internal projects or tooling. APIs may change without notice.
| Approach | Description | Best For |
|---|---|---|
| Python Framework | Import Citizen classes directly into your PySide6 app | Code-first, LLM-assisted development, full control |
| Visual Designer | Use the DSL + live preview designer to generate code | Rapid prototyping, visual iteration, complex layouts |
Both approaches produce the same dockable widget layouts. The Python API works seamlessly with a software engineer employing LLMs and AI coding assistants, while the visual designer excels at human-driven layout iteration.
Use Citizen as a standalone Python library without the designer. Import the classes directly for a clean, code-first approach to building dockable UIs:
from citizen import App, FileBrowser, Editor, Logger, Terminal
app = App("My IDE", theme="Tokyo Night")
app.dock(FileBrowser("files"), "left", label="Project")
app.dock(Editor("editor"), "center", label="Code")
app.dock(Logger("output"), "bottom", label="Output")
app.dock(Terminal("term"), "bottom", label="Terminal")
app.run()All QtAds complexity is abstracted away. See examples/python/simple_ide/ for a complete working example.
Citizen includes a parallel code - visual designer, something that I call a "Visual Surface Designer" that allows developers to see live previews of their layouts as they code, with two-way synchronization between the code and the preview. Code will update the layout, and layout changes will update the code. This significantly speeds up the development cycle and reduces the cognitive load on developers.
Auto Code Update
Here is an example of updating the visual designer blocks, while the code automatically updates to reflect the changes. Note that citizen designers uses zones as a coarse grid layout for the dockable widgets, making it easy to create complex layouts quickly.
Citizen-Widget Manipulation
One of the challenges with complex UIs is managing the layout of multiple dockable widgets. Citizen's visual designer makes it easy to insert, move, and resize widgets within the grid layout. Here is an example of inserting a new widget into the layout:
Code Widget Manipulation
Similarly, widgets can be manipulated directly in the code, with the visual layout updating in real-time to reflect the changes. Here is an example of moving a widget by updating its zone in the code:
The QPortal crate within Citizen is a mini-framework that provides the core backend services that every desktop application needs, so you can focus on your domain logic instead of reinventing the wheel.
Out of the box services include:
- System information display
- Version/banner information
- Configuration management
- User preferences
- Command history
- Logging
The Architecture of QPortal can be summarized as follows:
┌─────────────────────────────────────────────────────────┐
│ Frontend (PySide6 / Qt / egui / WASM) │
│ - Beautiful UI │
│ - User interactions │
└───────────────────────────┬─────────────────────────────┘
│ JSON-RPC over TCP
│ (or direct call for egui)
┌───────────────────────────┴─────────────────────────────┐
│ ServiceRegistry │
│ ├─ PlatformService (system info, logging) │
│ ├─ ApplicationService (config, state, history) │
│ └─ YourDomainService (app-specific logic) │
└─────────────────────────────────────────────────────────┘
- Rust 1.85+
- Python 3.10+
- PySide6 and PySide6QtAds
pip install PySide6 PySide6QtAdsThe Markdown Editor showcase demonstrates the full Citizen stack: Rust backend, PySide6 frontend, live preview, file browser, terminal, and advanced docking.
git clone [email protected]:saturn777/citizen.git
cd citizen
cargo run --bin markdown-editor-showcaseThis bash script starts the visual designer application:
./run.shFirst run builds everything automatically. Subsequent runs are instant.
The examples/ directory contains reference projects organized by workflow:
examples/
├── showcase/ # Full-featured demos
│ └── markdown-editor/ # ⭐ Flagship demo (Rust + Python)
├── dsl/ # Designer workflow (.cz → generated code)
│ ├── getting_started/ # Starter template
│ └── kicad/ # KiCAD-style project
└── python/ # Pure Python (no designer)
└── simple_ide/
Showcase - Complete applications demonstrating the full Citizen stack:
cargo run --bin markdown-editor-showcaseSee examples/showcase/markdown-editor/README.md for full documentation.
DSL Projects - Use the designer to edit .cz files, then build (F6) to generate Python code.
Python Projects - Import citizen classes directly without the designer:
cd examples/python/simple_ide
python app.pyContributions are welcome! Please see CONTRIBUTING.md for guidelines.
This project is licensed under the GPL-3.0 License - see the LICENSE file for details.