CareForAll Donation Platform

A fault-tolerant, event-driven microservices platform for managing donation campaigns with comprehensive observability.

🏗️ Architecture Overview

CareForAll is built using modern microservices architecture with the following key components:

• Event-Driven: RabbitMQ message broker for asynchronous communication
• CQRS Pattern: Separate read and write models for optimal performance
• Transactional Outbox: Guaranteed event delivery with at-least-once semantics
• State Machine: Controlled pledge lifecycle with validation
• Distributed Tracing: OpenTelemetry + Jaeger for request tracking
• Metrics & Monitoring: Prometheus + Grafana for real-time insights
• Centralized Logging: ELK Stack (Elasticsearch + Kibana)

📦 Tech Stack

Backend Services

• Runtime: Node.js 18+ with TypeScript
• Database: MongoDB Replica Set (transactions support)
• Message Broker: RabbitMQ 3.12
• API Gateway: NGINX

Observability Stack

• Distributed Tracing: Jaeger
• Metrics: Prometheus + Node Exporter
• Visualization: Grafana
• Logging: Elasticsearch + Kibana
• Instrumentation: OpenTelemetry SDK

Libraries

• Web Framework: Express.js
• ODM: Mongoose
• Validation: Zod
• Logging: Pino
• Metrics: prom-client
• Authentication: JWT (jsonwebtoken)

🚀 Quick Start

Prerequisites

• Docker Engine 20.10+
• Docker Compose 2.0+
• Node.js 18+ (for local development)
• npm 9+ or yarn 1.22+

Installation

1. Clone the repository:

git clone <repository-url>
cd careforall

2. Copy environment variables:

cp .env.example .env

3. Start the infrastructure:

docker-compose up -d

4. Verify services are running:

docker-compose ps

All services should show "healthy" status within 30-60 seconds.

Access Points

Once the infrastructure is running, access the following UIs:

Service	URL	Credentials
RabbitMQ Management	http://localhost:15672	admin / admin123
Jaeger UI	http://localhost:16686	-
Prometheus	http://localhost:9090	-
Grafana	http://localhost:3000	admin / admin
Kibana	http://localhost:5601	-
Elasticsearch	http://localhost:9200	-
API Gateway	http://localhost	-

📁 Project Structure

careforall/
├── services/                    # Microservices
│   ├── identity-service/        # User authentication & authorization
│   ├── campaign-service/        # Campaign management
│   ├── pledge-service/          # Pledge processing (with outbox pattern)
│   ├── payment-service/         # Payment processing & webhooks
│   ├── totals-service/          # CQRS read model for totals
│   └── comms-service/           # Notifications (bonus)
├── packages/
│   └── shared/                  # Shared TypeScript utilities
│       ├── types/               # Type definitions
│       ├── utils/               # Utility functions
│       │   ├── mongodb.ts       # Database connection
│       │   ├── rabbitmq.ts      # Message broker
│       │   ├── logger.ts        # Structured logging
│       │   ├── telemetry.ts     # OpenTelemetry setup
│       │   ├── metrics.ts       # Prometheus metrics
│       │   ├── validation.ts    # Zod schemas
│       │   └── errors.ts        # Custom error classes
│       └── constants/           # Shared constants
├── prometheus/
│   └── prometheus.yml           # Metrics scraping config
├── grafana/
│   ├── datasources/             # Prometheus datasource
│   └── dashboards/              # Pre-built dashboards
├── nginx/
│   └── nginx.conf               # API Gateway configuration
├── docker-compose.yml           # Infrastructure orchestration
├── .env.example                 # Environment variables template
└── README.md                    # This file

🔧 Development

Build Shared Package

cd packages/shared
npm install
npm run build

Running Services Locally

Each service can be run independently for development:

cd services/<service-name>
npm install
npm run dev

Note: Services require MongoDB and RabbitMQ. Either run them via Docker Compose or connect to local instances by updating .env.

Testing

# Run tests for all packages
npm run test

# Run tests for specific service
cd services/<service-name>
npm test

📊 Observability

Distributed Tracing with Jaeger

All HTTP requests, database queries, and message broker operations are automatically traced. View traces at http://localhost:16686.

Features:

• End-to-end request tracking across services
• Performance bottleneck identification
• Dependency analysis

Metrics with Prometheus & Grafana

Pre-configured dashboard available at http://localhost:3000 showing:

• HTTP request rate and latency (p50, p95, p99)
• Business metrics: pledges/sec, payment success rate
• RabbitMQ queue depths
• MongoDB connection pool stats
• Error rates by service
• Outbox event processing lag

Centralized Logging with ELK

All service logs are automatically shipped to Elasticsearch. View and search logs at http://localhost:5601.

Log Structure:

• Structured JSON format
• Service name and environment tags
• Request correlation IDs
• Error stack traces

🔐 Security

Environment Variables

Critical: Change the following secrets in production:

JWT_SECRET=<strong-random-secret>
WEBHOOK_SECRET=<strong-random-secret>

Authentication

• JWT tokens with 7-day expiry
• Role-based access control (RBAC)
• Anonymous session support for guest donors

🎯 Key Architectural Patterns

1. Transactional Outbox Pattern

Guarantees event delivery even if message broker is down:

1. Events written to outbox table in same DB transaction as business data
2. Background worker polls outbox and publishes to RabbitMQ
3. Exponential backoff retry on failures
4. Idempotent event processing

2. Idempotency

All pledge creation requests require Idempotency-Key header (UUID):

• Prevents duplicate charges
• Uses MongoDB unique index for atomic deduplication
• Race-condition free implementation

3. State Machine

Pledge status transitions are validated:

PENDING → AUTHORIZED → CAPTURED → COMPLETED
          ↓            ↓
        FAILED      REFUNDED

4. CQRS (Command Query Responsibility Segregation)

Separate write (Pledge Service) and read (Totals Service) models:

• Write: Optimized for consistency and validation
• Read: Pre-calculated totals for < 50ms response time
• Automatic reconciliation every 5 minutes

🐛 Troubleshooting

MongoDB Replica Set Not Initializing

# Check mongo-init logs
docker-compose logs mongo-init

# Manually initialize if needed
docker exec -it careforall-mongo mongosh --eval "rs.initiate()"

RabbitMQ Connection Issues

# Check RabbitMQ logs
docker-compose logs rabbitmq

# Verify service is healthy
docker-compose ps rabbitmq

Service Cannot Connect to MongoDB/RabbitMQ

Ensure services are on the same Docker network:

docker network ls
docker network inspect careforall-network

📈 Performance

Target Metrics

• Totals API response time: < 50ms (p95)
• Pledge creation: < 200ms (p95)
• Payment webhook processing: < 100ms (p95)
• Throughput: 1000+ requests/second

Load Testing

# Test totals endpoint
ab -n 10000 -c 100 http://localhost/api/totals/<campaignId>

🔄 CI/CD

GitHub Actions pipeline configured for:

• Automated testing on pull requests
• Docker image building and publishing
• Semantic versioning
• Monorepo change detection

See .github/workflows/ci.yml for details.

📚 API Documentation

API documentation will be available in Phase 2 when services are implemented.

🤝 Contributing

1. Create a feature branch
2. Make your changes
3. Ensure tests pass: npm test
4. Ensure linting passes: npm run lint
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details

👥 Team

• [Your Team Name]

🎓 References

• Transactional Outbox Pattern
• CQRS Pattern
• OpenTelemetry
• Event-Driven Architecture

---

Phase 1 Complete: Infrastructure Foundation ✅

Next: Phase 2 - API Gateway & Identity Service