Improve README Structure, Add Architecture Diagram and API Documentation #8
Description
Description:
The current README.md for Pinicker provides a great functional overview. However, since the project involves a split architecture (Python Backend + Flutter/Mobile Client), the documentation needs to be more structured to help contributors set up both environments without confusion.
Proposed Enhancements:
- Architecture Visualization:
- Add a flow diagram showing the interaction between Pinterest API
↔️ Python Backend↔️ Mobile App↔️ WhatsApp. This helps developers understand how the SQLite database prevents duplicates.
- Detailed API Specs:
- Document the internal endpoint (e.g.,
GET /check-new-stickers) that the mobile app uses to communicate with the Flask server. - Include expected JSON response formats.
- Visual "How it Works" Section:
- Add a section for "App Screenshots" or "UI Mockups" to show what the "Add to WhatsApp" button looks like.
- Enhanced Setup Guide:
- Split the installation guide into two clear sections: Backend Setup and Mobile Setup.
- Add a `.env.example template for Pinterest API keys and Board IDs.
- Troubleshooting & Requirements:
- Explicitly mention the WhatsApp 3-sticker minimum requirement in a "Warning" or "Note" callout box.
- Add information about network configuration (e.g., ensuring the phone and server are on the same Wi-Fi).
Why this is needed?
- Cross-stack development: Since this project uses both Python and Flutter, clear boundaries in the documentation are essential.
- Onboarding: New contributors can quickly identify which part (Backend or App) they want to work on.
Tasks for Contributors:
- Add a Mermaid.js diagram for the data flow.
- Format the "Future Enhancements" into a cleaner Roadmap.
- Add a "Prerequisites" section (Python 3.x, Flutter SDK, Pinterest Dev Account).
- Use GitHub Markdown alerts (
> [!NOTE]) for important WhatsApp limitations.
I will love to work on this issue and Submit a PR regarding the same.
Labels: SWOC SWOC'26 good first issue documentation