docs: add comprehensive developer documentation

[HusseinAdeiza]

Summary

Adds extensive documentation to address the current lack of contributor guidelines and centralized documentation for the arc-commerce project.

What's Included

This PR adds 1,807 lines of comprehensive documentation across 3 major files:

1. CONTRIBUTING.md (488 lines)

Complete contribution guidelines covering:

• Code of conduct
• Getting started guide with fork/clone instructions
• Development workflow and branch naming conventions
• Pull request process with template
• Code style guidelines (TypeScript, React, API routes)
• Commit message conventions (Conventional Commits)
• Testing guidelines with examples
• Documentation standards
• Issue reporting templates
• Security reporting procedures

2. docs/ARCHITECTURE.md (592 lines)

Complete system architecture documentation covering:

• System overview and credit purchase flow
• Technology stack details
• Architecture diagrams for credit purchase system
• Core components (User Dashboard, Admin Dashboard, Purchase API)
• Admin dashboard architecture and access control
• Circle Wallets integration (user and admin wallets)
• Database schema with RLS policies
• Webhook system for transaction notifications
• Security model and deployment considerations

3. docs/TROUBLESHOOTING.md (727 lines)

Comprehensive troubleshooting guide covering:

• Installation issues: Node version compatibility (v20 vs v22), npm vulnerabilities, Docker setup
• API key setup: Circle API keys, Entity Secrets, admin wallet creation
• Database issues: Supabase connection, migrations, RLS policies, email rate limits
• Webhook issues: ngrok setup, webhook delivery, signature verification
• Credit purchase errors: Purchase failures, stuck transactions, credit not added
• Admin dashboard issues: Access problems, empty data display
• Runtime errors: Wallet creation, USDC transfers, authentication
• Deployment issues: Environment variables, build failures
• FAQ: 10+ common questions with detailed answers

Problem Solved

Before this PR:

• ❌ No CONTRIBUTING.md - unclear how to contribute
• ❌ No docs/ folder - no centralized documentation
• ❌ No architecture documentation - credit purchase flow unclear
• ❌ No troubleshooting guide - common issues undocumented

After this PR:

• ✅ Clear contribution guidelines
• ✅ Comprehensive architecture documentation for credit purchase system
• ✅ Detailed troubleshooting for 40+ common issues
• ✅ ~1,800 lines of professional documentation

Benefits

• Faster onboarding: New contributors can get started in minutes
• Reduced support burden: Self-service troubleshooting for common issues
• Better understanding: Clear credit purchase flow and admin dashboard architecture
• Professional standards: Follows best practices for enterprise open source

Testing

✅ All markdown files validated
✅ Internal links verified
✅ Code examples tested
✅ Installation instructions followed on fresh environment

Screenshots

Documentation Structure

arc-commerce/ ├── CONTRIBUTING.md (488 lines) ├── README.md (existing) └── docs/ (new folder) ├── ARCHITECTURE.md (592 lines) └── TROUBLESHOOTING.md (727 lines)

Total: 1,807 lines of documentation

Notes

• This is my second contribution to Circle's repositories (first: arc-escrow)
• All documentation follows professional standards
• Ready for immediate review and merge
• Can adapt based on maintainer feedback

---

Thank you for considering this contribution! I'm excited to continue helping improve the developer experience for Circle's Arc blockchain ecosystem and making USDC payment integration more accessible to developers.