Files/ComputerAssignments/CA2/code/pc/docs/structure.md

## 1. Current Architecture (As‑Is)

The project currently contains **two overlapping architectures**:

### Active/Live Architecture (Works)
- **Entry point**: `cmd/airmouse-server/main.go`
- **UI Layer**: `ui/` package – Fyne‑based desktop GUI.
- **Application/Control Layer**: `control/` package – mouse controller, AI smoothers, predictors, gesture detection.
- **Protocol Layer**: `protocol/` package – TCP, WebSocket, UDP, Bluetooth, USB servers. Contains `ProtocolServer` that coordinates all protocols and the `device.Manager`.
- **Device Management**: `device/` package (not fully provided, but referenced) manages device states and persistence.
- **Configuration & Utils**: `config/`, `utils/`, `auth/` packages.

### Duplicate/Stub Architecture (Not Used)
- **Domain Layer**: `domain/` package – entities (`entity/`), service interfaces (`service/`), repository interfaces (`repository/`).
- **Infrastructure Layer**: `infra/` package – repository implementations (`repository/`), WebSocket hub (`websocket/`), HTTP router (`http/`), DTOs (`dto/`).
- **This layer is **not wired into `main.go`** and has many stubs/no‑ops.

Additionally, there are **ignored / experimental files** (`//go:build ignore`) like particle filter, duplicate mouse implementations, and a duplicate protocol server.

---

## 2. Recommended Clean Architecture

We will follow a **clean, layered architecture** with clear separation of concerns. I recommend **adopting the DDD‑style layer** (domain, application, infrastructure) **instead of** the current `protocol`/`control` approach, but **only if** you are willing to refactor. For most practical purposes, the existing `protocol`/`control` layer is simpler and already working. 

**I recommend the following structure** (which merges the best of both worlds):

```
airmouse-go/
├── cmd/
│   └── airmouse-server/          # Main entry point
├── internal/
│   ├── app/                      # Application orchestration
│   │   ├── server.go             # Creates ProtocolServer, UI, services
│   │   └── lifecycle.go          # Start/stop hooks
│   ├── domain/                   # Core business logic (entities, value objects)
│   │   ├── entity/               # Device, Client, Gesture, MouseProfile, Statistics
│   │   ├── repository/           # Interfaces for persistence/retrieval
│   │   └── service/              # Interfaces for use cases (MouseService, GestureService, ConnectionService)
│   ├── application/              # Implementation of services (use cases)
│   │   ├── mouse/
│   │   │   └── service.go        # Implements MouseService interface
│   │   ├── gesture/
│   │   │   └── service.go        # Implements GestureService (with recognizer)
│   │   └── connection/
│   │       └── service.go        # Implements ConnectionService
│   ├── infrastructure/           # External dependencies (repositories, protocol adapters)
│   │   ├── protocol/             # All protocol servers (TCP, WebSocket, UDP, Bluetooth, USB)
│   │   │   ├── tcp/
│   │   │   ├── websocket/
│   │   │   ├── udp/
│   │   │   ├── bluetooth/
│   │   │   ├── usb/
│   │   │   └── protocol.go       # ProtocolServer (orchestrates all)
│   │   ├── mouse/                # Platform‑specific mouse control (CoreGraphics, WinAPI, uinput)
│   │   │   ├── mouse.go          # MouseController interface
│   │   │   ├── darwin.go
│   │   │   ├── windows.go
│   │   │   └── linux.go
│   │   ├── repository/           # Concrete repository implementations (in‑memory, file, DB)
│   │   │   ├── client_repo.go
│   │   │   ├── gesture_repo.go
│   │   │   └── mouse_repo.go
│   │   ├── config/               # Configuration loader/saver
│   │   ├── auth/                 # Authentication (token validation)
│   │   ├── device/               # Device manager (could be merged with client repo)
│   │   └── utils/                # Helpers (ID generation, logging, IP, crypto)
│   ├── ui/                       # Fyne‑based GUI
│   │   ├── app.go                # Main window, tabs
│   │   ├── dashboard.go
│   │   ├── devices.go
│   │   ├── network.go
│   │   ├── gestures.go
│   │   ├── proximity.go
│   │   ├── analytics.go
│   │   ├── settings.go
│   │   ├── logs.go
│   │   ├── protocol_guide.go
│   │   ├── statusbar.go
│   │   ├── glass_card.go
│   │   ├── helpers.go
│   │   └── ... (other UI components)
│   └── pkg/                      # Shared libraries (if any)
│       └── ...
└── go.mod
```

