docs: add v1 architecture reference for v2 development - #2
Merged
Conversation
![MostronatorCoder[bot]](https://github.githubassets.com/images/gravatars/gravatar-user-420.png){kind=avatar}
These documents are from Mostro Mobile v1 (Dart/Flutter implementation). They serve as REFERENCE for understanding business logic, protocols, and flows. The v2 implementation uses Rust core + flutter_rust_bridge, so code examples must be adapted to Rust for the core logic layer. Included docs: - ARCHITECTURE.md - Overall app architecture - SESSION_AND_KEY_MANAGEMENT.md - BIP-32/39, trade keys, restore (CRITICAL) - NOSTR.md - Nostr protocol, NIP-59 Gift Wrap (CRITICAL) - ORDER_STATUS_HANDLING.md - Order state machine - P2P_CHAT_SYSTEM.md - Encrypted chat, ECDH (CRITICAL) - NWC_ARCHITECTURE.md - Nostr Wallet Connect - ENCRYPTED_IMAGE_MESSAGING_IMPLEMENTATION.md - ChaCha20, Blossom - FCM_IMPLEMENTATION.md - Push notifications - RELAY_SYNC_IMPLEMENTATION.md - Relay management - LOGGING_SYSTEM.md - Logging and export Source: https://github.com/MostroP2P/mobile/tree/main/docs/architecture
Member
|
@coderabbitai review |
Contributor
✅ Actions performedReview triggered.
|
Contributor
WalkthroughAdded a comprehensive v1 reference documentation suite under Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~30 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 11
🧹 Nitpick comments (2)
.specify/v1-reference/NOSTR.md (1)
32-67: Consider adding language specifiers to ASCII diagrams.The architecture diagrams use unlabeled code blocks (also at lines 95, 195, 278). Adding
textorplaintextlanguage specifiers would improve rendering and accessibility.Example enhancement
-``` +```text ┌─────────────────────────────────────────────────────────────┐ │ Mostro Mobile App │🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.specify/v1-reference/NOSTR.md around lines 32 - 67, Add a language specifier (e.g., ```text or ```plaintext) to the unlabeled ASCII diagram code blocks in .specify/v1-reference/NOSTR.md so they render/accessibly as plain text; update each diagram code fence that currently starts with ``` (the Mostro Mobile App/Nostr Network ASCII art and the other diagrams at the other code fences) to use a labeled fence like ```text to improve rendering and accessibility..specify/v1-reference/SESSION_AND_KEY_MANAGEMENT.md (1)
591-608: Consider adding language specifiers to code blocks.Several code blocks throughout this document lack language specifiers (also at lines 655, 788, 814, 1069, 1082). While these appear to be pseudo-code flow diagrams, adding language hints (e.g.,
textorplaintext) would improve readability and syntax highlighting.Example enhancement
-``` +```text 1. Parent Order Release → User completes range order (orderId: "parent-123", keyIndex: 7)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.specify/v1-reference/SESSION_AND_KEY_MANAGEMENT.md around lines 591 - 608, Several fenced code blocks (for example the block starting with "1. Parent Order Release" that references KeyManager.getNextKeyIndex(), NextTrade payload, MostroService._onData(), tradeKey.public, etc.) lack language specifiers; update those triple-backtick fences to include a language hint such as "text" or "plaintext" (and do the same for the other similar blocks mentioned in the review) so the diagrams render with appropriate formatting and consistent syntax highlighting.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.specify/v1-reference/ARCHITECTURE.md:
- Around line 21-68: The markdown has unlabeled fenced code blocks showing the
project tree (starting with the "lib/" directory listing) and other unlabeled
fences noted in the review; update each ``` fence to include an appropriate
language identifier (use ```text for file/directory trees and README-like
listings, and ```dart or ```bash for actual code/commands) so markdownlint rule
MD040 is satisfied; search for the block that begins with "lib/" and the other
unlabeled blocks referenced in the review (lines containing the directory tree,
translation file listings like "intl_en.arb", and any code snippet blocks) and
add the proper language tag to each fence.
In @.specify/v1-reference/ENCRYPTED_IMAGE_MESSAGING_IMPLEMENTATION.md:
- Around line 133-137: Update the "Why ChaCha20-Poly1305?" section to correct
two inaccurate security claims: replace the bullet "Nonce-misuse resistant
design" under the "**Why ChaCha20-Poly1305?**" heading with "Requires strict
nonce uniqueness per key" to reflect RFC 8439, and edit or remove the "Forward
Secrecy" claim (the forward-secrecy bullet at/around line 155) to state that
long-lived shared session keys do NOT provide forward secrecy — either remove
the claim or replace it with a note that forward secrecy requires ephemeral
per-message/session keys (e.g., via DH/ratcheting).
In @.specify/v1-reference/FCM_IMPLEMENTATION.md:
- Around line 16-24: The Encrypted Token Registration section is inconsistent
about current vs future state; update the document by splitting the existing
"Encrypted Token Registration" content into two explicit subsections named
"Current (v1) — Token Registration" and "Target (Phase 5) — Encrypted Token
Registration", move the present plaintext-token behavior (currently described
around lines 108-113 and 350-352) into the Current (v1) subsection, and place
the ChaCha20-Poly1305 / ECDH + HKDF details (ephemeral secp256k1 keypair, salt
"mostro-fcm-v1", info "mostro-token-encryption", 12-byte nonce, token format
`ephemeral_pubkey || nonce || ciphertext`) into the Target (Phase 5) subsection
so readers cannot assume encryption is already active; ensure equivalent updates
are made where the same content appears near lines 16-24 and 91-94.
- Around line 173-202: The fenced ASCII diagram block beginning with the diagram
lines (e.g., "MostroP2P App (Flutter)" / the box diagram) is missing a language
tag; update the opening triple-backticks for that block from ``` to ```text so
the diagram is a fenced code block with language "text" (this will satisfy
MD040).
In @.specify/v1-reference/NOSTR.md:
- Line 102: Two documentation sources specify conflicting BIP44 derivation
paths: one uses "m/44'/1237'/0'/0/trade_index" and the other uses
"m/44'/1237'/38383'/0/N"; pick the authoritative path and make both docs
consistent. Update all occurrences so they match the chosen canonical derivation
(replace either "0'" or "38383'" and normalize the terminal index naming to a
single convention like "trade_index" or "N"), and add a short note in the docs
clarifying the chosen purpose/index semantics and that this is the single source
of truth for key derivation.
In @.specify/v1-reference/NWC_ARCHITECTURE.md:
- Around line 30-31: The NwcConnection validation currently accepts both
"wss://" and "ws://" relay protocols which is unsafe; update the validation
logic in NwcConnection to allow only "wss://" (secure WebSocket) for production,
or if you intend to keep "ws://" for local development, explicitly gate it
behind a dev-only flag and add clear documentation/comments in the NwcConnection
validation and the toUri() round-trip logic that "ws://" is strictly
local-dev-only and not supported in production. Ensure any tests or examples
that used "ws://" are updated to "wss://" and that validation error messages
clearly state that only "wss://" is accepted in production.
In @.specify/v1-reference/README.md:
- Line 92: Update the migration priority list in the Phase 4 entry so the
filename matches the documented file: replace the referenced
ENCRYPTED_IMAGE_MESSAGING.md with ENCRYPTED_IMAGE_MESSAGING_IMPLEMENTATION.md in
the line containing "Phase 4: Chat (P2P_CHAT_SYSTEM.md,
ENCRYPTED_IMAGE_MESSAGING.md)"; ensure the entry preserves the existing
formatting and still references P2P_CHAT_SYSTEM.md alongside the corrected
ENCRYPTED_IMAGE_MESSAGING_IMPLEMENTATION.md.
In @.specify/v1-reference/RELAY_SYNC_IMPLEMENTATION.md:
- Around line 60-84: The markdown contains unlabeled fenced code blocks (the
ASCII flow diagram and the "App Launch → Settings Load → RelaysNotifier Init →
Load Saved Relays → Subscribe to Mostro Events → Wait for NostrService → Begin
Sync" block) which triggers MD040; update those triple-backtick fences to
include the language identifier "text" so they become ```text ... ```, and apply
the same change to the other unlabeled fences referenced around lines 1148-1165
to satisfy markdownlint.
- Around line 885-888: The getter validRelays currently accepts both 'ws://' and
'wss://', which conflicts with the documented secure-only relay policy; change
the filter in validRelays (the List<String> get validRelays { ... } that
iterates over relays) to only accept URLs starting with 'wss://', trim them as
before, and update any nearby comment/docs in RELAY_SYNC_IMPLEMENTATION.md that
referenced accepting 'ws://' to explicitly state that non-secure ws:// is
rejected (also search for other relay-parsing/validation logic in this doc and
the codebase and make the same 'wss://'‑only enforcement consistent).
- Around line 35-36: The docs and implementation disagree about whether user
relays are preserved on instance change; reconcile them by choosing one behavior
and updating both the spec text in RELAY_SYNC_IMPLEMENTATION.md (the "instance
transitions" / "preserved on instance transitions" sections) and the
implementation in updateMostroInstance() so they match: if preserving user
relays, remove the hardcoded userRelays: const [] reset in
updateMostroInstance() and instead merge or retain the existing user relay list
when constructing the new relay state; if resetting, change the docs to state
that user relays are cleared and ensure updateMostroInstance() explicitly resets
them. Reference updateMostroInstance() and the "instance transitions" wording in
RELAY_SYNC_IMPLEMENTATION.md when making the change.
In @.specify/v1-reference/SESSION_AND_KEY_MANAGEMENT.md:
- Line 20: The SESSION_AND_KEY_MANAGEMENT reference contains broken references
to SESSION_RECOVERY_ARCHITECTURE.md — either add the missing
SESSION_RECOVERY_ARCHITECTURE.md to the PR (so the links in
.specify/v1-reference/SESSION_AND_KEY_MANAGEMENT.md point to a local file) or
update every reference to SESSION_RECOVERY_ARCHITECTURE.md in that document to
explicitly point to the v1 source repository (replace the local filename/link
with the external v1 repo URL and a short note that it lives in v1), ensuring
all occurrences (lines referenced in the review) are updated consistently.
---
Nitpick comments:
In @.specify/v1-reference/NOSTR.md:
- Around line 32-67: Add a language specifier (e.g., ```text or ```plaintext) to
the unlabeled ASCII diagram code blocks in .specify/v1-reference/NOSTR.md so
they render/accessibly as plain text; update each diagram code fence that
currently starts with ``` (the Mostro Mobile App/Nostr Network ASCII art and the
other diagrams at the other code fences) to use a labeled fence like ```text to
improve rendering and accessibility.
In @.specify/v1-reference/SESSION_AND_KEY_MANAGEMENT.md:
- Around line 591-608: Several fenced code blocks (for example the block
starting with "1. Parent Order Release" that references
KeyManager.getNextKeyIndex(), NextTrade payload, MostroService._onData(),
tradeKey.public, etc.) lack language specifiers; update those triple-backtick
fences to include a language hint such as "text" or "plaintext" (and do the same
for the other similar blocks mentioned in the review) so the diagrams render
with appropriate formatting and consistent syntax highlighting.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 235ee958-f43f-4fe1-b0cc-7ea924bfd19e
📒 Files selected for processing (11)
.specify/v1-reference/ARCHITECTURE.md.specify/v1-reference/ENCRYPTED_IMAGE_MESSAGING_IMPLEMENTATION.md.specify/v1-reference/FCM_IMPLEMENTATION.md.specify/v1-reference/LOGGING_SYSTEM.md.specify/v1-reference/NOSTR.md.specify/v1-reference/NWC_ARCHITECTURE.md.specify/v1-reference/ORDER_STATUS_HANDLING.md.specify/v1-reference/P2P_CHAT_SYSTEM.md.specify/v1-reference/README.md.specify/v1-reference/RELAY_SYNC_IMPLEMENTATION.md.specify/v1-reference/SESSION_AND_KEY_MANAGEMENT.md
added 3 commits
March 23, 2026 10:18
Changes: - ARCHITECTURE.md: Add 'text' language tag to directory tree code blocks - ENCRYPTED_IMAGE_MESSAGING_IMPLEMENTATION.md: - Fix nonce-misuse claim: ChaCha20-Poly1305 requires strict nonce uniqueness - Clarify forward secrecy: long-lived session keys do NOT provide FS - FCM_IMPLEMENTATION.md: - Split token registration into Current (v1) vs Target (Phase 5) sections - Clarify that encryption is NOT yet implemented (Phase 5 future) - Add 'text' tag to ASCII architecture diagram - NOSTR.md: - Fix BIP44 derivation path: m/44'/1237'/38383'/0/N (was incorrect 0') - Align with SESSION_AND_KEY_MANAGEMENT.md as source of truth - NWC_ARCHITECTURE.md: - Add security warning: only wss:// should be used in production - Clarify ws:// is strictly for local development
Changes: - README.md: Fix filename ENCRYPTED_IMAGE_MESSAGING.md → ENCRYPTED_IMAGE_MESSAGING_IMPLEMENTATION.md - RELAY_SYNC_IMPLEMENTATION.md: - Add 'text' tag to ASCII data flow diagram - Fix validRelays to only accept wss:// (security) - Clarify instance transitions: user relays are NOT preserved (complete reset) - SESSION_AND_KEY_MANAGEMENT.md: - Update broken SESSION_RECOVERY_ARCHITECTURE.md links to point to v1 repo - Add 'text' tag to implementation flow diagram - NOSTR.md: - Add 'text' tag to architecture ASCII diagram
- SESSION_AND_KEY_MANAGEMENT.md: Add 'text' tags to flow diagrams - RELAY_SYNC_IMPLEMENTATION.md: Add 'text' tags to sequence diagrams
Member
|
@coderabbitai review |
Contributor
✅ Actions performedReview triggered.
|
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (2)
.specify/v1-reference/FCM_IMPLEMENTATION.md (1)
185-214: Optional: Add language tags to code blocks.Some fenced code blocks are missing language identifiers, triggering markdownlint MD040 warnings.
📝 Suggested refinement
For the ASCII diagram around line 185:
-``` +```text ┌─────────────────┐ │ MostroP2P App │For the Dart code around line 278:
-``` +```dart `@pragma`('vm:entry-point') Future<void> firebaseMessagingBackgroundHandler(RemoteMessage message) async {Also applies to: 278-293
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.specify/v1-reference/FCM_IMPLEMENTATION.md around lines 185 - 214, Add appropriate fenced-code language tags to the two Markdown code blocks: mark the ASCII diagram block (the box diagram starting "MostroP2P App (Flutter)" around the sequence diagram) as ```text and mark the Dart background handler block that defines `@pragma`('vm:entry-point') Future<void> firebaseMessagingBackgroundHandler(RemoteMessage message) async { ... } as ```dart so markdownlint MD040 warnings are resolved; locate the blocks by the ASCII diagram content and the firebaseMessagingBackgroundHandler function signature and update their opening fences accordingly..specify/v1-reference/README.md (1)
50-57: Optional: Add language tags to diagram fences.The ASCII diagram blocks are missing language identifiers, triggering markdownlint MD040 warnings. Consider adding
texttags for consistency.📝 Suggested refinement
-``` +```text ┌─────────────────────────────────────┐ │ Flutter/Dart │ ...Apply the same change to both diagram blocks.
Also applies to: 61-74
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.specify/v1-reference/README.md around lines 50 - 57, The ASCII diagram code fences in the README (the triple-backtick blocks that contain the box diagram with "Flutter/Dart" and the inner "UI + Business Logic + Crypto + Nostr (dart_nostr)" text) are missing language tags and trigger MD040; update each triple-backtick fence that surrounds those ASCII diagrams to include a language tag (e.g., change ``` to ```text) so both diagram blocks (the one with "Flutter/Dart" and the subsequent similar block) use ```text.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In @.specify/v1-reference/FCM_IMPLEMENTATION.md:
- Around line 185-214: Add appropriate fenced-code language tags to the two
Markdown code blocks: mark the ASCII diagram block (the box diagram starting
"MostroP2P App (Flutter)" around the sequence diagram) as ```text and mark the
Dart background handler block that defines `@pragma`('vm:entry-point')
Future<void> firebaseMessagingBackgroundHandler(RemoteMessage message) async {
... } as ```dart so markdownlint MD040 warnings are resolved; locate the blocks
by the ASCII diagram content and the firebaseMessagingBackgroundHandler function
signature and update their opening fences accordingly.
In @.specify/v1-reference/README.md:
- Around line 50-57: The ASCII diagram code fences in the README (the
triple-backtick blocks that contain the box diagram with "Flutter/Dart" and the
inner "UI + Business Logic + Crypto + Nostr (dart_nostr)" text) are missing
language tags and trigger MD040; update each triple-backtick fence that
surrounds those ASCII diagrams to include a language tag (e.g., change ``` to
```text) so both diagram blocks (the one with "Flutter/Dart" and the subsequent
similar block) use ```text.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 715d9f89-2bc0-4cbd-a01b-283a16108529
📒 Files selected for processing (8)
.specify/v1-reference/ARCHITECTURE.md.specify/v1-reference/ENCRYPTED_IMAGE_MESSAGING_IMPLEMENTATION.md.specify/v1-reference/FCM_IMPLEMENTATION.md.specify/v1-reference/NOSTR.md.specify/v1-reference/NWC_ARCHITECTURE.md.specify/v1-reference/README.md.specify/v1-reference/RELAY_SYNC_IMPLEMENTATION.md.specify/v1-reference/SESSION_AND_KEY_MANAGEMENT.md
✅ Files skipped from review due to trivial changes (3)
- .specify/v1-reference/ENCRYPTED_IMAGE_MESSAGING_IMPLEMENTATION.md
- .specify/v1-reference/NOSTR.md
- .specify/v1-reference/NWC_ARCHITECTURE.md
🚧 Files skipped from review as they are similar to previous changes (1)
- .specify/v1-reference/RELAY_SYNC_IMPLEMENTATION.md
grunch
added a commit
that referenced
this pull request
Apr 2, 2026
orders.rs — Fix #7: store_trade_key_index before publish Moved store_trade_key_index(&order_id, trade_index) from before the action dispatch to inside the publish-success else branch. A publish failure no longer leaves a stale key mapping. orders.rs — Fix #5: ln_address logged in plain text Replaced ln_address={:?} (which printed the actual address) with ln_address=present/none using if ln_address_ref.is_some(). orders.rs — Fix #4: fixed 30-min deadline regardless of activity Replaced the fixed deadline with a last_activity instant that resets on each matching event. The idle timeout is now 30 minutes of inactivity, not 30 minutes of total uptime. add_lightning_invoice_screen.dart — Fix #2: Lightning Address sent with 1-sat amount _isValid now returns false for @ inputs when _resolvedSats is null. _submit also guards against it and surfaces an error instead of falling through to BigInt.one. trade_detail_screen.dart — Fix #3: OrderStatus.pending mapped to TradeStatus.active Added TradeStatus.loading to the enum and made it the default branch in _mapOrderStatus. Unresolved/initial statuses no longer match the active-trade action button sections.
4 tasks
This was referenced Jul 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds architecture documentation from Mostro Mobile v1 as reference for v2 development.
Why?
The v1 docs contain detailed information about:
This knowledge is essential for building v2 with the new Rust core architecture.
What's included
SESSION_AND_KEY_MANAGEMENT.mdNOSTR.mdP2P_CHAT_SYSTEM.mdORDER_STATUS_HANDLING.mdNWC_ARCHITECTURE.mdENCRYPTED_IMAGE_MESSAGING_IMPLEMENTATION.mdFCM_IMPLEMENTATION.mdRELAY_SYNC_IMPLEMENTATION.mdARCHITECTURE.mdLOGGING_SYSTEM.mdImportant Note
See
.specify/v1-reference/README.mdfor the full index and migration guidance.Source
https://github.com/MostroP2P/mobile/tree/main/docs/architecture
Summary by CodeRabbit