Add architecture diagram to docs/

[Mystery-CLI]

Background

FuTuRe is a multi-component application consisting of a React frontend, a Node.js/Express backend, a Stellar Horizon integration layer, a PostgreSQL database, a Redis cache, and a WebSocket notification service. As the platform grows and the team expands, understanding how these components relate to one another — which services call which, what data flows where, and what the trust boundaries are — requires either deep code familiarity or a lengthy verbal explanation from a senior engineer. Neither approach scales. A persistent, visual architecture diagram would serve as the canonical reference for system understanding.

Problem

The current absence of an architecture diagram creates several practical problems:

• Onboarding takes longer. New engineers join the team and spend days piecing together the system's structure from reading code, docker-compose files, and asking colleagues. A diagram would reduce this to minutes.
• Ambiguity during design discussions. When discussing new features or infrastructure changes, teams often disagree about assumptions regarding component relationships, because there is no canonical reference to consult.
• Docs-code drift. Without a maintained diagram, any prose descriptions of the architecture in the README or wikis drift out of date faster than they are noticed.
• Security review difficulty. Understanding trust boundaries, data flows between components, and which components are internet-facing requires reading code and config rather than consulting a visual model.
• Contributor knowledge gaps. Open-source contributors and integration partners do not understand how their code changes affect the broader system without an architectural map.

Proposed Solution

Create docs/architecture.md containing an architecture diagram that covers the complete component topology. The diagram should be authored in a text-based diagram format (Mermaid is recommended, as it renders natively in GitHub Markdown) so that it is version-controlled alongside the code and can be updated via standard PR workflow.

The diagram should show:

1. Frontend — the React SPA, how it is served, and which backend APIs it calls.
2. Backend — the Express server, route groupings, and key middleware layers.
3. Stellar Horizon — the integration point between the backend and the Stellar network.
4. Database — PostgreSQL, which services write to it, and which read from it.
5. Cache — Redis, which services use it, and for what purpose.
6. WebSocket service — how real-time notifications flow from backend to frontend.
7. Authentication layer — where JWT validation occurs and which routes are protected.
8. External services — any third-party APIs (email, push notification providers) and where they connect.

In addition to the diagram, docs/architecture.md should include a short prose description of each component's role, a data flow walkthrough for the most common user journey (sending a payment), and a note on the deployment topology (containerised services, cloud provider if applicable).

Implementation Steps

1. Draft the Mermaid diagram covering all components listed above.
2. Verify the diagram renders correctly in GitHub's Markdown preview.
3. Write the accompanying prose sections for each component.
4. Write the payment flow walkthrough narrative.
5. Link docs/architecture.md from the project README.md and docs/README.md.
6. Add a note in CONTRIBUTING.md stating that significant architectural changes must be reflected with a diagram update in the same PR.

Acceptance Criteria

• docs/architecture.md exists with a rendered diagram and accompanying prose.
• The diagram covers all eight component categories listed above.
• The payment flow walkthrough is accurate and matches the current implementation.
• The document is linked from the README and documentation index.
• The Mermaid syntax renders without errors in GitHub's Markdown viewer.

Notes

The diagram should reflect the current production architecture, not aspirational or planned states. Planned changes can be noted in a separate section labelled "Planned." Keep the diagram at a component level — sequence diagrams for specific flows can be added as separate files if needed.