Add a CONTRIBUTING guide and frontend architecture docs covering routes, hooks, and the contract/api layer

[Baskarayelu]

📋 Description

The repo has a large README.md and scattered notes (README_SPLIT_TRANSACTIONS.md, RESPONSIVE_AUDIT_SUMMARY.md, SAVINGS_GOALS_IMPLEMENTATION_SUMMARY.md), but no single CONTRIBUTING guide that explains the frontend architecture: the App Router layout under app/, the shared hooks in lib/hooks / lib/client, the contract read/write layer in lib/contracts, and the test commands in package.json.

Why this matters: this is an active OSS bounty repo with many contributors. A clear architecture + contribution guide reduces duplicate work, wrong-layer changes, and review churn.

🎯 Requirements & Context

Functional requirements

• Add CONTRIBUTING.md documenting: branch naming, the exact test commands (npm run lint, npm run test:coverage, npm run test:unit, npm run test:integration, npm run test:e2e, npm run build), and PR expectations.
• Add docs/architecture.md describing the route map, the lib/contracts + lib/cache read layer, the API routes under app/api, wallet/session, and i18n.
• Document the difference between node --test .cjs suites and the Vitest .ts suites (both run in npm run test:unit).
• Cross-link from README.md.

Context & constraints

• Documentation-only; verify every command actually exists in package.json scripts.
• Keep it concise and skimmable.

🛠️ Suggested Execution

git checkout -b docs/contributing-architecture

• Write CONTRIBUTING.md + docs/architecture.md, verify commands, cross-link.

npm run lint

• Edge cases to cover in docs: where to add a new page vs component vs hook, when to add a cached read, how to add an i18n key in both locales.

Example commit message

docs: add CONTRIBUTING guide and frontend architecture overview

Documents route map, hooks, contract/cache/api layers, i18n, and the
exact verified test commands from package.json.

✅ Acceptance Criteria & Guidelines

Requirement	Target
CONTRIBUTING.md with verified commands	Required
docs/architecture.md route + layer map	Required
node:test vs Vitest distinction documented	Required
README cross-link	Required
Lint clean	Required
Timeframe	96 hours from assignment

💬 Community & Support

Join the RemitWise contributor community on Discord: https://discord.gg/CtQuPZFMA

Comment to claim before starting. 🚀

[bashir1738]

gm i would like to work on this

[Queenode]

Hi Maintainers,

I would like to work on this issue.

I have experience contributing to frontend and Web3 projects, and I understand how valuable accurate documentation is for onboarding contributors and reducing review overhead. Before making any documentation changes, I will thoroughly review the repository structure and verify all commands, paths, and workflows directly from the codebase.

Implementation Plan

1. Review the existing project structure, including:

   • app/ route hierarchy and App Router layout
   • lib/hooks
   • lib/client
   • lib/contracts
   • lib/cache
   • app/api
   • wallet/session management
   • i18n implementation

2. Create a comprehensive but concise CONTRIBUTING.md covering:

   • Branch naming conventions
   • Development workflow
   • PR expectations
   • Verified test and quality commands from package.json
   • Guidelines for contributors before opening a PR

3. Create docs/architecture.md documenting:

   • Application route map
   • Frontend architecture layers
   • Contract read/write flow
   • Cache strategy
   • API route organization
   • Wallet and session handling
   • Internationalization workflow

4. Document contributor decision-making guidelines, including:

   • When to create a new page versus a component
   • When to add a custom hook
   • When a cached read should be introduced
   • How to add new translation keys across supported locales

5. Clearly explain the distinction between:

   • Node.js node:test .cjs test suites
   • Vitest .ts test suites
   • How both are executed through npm run test:unit

6. Update README.md with clear links to:

   • CONTRIBUTING.md
   • docs/architecture.md

7. Verify documentation accuracy by running the project's linting and validation commands before submitting the PR.

Deliverables

• CONTRIBUTING.md
• docs/architecture.md
• README cross-links
• Verified and documented test commands
• Clear architecture overview for new contributors

Why I'm a Good Fit

• Experience working with React, Next.js, TypeScript, and Web3 applications.
• Strong focus on developer experience and maintainable documentation.
• Comfortable analyzing large codebases and translating implementation details into contributor-friendly guides.
• Attention to accuracy and consistency when documenting project architecture.

I will keep the documentation concise, skimmable, and aligned with the actual implementation to ensure it remains useful for both new and existing contributors.

Thank you for your consideration.

[jaynomyaro]

Hi! I’m a full-stack developer with a strong blockchain background. I’d love to handle this issue and can deliver a clean, reliable solution. Kindly assign it to me.

[jaynomyaro]

Hi! I’m a full-stack developer with a strong blockchain background. I’d love to handle this issue and can deliver a clean, reliable solution. Kindly assign it to me.

[lifewithbigdamz]

I would like to work on this issue as a full stack developer and I solve complex web 3 problems

[grantfox-oss]

🦊 GrantFox — @bashir1738 has been assigned to this issue!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #482)
2. Your PR will be reviewed by the Remitwise-Org maintainers

Good luck! Track your progress on GrantFox.