🇫🇷 Gestion des Associations Sociales Tunisiennes

Application web complète pour la gestion des associations caritatives en Tunisie

English Version

---

📋 Description

Cette application permet aux associations sociales tunisiennes de gérer efficacement :

• 👥 Les bénéficiaires et leurs familles
• 🎁 La distribution des aides (Couffin Ramadan, Aide scolaire, Vêtements Aïd, etc.)
• 💰 La comptabilité (entrées/sorties financières)
• 📱 Le suivi par QR Code avec preuve photo
• 🔄 La détection automatique des doublons (éviter les distributions multiples)

✨ Fonctionnalités

Gestion des Bénéficiaires

• Enregistrement avec CIN, situation familiale, revenus
• Liaison des conjoints pour la détection des doublons au niveau du foyer
• Historique complet des aides reçues

Distribution des Aides

• Types d'aides préconfigurés (Ramadan, scolaire, Aïd, médical, alimentaire)
• Génération de QR codes uniques par opération
• Scan QR pour distribution rapide
• Preuve photo obligatoire lors de la remise

Gestion Financière

• Suivi des entrées (dons, subventions, cotisations)
• Suivi des dépenses (achats, charges, aides directes)
• Tableau de bord avec statistiques

Détection des Doublons

• Vérification automatique avant distribution
• Prise en compte des périodes (mensuel, annuel, ponctuel)
• Vérification au niveau du foyer (conjoint inclus)

🛠️ Technologies

Backend

• Node.js + Express.js
• PostgreSQL (base de données)
• JWT (authentification)
• Multer (upload photos)
• QRCode (génération)

Frontend

• React 18 + Vite
• TailwindCSS (styles)
• React Router DOM (navigation)
• Axios (requêtes API)
• html5-qrcode (scan QR)

📁 Structure du Projet

Gestion-Associations/
├── backend/
│   ├── config/          # Configuration base de données
│   ├── controllers/     # Logique métier
│   │   ├── authController.js
│   │   ├── beneficiaireController.js
│   │   ├── financeController.js
│   │   └── operationController.js
│   ├── middleware/      # Authentification JWT
│   ├── routes/          # Routes API
│   ├── uploads/         # Photos uploadées
│   ├── schema.sql       # Schéma de la base de données
│   └── server.js        # Point d'entrée
├── frontend/
│   └── src/
│       ├── components/  # Composants réutilisables
│       ├── context/     # Context React (Auth)
│       ├── pages/       # Pages principales
│       │   ├── Dashboard.jsx
│       │   ├── Beneficiaires.jsx
│       │   ├── Operations.jsx
│       │   ├── Finance.jsx
│       │   └── Login.jsx
│       └── services/    # Services API
└── scripts de démarrage (.bat)

🚀 Installation

Prérequis

• Node.js >= 18
• PostgreSQL >= 14
• npm ou yarn

1. Cloner le projet

git clone https://github.com/votre-username/Gestion-Associations.git
cd Gestion-Associations

2. Configurer la base de données

# Créer la base de données PostgreSQL
psql -U postgres
CREATE DATABASE gestion_associations;
\q

# Exécuter le schéma SQL
psql -U postgres -d gestion_associations -f backend/schema.sql

3. Configurer l'environnement

# backend/.env
DATABASE_URL=postgresql://postgres:votre_mot_de_passe@localhost:5432/gestion_associations
JWT_SECRET=votre_secret_jwt
PORT=5000

4. Installer les dépendances

# Backend
cd backend
npm install

# Frontend
cd ../frontend
npm install

5. Lancer l'application

# Terminal 1 - Backend
cd backend
npm run dev

# Terminal 2 - Frontend
cd frontend
npm run dev

Ou utilisez les scripts fournis :

• start-app.bat - Lance tout
• start-backend.bat - Backend uniquement
• start-frontend.bat - Frontend uniquement

📱 Utilisation

1. Connexion : Utilisez vos identifiants pour vous connecter
2. Dashboard : Vue d'ensemble des statistiques
3. Bénéficiaires : Ajouter/modifier les bénéficiaires
4. Opérations : Créer des distributions, scanner les QR codes
5. Finance : Gérer les entrées et sorties

