docs: add frontend component hierarchy map for dashboard pages

[superstarflayce]

Closes #612

---

Pull Request Template

📋 Description

Add a complete environment variable matrix (docs/ENV_VARIABLE_MATRIX.md) covering every env var consumed across the backend and frontend, with defaults, required flags, and production recommendations. Update README.md and ENV_QUICK_REFERENCE.md to link to the new document.

🔗 Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)
• 📚 Documentation update
• 🔒 Security improvement

---

🔒 SECURITY REVIEW (⭐ MANDATORY FOR SMART CONTRACT CHANGES)

For all smart contract code changes, complete the following checklist.

See docs/SECURITY_CHECKLIST.md for detailed guidance.

Required: Security Checklist Sign-Off

• I have reviewed this PR against the Internal Security Checklist (docs/SECURITY_CHECKLIST.md)

  • Reentrancy: Verified Checks-Effects-Interactions (CEI) pattern
  • Access Control: Confirmed all sensitive functions are protected (onlyOwner, onlyRole(), etc.)
  • Input Validation: Validated all parameters have appropriate bounds checks
  • Unchecked Returns: All external calls have return value checks (require(success, ...))
  • Gas Limits: No unbounded loops or potential DOS vectors

  If any checkbox cannot be verified, explain below:

  N/A — this PR contains only documentation changes. No smart contract code was modified.
  

Slither Static Analysis Results

• Ran Slither locally: slither . --config-file slither.config.json

  • Result: ✅ No High/Medium findings OR 🟡 Documented false positives (see below)

• GitHub Actions Slither workflow passed:

  • 🟢 All High/Medium findings fixed OR
  • 🟡 All false positives documented with FP references

  If this PR has security findings, document them below:

  N/A — documentation-only PR. No contract or runtime code changed.
  

Handling Security Findings

Option A: Fixed in This PR ✅

• Vulnerability identified and resolved
• Test case added to verify fix
• Explain fix below:

  N/A
  

Option B: False Positive 🟡

• Identified as false positive (tool limitation or misleading check)
• Added entry to contracts/.false-positives.md with:
  • Detector rule name
  • Technical reasoning (3+ sentences why it's safe)
  • Evidence (code snippet, test case, or reference)
• Reference number (e.g., FP-001):

  N/A
  

• Inline suppression added to code:

  // slither-disable-next-line <detector-name>
  // Reason: [one-line reason]

Option C: Accepted Risk ⚠️

• Acknowledged as low-priority style issue (naming conventions, etc.)
• Added to Slither exclusions
• Explain below:

  N/A
  

---

📝 Testing

Functional Testing

• Unit tests added/updated for changes
• Integration tests passing
• Manual testing completed and documented below:

  - Verified all variable names, defaults, and required flags against source files:
    backend/src/index.ts, rateLimiter.ts, auth.ts, tracing.ts
  - Cross-checked every .env.example, .env.local.example, .env.production.example
    in both backend/ and frontend/
  - Confirmed links in README.md and ENV_QUICK_REFERENCE.md resolve correctly
  - No runtime code changed; no functional regression possible
  

Security Testing

• For state-changing functions:

  • Reentrancy test (if applicable): Verify re-entry is blocked
  • Access control test: Verify unauthorized access is rejected
  • Boundary test: Verify edge cases are handled

• For external integrations:

  • Return value verification test
  • Failure scenario test

Test Coverage

• All new code paths have test coverage
• Security-critical paths have comprehensive test cases
• Coverage report: N/A — documentation only, no executable code added

---

🚀 Deployment Notes

No deployment steps required. This PR adds a Markdown file and updates two existing Markdown files only.

Mainnet Readiness

• This code is ready for production deployment
• All critical tests pass
• Security review approved
• No temporary debug code
• No TODO comments

Breaking Changes

If this PR introduces breaking changes:

• Migration guide provided
• Deprecation period defined: [timeframe]
• Legacy code deprecated with warnings

---

📊 Automated Scan Results

Slither Analysis

• ✓ Status: N/A — no contract code changed
• 🔴 High/Medium findings: 0
• 🟡 Low/Informational findings: 0
• 🟢 No issues detected: documentation-only PR

Related Documentation

• Security Checklist — Use for code review
• False Positive Process — For non-vulnerabilities
• Slither Configuration — Current scanner settings

---

✅ Reviewer Checklist

For code reviewers (use this to guide your security-focused review):

• PR author completed security checklist ✓
• All findings documented and categorized (fixed/false positive/excluded)
• Inline security comments are clear and justified
• Tests cover security-critical code paths
• No external calls bypass return value checks
• Access control is properly enforced
• State updates follow CEI pattern
• Input validation is comprehensive
• Follow-up actions (if any) tracked in issues

---

📞 Questions or Issues?

• 🤔 Confused about security checklist? → See docs/SECURITY_CHECKLIST.md
• 🔍 Marking finding as false positive? → Follow docs/FALSE_POSITIVE_HANDLING.md
• 🆘 Need security review help? → Tag @security-team in comments

---

📋 Pre-Submit Checklist

Before marking PR as ready for review:

• Description is clear and concise
• All security checklist items checked (✅ or explanation provided)
• All tests passing locally: npm test
• Linter passing: npm run lint
• Slither passing locally OR findings documented: slither . --config-file slither.config.json
• Code follows project style guide
• No merge conflicts
• Commits are clean and well-documented
• Branch is up-to-date with main/develop

---

✅ Ready for Review? Ensure all items above are checked before requesting review.

[superstarflayce]

Summary

This PR adds documentation describing the frontend component hierarchy for the dashboard pages.

Changes

• Added a component hierarchy map for the dashboard.
• Documented the responsibilities of the primary dashboard components.
• Included a high-level overview of transaction flow, validation, and user feedback components.

Why

This documentation makes it easier for contributors to understand the dashboard architecture, locate components, and maintain or extend the frontend.

Closes #612

[drips-wave]

@superstarflayce Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[superstarflayce]

Summary

This PR adds documentation describing the frontend component hierarchy for the dashboard pages.

Changes

• Added a component hierarchy map for the dashboard.
• Documented the responsibilities of the primary dashboard components.
• Included a high-level overview of transaction flow, validation, and user feedback components.

Why

This documentation makes it easier for contributors to understand the dashboard architecture, locate components, and maintain or extend the frontend.

Closes #612