VugaSafe Backend API

A secure, scalable backend API for the VugaSafe GBV Case Management Platform in Rwanda. Built with Node.js, TypeScript, Express, and PostgreSQL.

🚀 Features

Public Victim API (No Authentication Required)

• Case Reporting: Anonymous case submission with encrypted contact information
• Case Tracking: Public tracking using unique tracking codes
• Support Services Directory: Access to legal, medical, psychosocial, and shelter services

Admin API (JWT Authentication)

• Case Management: View, filter, and update case status
• Case Assignment: SuperAdmin can assign cases to specific admins
• Dashboard Statistics: Real-time analytics and reporting

SuperAdmin API (SuperAdmin Only)

• User Management: CRUD operations for admin users
• Service Management: Manage support services directory
• Audit Logs: Complete system activity tracking
• Data Export: CSV export functionality for cases
• System Analytics: Comprehensive dashboard statistics

Security Features

• AES-256-GCM Encryption: For sensitive contact information
• JWT Authentication: Secure token-based authentication
• Role-Based Access Control (RBAC): Admin and SuperAdmin roles
• Rate Limiting: Configurable request throttling
• Input Validation: Zod schema validation
• Audit Logging: Complete action tracking

🛠 Tech Stack

• Runtime: Node.js 18+
• Language: TypeScript
• Framework: Express.js
• Database: PostgreSQL with Sequelize ORM
• Authentication: JWT + bcrypt
• Validation: Zod
• Logging: Pino
• Testing: Jest + Supertest
• Documentation: Swagger/OpenAPI
• Containerization: Docker + Docker Compose

📋 Prerequisites

• Node.js 18+
• PostgreSQL 15+
• Redis 7+ (optional, for rate limiting)
• Docker & Docker Compose (for containerized deployment)

🚀 Quick Start

1. Clone the Repository

git clone <repository-url>
cd vugasafe-backend

2. Environment Setup

# Copy environment template
cp env.example .env

# Edit .env with your configuration
nano .env

3. Install Dependencies

npm install

4. Database Setup

# Run migrations
npm run migrate

# Seed initial data
npm run seed

5. Start Development Server

npm run dev

The API will be available at http://localhost:5000

🐳 Docker Deployment

Using Docker Compose (Recommended)

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f api

# Stop services
docker-compose down

Manual Docker Build

# Build image
docker build -t vugasafe-backend .

# Run container
docker run -p 5000:5000 --env-file .env vugasafe-backend

📚 API Documentation

Once the server is running, visit:

• Swagger UI: http://localhost:5000/docs
• Health Check: http://localhost:5000/health
• Readiness Check: http://localhost:5000/ready

🔐 Authentication

Default SuperAdmin Credentials

• Email: admin@vugasafe.rw
• Password: admin123456

JWT Token Usage

# Login to get token
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@vugasafe.rw", "password": "admin123456"}'

# Use token in subsequent requests
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:5000/api/cases

📊 API Endpoints

Public Endpoints

• POST /api/cases/report - Report a new case
• GET /api/cases/track/:trackingCode - Track case status
• GET /api/services - Get support services
• GET /api/services/:id - Get specific service

Admin Endpoints (JWT Required)

• GET /api/cases - Get cases (with filters)
• GET /api/cases/:id - Get specific case
• PUT /api/cases/:id/status - Update case status
• GET /api/auth/profile - Get user profile

SuperAdmin Endpoints (SuperAdmin Only)

• GET /api/admin/users - Get all users
• POST /api/admin/users - Create user
• PUT /api/admin/users/:id - Update user
• DELETE /api/admin/users/:id - Delete user
• GET /api/admin/audit-logs - Get audit logs
• GET /api/admin/export/cases - Export cases to CSV
• GET /api/admin/dashboard - Get dashboard statistics
• PUT /api/cases/:id/assign - Assign case to admin

🧪 Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

📝 Development

Code Quality

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Type checking
npm run type-check

Database Operations

# Run migrations
npm run migrate

# Undo last migration
npm run migrate:undo

# Run seeders
npm run seed

# Undo seeders
npm run seed:undo

🔧 Configuration

Environment Variables

Variable	Description	Default
DB_HOST	PostgreSQL host	localhost
DB_PORT	PostgreSQL port	5432
DB_NAME	Database name	vugasafe_db
DB_USER	Database user	vugasafe_user
DB_PASSWORD	Database password	Required
JWT_SECRET	JWT signing secret	Required (32+ chars)
ENCRYPTION_KEY_32B	AES encryption key	Required (32 bytes)
REDIS_HOST	Redis host	Optional
REDIS_PORT	Redis port	6379
NODE_ENV	Environment	development
PORT	Server port	5000

Security Considerations

1. Change Default Credentials: Update the default SuperAdmin password
2. Strong Secrets: Use cryptographically strong JWT and encryption keys
3. Environment Variables: Never commit .env files to version control
4. HTTPS: Use HTTPS in production with proper SSL certificates
5. Rate Limiting: Configure appropriate rate limits for your use case

📈 Monitoring & Logging

Log Levels

• fatal - System is unusable
• error - Error conditions
• warn - Warning conditions
• info - General information
• debug - Debug information
• trace - Trace information

Health Checks

• /health - Basic health check
• /ready - Readiness check (includes database connectivity)

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support and questions:

• Create an issue in the repository
• Contact the development team
• Check the API documentation at /docs

🔄 Changelog

v1.0.0

• Initial release
• Complete API implementation
• Docker support
• Comprehensive testing
• Security features
• Documentation