### Key Architectural Principles:
- **Dependency Inversion**: High‑level modules (UI, application services) depend on **interfaces** (domain/service, domain/repository), not on concrete implementations.
- **Separation of Concerns**:
  - **UI**: Only deals with presentation and user input. It calls application services.
  - **Application Services**: Orchestrate use cases, call repositories and infrastructure adapters.
  - **Domain**: Contains business rules, entities, and value objects (no external dependencies).
  - **Infrastructure**: Implements repositories, protocol servers, mouse control, etc.
- **Single Responsibility**: Each package has a clear purpose and minimal overlap.

---

## 3. Component Interactions (How They Talk to Each Other)

```
+------------------+          +---------------------------+
|   UI (fyne)      | -------> | Application Services      |
|   (ui/*)         |          | (mouse, gesture, connect) |
+------------------+          +-------------+-------------+
                                          |
                                          v
                              +---------------------------+
                              | Domain Entities & Repos   |
                              | (domain/entity, repo)     |
                              +-------------+-------------+
                                          |
                                          v
+------------------+          +---------------------------+
| Protocol Server  | <------> | Repository Implementations|
| (infra/protocol) |          | (infra/repository)        |
+------------------+          +---------------------------+
                                          |
                                          v
                              +---------------------------+
                              | External Systems          |
                              | (OS mouse, network, etc.) |
                              +---------------------------+
```

- **UI** calls services (e.g., `mouseService.Move()`, `connectionService.ListClients()`).
- **Services** use **repositories** to read/write data (clients, gestures, statistics) and call **infrastructure adapters** (e.g., `protocolServer.Broadcast()`, `mouseRepo.Move()`).
- **Protocol Servers** handle raw network connections, decode messages, and call back into the application (e.g., on new client, on mouse move, on gesture). They are **infrastructure** and should not contain business logic.

---

## 4. Which Files to Keep, Delete, or Complete

Based on the current state, here is a concrete action plan:

### ✅ **Keep (Active, working)**
- `cmd/airmouse-server/main.go`
- `ui/` (all `.go` files) – they already call the active services (but you may refactor them to call the new application services later).
- `control/` (all active files: `mouse.go`, `movement_predictor.go`, `pause.go`, plus platform‑specific `*_darwin.go`, `*_linux.go`, `*_windows.go`). Keep these for now if you stick with the old architecture. If you refactor, you can replace them with `infrastructure/mouse/`.
- `protocol/` (all active `*.go` except the ignored `server.go`). Keep `protocol.go`, `message.go`, and sub‑packages (tcp, websocket, udp, bluetooth, usb).
- `device/` – keep (used by protocol servers).
- `auth/` – keep.
- `config/` – keep.
- `utils/` – keep.
- `personalization/` – keep (if used).

### ❌ **Delete / Archive (Duplicates, stubs, ignore)**
- All `//go:build ignore` files:
  - `control/mouse_darwin.go`
  - `protocol/server.go`
  - `particlefilter/` (entire folder) – unless you plan to use it; then you could move it to `infrastructure/gesture/recognizer`.
  - `predictive/test.go` – rename to `kalman2d_test.go` if needed, but it's not integrated.
  - `control/predictor.go` (duplicate of `movement_predictor.go`).
- The **entire DDD‑style layer** (`domain/`, `infra/` except for `infra/mouse` and `infra/repository` if you decide to use them) – **if you are not going to refactor**. If you *are* going to refactor, then you should **complete** and **integrate** them, not delete.

### 🔧 **Complete (if you choose to adopt the new architecture)**
- `domain/entity/` – define all entities (already done, but ensure they match the active ones).
- `domain/repository/` – interfaces (already defined).
- `domain/service/` – interfaces (already defined).
- `infra/repository/` – implement all methods (already done for client and gesture; mouse repo needs real OS integration).
- `infra/websocket/` – if used, integrate with protocol; but I'd rather keep the existing `protocol/websocket`.
- `infra/http/` – if you want a separate HTTP server for health/metrics, it's fine.

---

## 5. Fully Completed File Structure (After Cleanup)

Here is the **final file tree** you should aim for (with no duplicates, all necessary files present and functional):

