Documentation: System Architecture & Monorepo Flow

[OSEH-svg]

Difficulty: Difficult

NOTE: This is a high-level documentation task requiring full-stack understanding.

Task Description

Create a root-level ARCHITECTURE.md that explains the high-level system flow and the monorepo structure, helping developers understand how the three main pillars (Web, Server, Contract) interact.

Implementation Details

File Path: ARCHITECTURE.md (root)
Content:

• Monorepo Structure: Explain the purpose of /apps/web, /server, and /contract.
• System Flow Diagram: Use a Mermaid diagram to visualize:
  • Frontend (Next.js) -> Backend (Axum).
  • Backend (Axum) -> Database (PostgreSQL).
  • Frontend (Next.js) -> Blockchain (Soroban Contracts).
  • Backend (Axum) -> Blockchain (Stellar SDK).
• Ticketing Flow: Document the "Ticket" metaphor implementation across the stack (how a ticket goes from a Soroban registry to a PostgreSQL transaction).
• Communication Protocol: REST APIs vs. Smart Contract calls.

Acceptance Criteria

• ARCHITECTURE.md contains at least one Mermaid sequence or flow diagram.
• Clear distinction between "On-chain" and "Off-chain" data storage is made.
• Folder responsibilities are accurately described.

When opening your PR, ensure you link this issue. Include: Closes #issue_number.

💡 Questions?
Reach out on Telegram: @divine_oseh

[nice-bills]

@nice-bills has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

I would like to apply to fix this issue I have also gone through the codebase
eta 1 hr

ℹ️ Repo Maintainers: To accept this application, review their application or assign @nice-bills to this issue.

[drips-wave]

Congratulations, @nice-bills! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on March 30, 2026.

🧑‍💻 @nice-bills: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