ProjectsDirective.txt

# Windows Desktop Application - Project Directive

## Core Architecture

Build a Windows desktop application using **Wails** (Go-based) as the native launcher and packager.

### Technology Stack
- **Go (Wails)**: Native launcher, packager, and compilation ONLY
- **Modern JavaScript**: All frontend UI and user interactions
- **Python 3**: All application backend logic

### Role Definitions

**Go/Wails Layer:**
- Acts ONLY as a native launcher and packager
- Provides boilerplate window startup code
- Launches Python backend as subprocess/sidecar
- Facilitates communication bridge between JS and Python
- Do NOT place any application logic in Go
- Keep Go code minimal and boilerplate only

**Frontend (Modern JavaScript):**
- Runs in Wails' WebView
- Owns ALL UI rendering, state management, and user interactions
- Communicates with Python backend via JSON over HTTP or WebSocket
- Modern JavaScript only - no TypeScript, no frameworks unless explicitly approved
- Handles presentation layer exclusively

**Backend (Python 3):**
- All application logic must be written in Python 3
- Runs as a sidecar process started by Wails
- Handles:
  - Windows filesystem access
  - Windows registry access
  - Business logic and data processing
  - All system-level operations
- No UI logic in Python

## Architecture Rules

**Strict Separation:**
- NO OS or registry access from JavaScript
- NO UI logic in Python
- NO application logic in Go
- Communication must be request/response with clear JSON schemas
- Treat Python as the system authority
- Treat JavaScript as presentation only
- Treat Go as the packaging/launcher only

**Communication:**
- JavaScript ↔ Python: JSON over HTTP or WebSocket
- Go facilitates but does not process application data
- Clear, documented JSON schemas for all endpoints

## Project Structure

```
/src-ui         → Modern JavaScript UI files
/backend        → Python 3 application
/src-go         → Wails config + boilerplate Go only
```

## Code Quality Standards

**All Code:**
- Must be thoroughly commented
- Comments required throughout, not just at file start
- Major blocks and functions must have human-readable descriptions
- Explain WHAT the code does, not just HOW

**Python 3 Guidelines:**

*Modularity:*
- Use modules to separate distinct duties (e.g., registry access, filesystem operations, business logic)
- Do NOT over-abstract or create deep module hierarchies
- Avoid premature generalization or "reusable frameworks"
- Prefer a small number of clearly named modules over many fine-grained ones
- Functions should be grouped by responsibility, not by technical pattern

*Structure Rules:*
- Each module must have a clear, single purpose
- If logic is only used once and does not clarify responsibility, keep it inline
- Favor readability and traceability over extensibility
- Keep codebase simple and easy to follow for Python beginners to intermediate developers

**JavaScript Guidelines:**
- Modern JavaScript syntax and features
- Clear function and variable naming
- Commented logic blocks
- Modular file structure based on UI components/features

## Development Workflow

**Stage-Based Development:**
We build apps in stages, not one big push.

**Example Progression:**
1. **Stage 1**: Build boilerplate just enough to launch a binary window
   - Compile and name: `WinpyThemr_LaunchTest.exe`
   - Test that window launches successfully
   - **STOP and await further instructions**

2. **Stage 2**: (Example) Add Python backend communication
   - Implement basic IPC between Go/JS/Python
   - Compile and test communication works
   - **STOP and await further instructions**

**Process for Each Stage:**
1. Receive stage instructions
2. Confirm build goals and deliverables for this stage
3. Complete the work
4. Confirm completion and summarize what was built
5. Developer reviews and chooses to build/test or provide new instructions
6. Only proceed to next stage after explicit approval

## Build Output Goal

Produce a native Windows `.exe` that:
- Embeds the WebView UI (JavaScript)
- Runs the Python 3 backend locally
- Packages all dependencies
- Runs as a standalone application

## Framework Policy

**Strict Rule:**
- Avoid introducing additional frameworks or languages unless strictly required
- If a new framework/language is needed, YOU MUST ASK FIRST and explain why
- Prefer simple, explicit IPC over framework-specific abstractions
- Default to vanilla implementations when possible

## Summary

This is a **three-layer** application:
1. **Go (Wails)**: Fast compilation, native packaging, boilerplate launcher
2. **JavaScript**: Modern frontend, all UI/UX
3. **Python 3**: All business logic, system access, data processing

Each layer has a single, clear responsibility. Keep it simple, keep it separated, keep it documented.