```
airmouse-go/
├── cmd/
│   └── airmouse-server/
│       └── main.go                        # Initializes app, starts UI, protocol, services
├── internal/
│   ├── app/
│   │   ├── app.go                         # Application bootstrap, dependency injection
│   │   └── lifecycle.go                   # Start/stop hooks (optional)
│   ├── ui/                                # All UI files (no changes needed)
│   │   ├── about.go
│   │   ├── analytics.go
│   │   ├── app.go                         # Main window, tabs, menu
│   │   ├── connection.go                  # Quality widget
│   │   ├── dashboard.go
│   │   ├── devices.go
│   │   ├── gestures.go
│   │   ├── glass_card.go
│   │   ├── helpers.go
│   │   ├── icons.go
│   │   ├── logs.go
│   │   ├── network.go
│   │   ├── pairing.go
│   │   ├── premium_dashboard.go
│   │   ├── premium_theme.go
│   │   ├── protocol_guide.go
│   │   ├── proximity.go
│   │   ├── settings.go
│   │   ├── shortcuts.go
│   │   ├── speedchart.go
│   │   ├── statusbar.go
│   │   └── themes.go
│   ├── domain/                            # Core business entities and repository/service interfaces
│   │   ├── entity/
│   │   │   ├── client.go
│   │   │   ├── device.go                  # (if not already in device package)
│   │   │   ├── gesture.go
│   │   │   ├── mouse.go
│   │   │   └── statistics.go
│   │   ├── repository/
│   │   │   ├── client_repository.go       # Interface
│   │   │   ├── gesture_repository.go      # Interface
│   │   │   └── mouse_repository.go        # Interface
│   │   └── service/
│   │       ├── connection_service.go      # Interface
│   │       ├── gesture_service.go         # Interface
│   │       └── mouse_service.go           # Interface
│   ├── application/                       # Implementations of services (use cases)
│   │   ├── mouse/
│   │   │   └── service.go                 # MouseService impl (using repos and mouse controller)
│   │   ├── gesture/
│   │   │   ├── service.go                 # GestureService impl (with recognizer)
│   │   │   └── recognizer.go              # (optional) internal recognizer
│   │   └── connection/
│   │       └── service.go                 # ConnectionService impl (using client repo)
│   ├── infrastructure/                    # External adapters
│   │   ├── protocol/                      # All protocol servers (keep current)
│   │   │   ├── tcp/
│   │   │   ├── websocket/
│   │   │   ├── udp/
│   │   │   ├── bluetooth/
│   │   │   ├── usb/
│   │   │   └── protocol.go                # ProtocolServer (orchestrates all, calls services?)
│   │   ├── mouse/                         # Platform‑specific mouse control
│   │   │   ├── mouse.go                   # Interface and common logic
│   │   │   ├── darwin.go
│   │   │   ├── windows.go
│   │   │   └── linux.go
│   │   ├── repository/                    # Repository implementations
│   │   │   ├── client_repository_impl.go
│   │   │   ├── gesture_repository_impl.go
│   │   │   └── mouse_repository_impl.go   # Uses mouse controller from infra/mouse
│   │   ├── config/                        # Configuration (keep)
│   │   ├── auth/                          # Auth (keep)
│   │   ├── device/                        # Device manager (could be replaced by client repo)
│   │   └── utils/                         # Helpers (keep)
│   └── pkg/                               # (optional) shared libraries
│       └── ...
├── go.mod
└── go.sum
```

---

## 6. Recommended Migration Path

1. **First, stabilise the current working version** – fix the critical bugs (WebSocket error propagation, data races, welcome message) so that the app connects reliably.
2. **Decide which architecture to keep** – either keep the simple `protocol`/`control` approach or adopt the clean DDD architecture.
3. **If you adopt the DDD architecture**:
   - Move all protocol servers to `infrastructure/protocol/` and make them implement a `Broadcaster` interface.
   - Inject `ConnectionService` and `MouseService` into the protocol handlers.
   - Replace direct calls to `device.Manager` with calls to `ConnectionService` and `ClientRepository`.
   - Refactor the UI to use the new services (this is a bigger effort).
4. **Delete all duplicate/ignored files** to reduce confusion.
5. **Write comprehensive unit and integration tests** for the critical paths.

---

## 7. Summary

The **cleanest, most maintainable structure** is one where:
- UI depends only on **application services**.
- Services depend on **repository interfaces** and **infrastructure adapters**.
- Repositories and protocol servers are **pluggable** and **testable**.
- There are **no duplicate** implementations and **no ignored files** in the main build.

I have provided the full file layout and the reasoning. If you need more detail on any specific file (e.g., the exact implementation of `mouse_repository_impl.go` that calls the OS APIs), I can provide that too. Let me know which part you want to tackle first.