🔐 Rôles Utilisateurs

• Admin : Accès complet
• Gestionnaire : Gestion bénéficiaires et opérations
• Bénévole : Distribution uniquement

---

🇬🇧 Tunisian Social Associations Management

Complete web application for managing charitable associations in Tunisia

Version Française

---

📋 Description

This application helps Tunisian social associations efficiently manage:

• 👥 Beneficiaries and their families
• 🎁 Aid distribution (Ramadan baskets, school supplies, Eid clothing, etc.)
• 💰 Accounting (financial income/expenses)
• 📱 QR Code tracking with photo proof
• 🔄 Automatic duplicate detection (prevent multiple distributions)

✨ Features

Beneficiary Management

• Registration with ID number, family status, income
• Spouse linking for household-level duplicate detection
• Complete history of received aid

Aid Distribution

• Pre-configured aid types (Ramadan, school, Eid, medical, food)
• Unique QR code generation per operation
• QR scan for quick distribution
• Mandatory photo proof upon delivery

Financial Management

• Income tracking (donations, grants, memberships)
• Expense tracking (purchases, charges, direct aid)
• Dashboard with statistics

Duplicate Detection

• Automatic verification before distribution
• Period consideration (monthly, annual, one-time)
• Household-level verification (spouse included)

🛠️ Technologies

Backend

• Node.js + Express.js
• PostgreSQL (database)
• JWT (authentication)
• Multer (photo upload)
• QRCode (generation)

Frontend

• React 18 + Vite
• TailwindCSS (styling)
• React Router DOM (navigation)
• Axios (API requests)
• html5-qrcode (QR scanning)

📁 Project Structure

Gestion-Associations/
├── backend/
│   ├── config/          # Database configuration
│   ├── controllers/     # Business logic
│   │   ├── authController.js
│   │   ├── beneficiaireController.js
│   │   ├── financeController.js
│   │   └── operationController.js
│   ├── middleware/      # JWT authentication
│   ├── routes/          # API routes
│   ├── uploads/         # Uploaded photos
│   ├── schema.sql       # Database schema
│   └── server.js        # Entry point
├── frontend/
│   └── src/
│       ├── components/  # Reusable components
│       ├── context/     # React Context (Auth)
│       ├── pages/       # Main pages
│       │   ├── Dashboard.jsx
│       │   ├── Beneficiaires.jsx
│       │   ├── Operations.jsx
│       │   ├── Finance.jsx
│       │   └── Login.jsx
│       └── services/    # API services
└── startup scripts (.bat)

🚀 Installation

Prerequisites

• Node.js >= 18
• PostgreSQL >= 14
• npm or yarn

1. Clone the project

git clone https://github.com/your-username/Gestion-Associations.git
cd Gestion-Associations

2. Configure the database

# Create PostgreSQL database
psql -U postgres
CREATE DATABASE gestion_associations;
\q

# Run the SQL schema
psql -U postgres -d gestion_associations -f backend/schema.sql

3. Configure environment

# backend/.env
DATABASE_URL=postgresql://postgres:your_password@localhost:5432/gestion_associations
JWT_SECRET=your_jwt_secret
PORT=5000

4. Install dependencies

# Backend
cd backend
npm install

# Frontend
cd ../frontend
npm install

5. Run the application

# Terminal 1 - Backend
cd backend
npm run dev

# Terminal 2 - Frontend
cd frontend
npm run dev

Or use the provided scripts:

• start-app.bat - Starts everything
• start-backend.bat - Backend only
• start-frontend.bat - Frontend only

📱 Usage

1. Login: Use your credentials to log in
2. Dashboard: Overview of statistics
3. Beneficiaries: Add/edit beneficiaries
4. Operations: Create distributions, scan QR codes
5. Finance: Manage income and expenses

🔐 User Roles

• Admin: Full access
• Manager: Beneficiary and operation management
• Volunteer: Distribution only

---

📄 License

MIT License - See LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📧 Contact

For questions or support, please open an issue on GitHub.