{"id":28102180,"url":"https://github.com/moxer-mmh/tweeza","last_synced_at":"2025-05-13T19:34:34.948Z","repository":{"id":282631551,"uuid":"947797603","full_name":"moxer-mmh/Tweeza","owner":"moxer-mmh","description":"Tweeza is a donation and resource sharing platform designed to connect donors, organizations, and beneficiaries in Algeria. By leveraging cutting-edge technology, Tweeza aims to combat food waste, optimize resource allocation, and improve humanitarian aid distribution ","archived":false,"fork":false,"pushed_at":"2025-04-16T22:50:37.000Z","size":372,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-17T11:29:42.565Z","etag":null,"topics":["docker","fastapi","jwt","leaflet","lucide-react","nextjs","oauth2","react","shadcn-ui","sqlalchemy","sqlite","tailwindcss","volunteering"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moxer-mmh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-13T09:10:58.000Z","updated_at":"2025-04-17T11:20:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"6fe17436-c69c-4819-8cc3-964012a0be15","html_url":"https://github.com/moxer-mmh/Tweeza","commit_stats":null,"previous_names":["moxer-mmh/tweeza"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moxer-mmh%2FTweeza","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moxer-mmh%2FTweeza/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moxer-mmh%2FTweeza/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moxer-mmh%2FTweeza/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moxer-mmh","download_url":"https://codeload.github.com/moxer-mmh/Tweeza/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254013197,"owners_count":21999374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","fastapi","jwt","leaflet","lucide-react","nextjs","oauth2","react","shadcn-ui","sqlalchemy","sqlite","tailwindcss","volunteering"],"created_at":"2025-05-13T19:33:14.340Z","updated_at":"2025-05-13T19:34:34.921Z","avatar_url":"https://github.com/moxer-mmh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tweeza\n\n**Empowering Community Solidarity \u0026 Volunteerism**\n\nTweeza is a donation and resource sharing platform designed to connect donors, organizations, and beneficiaries in Algeria. By leveraging cutting-edge technology, Tweeza aims to combat food waste, optimize resource allocation, and improve humanitarian aid distribution—empowering community solidarity and volunteerism.\n\nThis repository contains the complete source code for both the backend and frontend components developed for the Djezzy Code Fest hackathon.\n\n---\n\n## Table of Contents\n\n- [Tweeza](#tweeza)\n  - [Table of Contents](#table-of-contents)\n  - [Overview](#overview)\n  - [Architecture](#architecture)\n    - [Technical Documentation](#technical-documentation)\n    - [Backend Architecture](#backend-architecture)\n    - [Frontend Architecture](#frontend-architecture)\n  - [Features](#features)\n  - [Technologies](#technologies)\n  - [Installation](#installation)\n    - [Backend Setup](#backend-setup)\n    - [Frontend Setup](#frontend-setup)\n    - [Docker](#docker)\n  - [Usage](#usage)\n  - [Testing](#testing)\n    - [Backend Testing](#backend-testing)\n  - [Contributing](#contributing)\n  - [License](#license)\n\n---\n\n## Overview\n\nTweeza is a comprehensive platform that:\n\n* **Tracks Donations:** Securely handles user registration, authentication (JWT, OAuth, and two-factor authentication), and donation management.\n* **Manages Resources:** Facilitates the creation and tracking of resource requests, contributions, and allocation optimization.\n* **Coordinates Volunteers:** Supports volunteer registration and management, event creation, and real-time notifications.\n* **Optimizes Distribution:** Implements smart resource allocation algorithms to prioritize urgent needs and minimize waste.\n\nThe platform is tailored to Algeria's unique context, with localization for Arabic, French, and English, and optimization for areas with limited connectivity.\n\n---\n\n## Architecture\n\n### Technical Documentation\n\nCheck : [Technical Documentation](https://github.com/moxer-mmh/Tweeza/blob/main/backend/docs/DOCUMENTATION.md)\n\n### Backend Architecture\n\nThe backend is built with FastAPI and SQLAlchemy, following a layered architecture:\n\n```\nClient Layer → API Layer → Service Layer → Data Access Layer → Database Layer\n```\n\nKey components:\n\n* **FastAPI Application:** High-performance API server.\n* **SQLAlchemy ORM:** For database operations.\n* **SQLite Database:** Used during development (configurable to PostgreSQL for production).\n* **JWT Authentication \u0026 OAuth Integration:** Securing endpoints and enabling social logins.\n* **Comprehensive Testing:** 85% code coverage including API, service, and model tests.\n\nA detailed sequence diagram and ER diagram are provided in the documentation.\n\n### Frontend Architecture\n\nThe frontend is developed using Next.js and React with a focus on interactivity and accessibility:\n\n* **Next.js (App Router):** Provides SSR and file-based routing.\n* **React Functional Components:** Leveraging Hooks for state management.\n* **Leaflet.js:** For interactive mapping with dynamic markers based on content type.\n* **Tailwind CSS:** For utility-first responsive styling.\n* **Lucide React:** For iconography.\n\nComponents include:\n\n* **AuthTabs:** For login/registration navigation.\n* **Interactive Map:** Displays emergencies, assistance, and events with category-based marker colors.\n* **Card Components:** EventCard, EmergencyCard, AssistanceCard to display various content.\n* **Dashboard \u0026 Volunteer Pages:** Centralized views for main functionality and volunteer registration.\n\n---\n\n## Features\n\n* **User \u0026 Organization Management:** Registration, authentication, profile management, and role-based permissions.\n* **Event Management:** Creation and discovery of events, including location-based searches.\n* **Resource Management:** Creation of resource requests and tracking of contributions.\n* **Notification System:** Email, in-app, and SMS notifications.\n\n---\n\n## Technologies\n\n* **Backend:** FastAPI, SQLAlchemy, SQLite/PostgreSQL, JWT, OAuth, Docker\n* **Frontend:** Next.js, React, Leaflet.js, Tailwind CSS, Lucide React\n\n---\n\n## Installation\n\n### Backend Setup\n\n1. **Clone the Repository \u0026 Navigate to Backend Directory:**\n\n   ```bash\n   git clone https://github.com/moxer-mmh/Tweeza.git\n   cd Tweeza/backend\n   ```\n2. **Create a Virtual Environment and Install Dependencies:**\n\n   ```bash\n   python -m venv venv\n   source venv/bin/activate  # Windows: venv\\Scripts\\activate\n   pip install -r requirements.txt\n   ```\n3. **Configure Environment Variables:**\n\n   ```bash\n   cp .env.example .env\n   # Edit .env with your configuration values (SECRET_KEY, OAuth credentials, etc.)\n   ```\n4. **Run the Development Server:**\n\n   ```bash\n   uvicorn main:app --reload\n   ```\n\n   The API documentation is available at [http://localhost:8000/docs](http://localhost:8000/docs).\n\n### Frontend Setup\n\n1. **Navigate to the Frontend Directory:**\n\n   ```bash\n   cd ../frontend\n   ```\n2. **Install Dependencies:**\n\n   ```bash\n   npm install\n   ```\n3. **Run the Development Server:**\n\n   ```bash\n   npm run dev\n   ```\n\n   The application will be accessible at [http://localhost:3000](http://localhost:3000/).\n\n### Docker\n\n   ```\n   docker-compose up -d\n   ```\n\n---\n\n## Usage\n\n* **API Endpoints:**\n\n  The backend exposes endpoints for authentication, user, organization, event, resource, and notification management. Refer to the API documentation section in the backend docs for details.\n* **Interactive Dashboard:**\n\n  The frontend dashboard integrates a dynamic map with card-based displays for emergencies, assistance, and events. Navigate through tabs to filter content and access individual resource pages.\n* **Volunteer \u0026 Donation Flows:**\n\n  Users can register as volunteers or donors via dedicated forms. The multi-step forms ensure data is collected accurately for each user type.\n\n---\n\n## Testing\n\n### Backend Testing\n\n* **Run All Tests:**\n  ```bash\n  python run_tests.py\n  ```\n* **HTML Coverage Report:**\n  ```bash\n  python run_tests.py --html\n  ```\n* **Run a Specific Test Module:**\n  ```bash\n  python run_tests.py --path tests/test_api/test_auth.py\n  ```\n\n---\n\n## Contributing\n\nContributions are welcome! Please follow these steps in [CONTRIBUTING.md](CONTRIBUTING.md).\n\n---\n\n## License\n\nThis project is licensed under the [MIT License](/LICENSE).\n\n---\n\n*This repository was developed as part of the Djezzy Code Fest hackathon to empower community-driven initiatives in Algeria, promoting efficient donation tracking, resource management, and volunteer coordination.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoxer-mmh%2Ftweeza","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoxer-mmh%2Ftweeza","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoxer-mmh%2Ftweeza/lists"}