1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
# Architecture Overview (Detailed)
## Scope and goals
This document is a map of the launcher at the module level. It focuses on boundaries, interactions, and the main data flows so you can find the right files quickly before making changes.
## Layered model
1. **UI + ViewModels** (`launcher/ui/`, `launcher/viewmodels/`)
- Qt Widgets screens, dialogs, and widgets.
- ViewModels expose state and actions for the UI.
2. **Core/domain** (`launcher/`, `launcher/minecraft/`, `launcher/java/`)
- Models, settings, instance management, launch logic.
- No UI dependencies.
3. **Task system** (`launcher/tasks/`)
- Long-running or async work (downloads, extraction, indexing).
- Emits progress and completion signals.
4. **Networking** (`launcher/net/`)
- HTTP requests and API adapters.
- Used by tasks and core services.
5. **Mod platform integrations** (`launcher/modplatform/`)
- Mod platform APIs and install flows.
- Orchestrated by tasks and core logic.
## Where to start in code
- `launcher/main.cpp`: entry point, application wiring.
- `launcher/Application.cpp`: lifecycle, settings, instance loading.
- `launcher/ui/MainWindow.cpp`: main Qt Widgets UI.
- `launcher/LaunchController.cpp`: launch orchestration (Task).
- `launcher/tasks/`: long-running work and progress reporting.
## Component catalog
| Component | Path | Responsibility | Depends on |
| --- | --- | --- | --- |
| UI | `launcher/ui/` | Render UI, collect input, start actions | Core, Tasks |
| ViewModels | `launcher/viewmodels/` | Present core data to the UI | Core |
| Core/Domain | `launcher/`, `launcher/minecraft/` | Domain models and launch logic | Storage, Tasks, Net |
| Tasks | `launcher/tasks/` | Async work and progress reporting | Net, Storage |
| Net | `launcher/net/` | HTTP/APIs, downloads | External APIs |
| Modplatform | `launcher/modplatform/` | Mod platform workflows | Net, Tasks |
| Java | `launcher/java/` | Java discovery/metadata | Storage |
## High-level control flow
### Startup
1. `main.cpp` initializes the `Application` singleton.
2. `Application` loads settings, accounts, and instances.
3. UI is created (`MainWindow`), which binds to application state.
### Launch flow (typical)
```mermaid
sequenceDiagram
participant U as User
participant UI as UI (Qt Widgets)
participant C as Core
participant T as LaunchController/Tasks
participant N as Net
participant S as Storage
U->>UI: Click "Launch"
UI->>C: Build LaunchRequest
C->>T: Start LaunchController (Task)
T->>N: Fetch assets/metadata
N-->>T: Responses
T->>S: Write/update files
T-->>UI: progress + completed
```
## Data flow diagram
```mermaid
graph TD
UI[UI (Qt Widgets)] -->|signals/slots| ViewModels
ViewModels --> Core
UI --> Tasks
Core --> Storage[(Disk: settings/instances/cache)]
Tasks --> Net
Tasks --> Storage
Net --> ExternalAPIs[(Remote APIs)]
Modplatform --> Net
```
## Module boundaries and rules
- UI must not perform long-running work or file/network I/O.
- Core and tasks must not depend on Qt Widgets.
- ViewModels should stay free of UI widget dependencies.
- Use `Task` for work that blocks or takes more than a few milliseconds.
- Keep dependencies flowing "downward": `ui` -> `core` -> `data` (storage/net).
## Internal contracts (templates)
Use these templates when documenting module interfaces in feature-specific docs.
### Task contract
```cpp
class ExampleTask : public Task {
Q_OBJECT
protected:
void executeTask() override {
setStatus("Working...");
setProgress(0);
// Work goes here...
if (failed) {
emitFailed("reason");
return;
}
emitSucceeded();
}
};
```
### Service contract (UI to Core)
```cpp
struct LaunchRequest {
QString instanceId;
QString javaPath;
QMap<QString, QString> env;
};
struct LaunchResult {
bool ok;
QString errorCode;
QString message;
};
class ILaunchService : public QObject {
Q_OBJECT
public:
virtual Task::Ptr launch(const LaunchRequest& req) = 0;
signals:
void progress(int percent);
void finished(const LaunchResult& result);
};
```
## API contract table (example format)
| Contract | Producer | Consumer | Request | Response/Event | Errors | Notes |
| --- | --- | --- | --- | --- | --- | --- |
| LaunchTask | Core | Task System | `LaunchRequest` | `progress`, `finished` | `failed(code,msg)` | Async |
| DownloadAsset | Task | Net | URL + headers | bytes + status | network errors | Retry policy |
## How to update this document
1. Identify the feature or module (`launcher/<module>/`).
2. List the public interfaces it exposes (signals, task APIs, service methods).
3. Add or update the relevant diagram(s) and contract table entries.
4. Verify control flow against entry points in `main.cpp`, `Application`, and `MainWindow`.
## Notes
- Diagrams are high-level and may omit file-level details.
- Contracts are templates; validate names and arguments against the current code.
|
