Skip to content

Commit e207b46

Browse files
claudeclaude
committed
docs: Add ADRs and research for CLI parsing and MQTT commands
Add architectural decision records and research documentation: - ADR-004: Decision to keep yargs for CLI parsing - Evaluated yargs vs commander.js vs CLI action commands - Decided to stick with yargs and use MQTT for actions instead - Avoids fragile CLI parsing and breaking meeting links - ADR-005: Decision to not bundle embedded MQTT broker - Evaluated bundling Aedes broker in Electron app - Rejected due to still requiring client tools (mosquitto_pub) - Better alternatives exist (HTTP server, external broker) - Research: MQTT Commands Implementation - Comprehensive analysis of adding bidirectional MQTT support - Implementation plan: 4-6 hours, ~60 lines of code, low risk - User setup guide, security considerations, broker recommendations - Enables keyboard shortcuts and home automation integration These documents provide context for future MQTT command implementation.
1 parent d9f2536 commit e207b46

File tree

3 files changed

+638
-0
lines changed

3 files changed

+638
-0
lines changed

‎docs-site/docs/development/adr/004-cli-argument-parsing-library.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# ADR 004: CLI Argument Parsing Library Decision
2+
3+
**Status:** Accepted
4+
**Date:** 2025-11-16
5+
**Deciders:** Development Team
6+
**Related:** MQTT Commands Research
7+
8+
---
9+
10+
## Context
11+
12+
Teams for Linux uses `yargs` for CLI argument parsing. We evaluated whether to:
13+
1. Add CLI-based action commands (`teams-for-linux action toggle-mute`)
14+
2. Migrate to `commander.js` for better subcommand support
15+
3. Keep current `yargs` implementation
16+
17+
### Requirements
18+
- Support 30+ configuration options
19+
- Parse config files and environment variables
20+
- Handle meeting URLs as positional arguments (`teams-for-linux https://teams.microsoft.com/...`)
21+
- Low risk of breaking existing functionality
22+
23+
### Considered Options
24+
25+
**Option A: Add CLI Action Commands with yargs**
26+
- Requires fragile pre-parsing before yargs initialization
27+
- High risk of breaking meeting link flow (critical feature)
28+
- Conflicts with existing URL positional argument handling
29+
- Effort: 14-23 hours
30+
31+
**Option B: Migrate to commander.js**
32+
- Better subcommand support
33+
- Requires reimplementing config file and environment variable parsing
34+
- 30+ options need migration
35+
- Effort: 6-8 hours
36+
- Risk: Medium (regression testing needed)
37+
38+
**Option C: Keep yargs, Use Alternative Command Mechanism**
39+
- MQTT for actions (see MQTT Commands Research)
40+
- HTTP server for actions
41+
- No CLI parsing changes needed
42+
- Effort: 4-6 hours
43+
- Risk: Low (isolated addition)
44+
45+
---
46+
47+
## Decision
48+
49+
**Stick with yargs. Do not add CLI action commands. Use MQTT for action triggers.**
50+
51+
### Rationale
52+
53+
1. **yargs is appropriate for current use case**
54+
- Config-heavy application (30+ options)
55+
- Built-in config file and environment variable support
56+
- No need for subcommands (actions handled via MQTT)
57+
58+
2. **Avoid fragile bypass layer**
59+
- Pre-parsing arguments before yargs creates tight coupling
60+
- High risk of breaking meeting link handling
61+
- Difficult to maintain
62+
63+
3. **Better alternatives exist**
64+
- MQTT commands: Clean architecture, extensible, low risk
65+
- HTTP server: Zero external dependencies for shortcuts
66+
- No need for complex CLI parsing
67+
68+
4. **Future-proofing**
69+
- Can migrate to commander.js during major version bump (v2.0+) if multiple subcommands become necessary
70+
- Current architecture works well for current needs
71+
72+
---
73+
74+
## Consequences
75+
76+
### Positive
77+
- ✅ No risk to existing functionality (meeting links, config options)
78+
- ✅ No migration effort
79+
- ✅ Built-in config/env parsing continues working
80+
- ✅ Users get action commands via MQTT (better UX anyway)
81+
82+
### Negative
83+
- ⚠️ No native CLI subcommands (not needed currently)
84+
- ⚠️ Future subcommand needs require migration or workarounds
85+
86+
### Neutral
87+
- Option to migrate to commander.js remains open for future major versions
88+
- Decision can be revisited if requirements change significantly
89+
90+
---
91+
92+
## References
93+
94+
- [CLI Arguments vs MQTT Comparison](../research/mqtt-commands-implementation.md)
95+
- [yargs Documentation](https://yargs.js.org/)
96+
- [commander.js Documentation](https://github.com/tj/commander.js)

‎docs-site/docs/development/adr/005-embedded-mqtt-broker.md‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
# ADR 005: Embedded MQTT Broker Decision
2+
3+
**Status:** Rejected
4+
**Date:** 2025-11-16
5+
**Deciders:** Development Team
6+
**Related:** [MQTT Commands Research](../research/mqtt-commands-implementation.md)
7+
8+
---
9+
10+
## Context
11+
12+
With MQTT commands implementation planned, we evaluated whether to bundle an embedded MQTT broker (Aedes) in the Electron app to simplify user setup.
13+
14+
### Problem
15+
16+
Users need an MQTT broker to:
17+
1. Receive status updates from Teams
18+
2. Send action commands to Teams
19+
20+
Without a broker, users must:
21+
- Install mosquitto: `sudo apt-get install mosquitto`
22+
- Configure and start the service
23+
- Understand MQTT concepts
24+
25+
### Proposed Solution
26+
27+
Bundle Aedes (JavaScript MQTT broker) in the Electron app:
28+
- Auto-starts when app launches
29+
- Listens on `localhost:1883`
30+
- Zero configuration needed
31+
- Bundle size: +230 KB
32+
- Implementation effort: 6-8 hours
33+
34+
---
35+
36+
## Decision
37+
38+
**Do NOT bundle an embedded MQTT broker.**
39+
40+
---
41+
42+
## Rationale
43+
44+
### 1. Doesn't Solve the Real Problem
45+
46+
**Users still need MQTT client tools** to send commands:
47+
48+
```bash
49+
# Even with embedded broker, users must install:
50+
sudo apt-get install mosquitto-clients
51+
52+
# To run:
53+
mosquitto_pub -h localhost -t teams/command -m '{"action":"toggle-mute"}'
54+
```
55+
56+
**Embedded broker eliminates:**
57+
- Installing mosquitto broker
58+
59+
**Embedded broker does NOT eliminate:**
60+
- Installing mosquitto-clients (for `mosquitto_pub`)
61+
- Creating wrapper scripts
62+
- Understanding MQTT topics
63+
64+
**Conclusion:** Marginal benefit (removes 1 of 3 installation steps)
65+
66+
---
67+
68+
### 2. Wrong Architectural Pattern
69+
70+
**Teams should be a client, not a broker.**
71+
72+
```
73+
❌ Wrong: Each Teams instance runs its own broker
74+
Teams Instance 1 → Aedes broker :1883
75+
Teams Instance 2 → Aedes broker :1884 (port conflict!)
76+
Home Assistant → Mosquitto :1883
77+
→ Fragmented ecosystem
78+
79+
✅ Right: Centralized broker, multiple clients
80+
Mosquitto :1883 (or Home Assistant MQTT add-on)
81+
├─ Teams for Linux (client)
82+
├─ Home Assistant (client)
83+
├─ Node-RED (client)
84+
└─ IoT devices (clients)
85+
→ Unified ecosystem
86+
```
87+
88+
Users with home automation already have MQTT brokers. Creating another broker fragments their setup.
89+
90+
---
91+
92+
### 3. Better Alternatives Exist
93+
94+
**For users wanting keyboard shortcuts with zero dependencies:**
95+
96+
**Option A: HTTP Server**
97+
```bash
98+
# curl is pre-installed on all Linux systems
99+
curl -X POST http://localhost:48765/action/toggle-mute
100+
```
101+
- ✅ No package installation
102+
- ✅ Simpler than MQTT
103+
- ✅ Can serve web UI
104+
105+
**Option B: Named Pipe (FIFO)**
106+
```bash
107+
# echo is built-in
108+
echo '{"action":"toggle-mute"}' > ~/.config/teams-for-linux/commands.fifo
109+
```
110+
- ✅ Zero external dependencies
111+
- ✅ Standard Unix IPC
112+
113+
**For users with home automation:**
114+
- They already have MQTT brokers (Home Assistant, etc.)
115+
- Prefer connecting to existing broker
116+
- Embedded broker adds unnecessary complexity
117+
118+
---
119+
120+
### 4. Implementation Complexity Without Value
121+
122+
| Component | Embedded Broker | External Broker | HTTP Server |
123+
|-----------|----------------|-----------------|-------------|
124+
| Bundle size | +230 KB | 0 KB | 0 KB |
125+
| Implementation | 6-8 hours | 0 hours | 3-4 hours |
126+
| User dependencies | mosquitto-clients | mosquitto + mosquitto-clients | None (curl) |
127+
| Port conflicts | Yes (need handling) | No | Rare |
128+
| Maintenance | Update Aedes | User manages | None |
129+
130+
**Cost/benefit:** Not favorable
131+
132+
---
133+
134+
## Consequences
135+
136+
### Positive
137+
- ✅ Simpler architecture (Teams = client only)
138+
- ✅ No port conflict handling needed
139+
- ✅ No Aedes dependency to maintain
140+
- ✅ Users with existing MQTT get better integration
141+
- ✅ Saved 6-8 hours implementation effort
142+
143+
### Negative
144+
- ⚠️ Users without MQTT must install mosquitto
145+
- ⚠️ Slightly higher barrier to entry for MQTT features
146+
147+
### Mitigations
148+
- Document easy broker setup (apt-get one-liner for most distros)
149+
- Recommend Home Assistant MQTT add-on (one-click install)
150+
- Consider HTTP server for zero-dependency shortcuts (future)
151+
152+
---
153+
154+
## Alternatives Considered
155+
156+
### Alternative 1: HTTP Command Server (Future)
157+
158+
**For users wanting shortcuts without MQTT:**
159+
160+
```javascript
161+
// Serve HTTP endpoint
162+
http://localhost:48765/action/toggle-mute
163+
164+
// User script (no dependencies)
165+
curl -X POST http://localhost:48765/action/toggle-mute
166+
```
167+
168+
**Advantages:**
169+
- ✅ curl is pre-installed
170+
- ✅ Simpler than MQTT for basic use
171+
- ✅ Can add web UI later
172+
173+
**Status:** Consider for future implementation
174+
175+
### Alternative 2: Keep MQTT, Document Broker Setup
176+
177+
**For users with home automation:**
178+
179+
Document connecting to existing brokers:
180+
- Home Assistant MQTT add-on
181+
- Existing mosquitto installation
182+
- Cloud MQTT providers (for advanced users)
183+
184+
**Status:** Accepted (current plan)
185+
186+
---
187+
188+
## User Segments
189+
190+
### Segment 1: Home Automation Users (30%)
191+
- Already have MQTT broker
192+
- Want Teams integration with automations
193+
- **Solution:** Connect to existing broker (documented)
194+
195+
### Segment 2: Keyboard Shortcut Users (50%)
196+
- Want simple system-wide shortcuts
197+
- Don't have MQTT infrastructure
198+
- **Solution:** Install mosquitto (documented) OR HTTP server (future)
199+
200+
### Segment 3: Advanced Users (20%)
201+
- Can set up whatever they need
202+
- **Solution:** Any approach works
203+
204+
---
205+
206+
## References
207+
208+
- [MQTT Commands Implementation Research](../research/mqtt-commands-implementation.md)
209+
- [Aedes MQTT Broker](https://github.com/moscajs/aedes)
210+
- Related: HTTP command server (future consideration)
211+
212+
---
213+
214+
## Review
215+
216+
This decision should be reviewed if:
217+
1. A zero-dependency command mechanism becomes critical requirement
218+
2. MQTT adoption is very low due to broker installation complexity
219+
3. Implementation effort for embedded broker drops significantly (new library, etc.)
220+
221+
For now: **Proceed with MQTT client only + document broker setup.**

0 commit comments

Comments
 (0)