Add architecture documentation and Pyxis parity plan

[brothercorvo]

Summary

• add docs/architecture.md describing the firmware runtime architecture, startup flow, transport layers, UI stack, persistence, and event loop
• include docs/plans/pyxis-parity-plan.md outlining the product and UI parity roadmap for Pyxis on T-Deck hardware
• keep the change docs-only so the current implementation remains untouched

Notes

• the architecture doc is based on the current embedded firmware composition in src/main.cpp and the transport/UI/audio libraries under lib/
• the parity plan frames Meshtastic-style standalone UX parity as a product-level target, not a protocol port

Testing

• not run (docs-only change)

[greptile-apps]

Greptile Summary

This docs-only PR adds two new documentation files with no code changes:

• docs/architecture.md — A detailed architecture overview of the Pyxis firmware covering the composition root (src/main.cpp), staged startup sequence, four transport adapters (TCP, LoRa, AutoInterface, BLE), LXMF messaging/propagation, LVGL-based UI architecture, LXST voice call pipeline, storage mechanisms (NVS + SPIFFS), the cooperative event loop model, concurrency approach, and diagnostics. Verified against source code — the documentation is highly accurate.
• docs/plans/pyxis-parity-plan.md — A 12-phase product roadmap to bring Pyxis to UX-level parity with Meshtastic's standalone UI on T-Deck hardware, while preserving Reticulum/LXMF/LXST native strengths. Includes architecture recommendations, a PR-by-PR backlog, testing strategy, risk mitigations, and AI agent working instructions.

Minor finding:

• The mermaid flowchart in architecture.md lists only 6 of 9 actual LVGL screens (omitting announces, QR, and propagation nodes), though the detailed text section correctly enumerates all nine.

Confidence Score: 5/5

• This is a docs-only PR with no code changes — safe to merge with zero runtime risk.
• Both files are pure documentation (markdown). No code, configuration, or build files are modified. The architecture documentation was verified against the actual source code and found to be highly accurate. The parity plan correctly references existing codebase structures.
• No files require special attention. Both are documentation-only additions.

Important Files Changed

Filename	Overview
docs/architecture.md	Comprehensive architecture documentation that accurately describes the firmware's composition root, startup sequence, transport layers, UI stack, persistence, and event loop. One minor inconsistency: the mermaid flowchart omits 3 of 9 LVGL screens that the detailed text section correctly enumerates.
docs/plans/pyxis-parity-plan.md	Detailed parity roadmap mapping Meshtastic standalone UX concepts to Reticulum/LXMF/LXST equivalents. Includes 13 phased deliverables, a PR-by-PR backlog, testing strategy, risk mitigations, and working instructions for AI agents. Accurately references existing codebase state.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["docs/architecture.md"] --> B["Firmware Architecture Overview"]
    B --> B1["Composition Root & Startup"]
    B --> B2["Transport Adapters"]
    B --> B3["LXMF Messaging & Propagation"]
    B --> B4["LVGL UI Stack"]
    B --> B5["LXST Voice Pipeline"]
    B --> B6["Storage & Event Loop"]

    C["docs/plans/pyxis-parity-plan.md"] --> D["Parity Roadmap"]
    D --> D1["Phase 0-1: Shell Foundation"]
    D --> D2["Phase 2-3: Setup Wizard & Dashboard"]
    D --> D3["Phase 4-6: Peers & Networks"]
    D --> D4["Phase 7-8: Chat & Map"]
    D --> D5["Phase 9-12: Tools, Settings & Polish"]

    B -.->|"informs"| D

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: docs/architecture.md
Line: 43-44

Comment:
**Flowchart omits three screens**

The mermaid diagram lists LVGL screens as "conversations, chat, compose, status, settings, calls" but the actual codebase (and the detailed text at lines 316-324 of this same file) includes three additional screens: `AnnounceListScreen`, `QRScreen`, and `PropagationNodesScreen`. Consider updating the diagram to include all nine screens for consistency:

```suggestion
    H --> I["LVGL screens
    conversations, chat, compose, announces, QR, status, settings, propagation nodes, calls"]
```

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: 498c3e3}

[greptile-apps]

Flowchart omits three screens

The mermaid diagram lists LVGL screens as "conversations, chat, compose, status, settings, calls" but the actual codebase (and the detailed text at lines 316-324 of this same file) includes three additional screens: AnnounceListScreen, QRScreen, and PropagationNodesScreen. Consider updating the diagram to include all nine screens for consistency:

Suggested change

	H --> I["LVGL screens
	conversations, chat, compose, status, settings, calls"]
	H --> I["LVGL screens
	conversations, chat, compose, announces, QR, status, settings, propagation nodes, calls"]

Prompt To Fix With AI

This is a comment left during a code review.
Path: docs/architecture.md
Line: 43-44

Comment:
**Flowchart omits three screens**

The mermaid diagram lists LVGL screens as "conversations, chat, compose, status, settings, calls" but the actual codebase (and the detailed text at lines 316-324 of this same file) includes three additional screens: `AnnounceListScreen`, `QRScreen`, and `PropagationNodesScreen`. Consider updating the diagram to include all nine screens for consistency:

```suggestion
    H --> I["LVGL screens
    conversations, chat, compose, announces, QR, status, settings, propagation nodes, calls"]
```

How can I resolve this? If you propose a fix, please make it concise.