Event-Driven Team Task Board on GKE

Table of Contents

• About
• Architecture
• Getting Started
  • Local Development
  • GKE Deployment
• Authentication
• Scripts
• License

Architecture

Cascade implements a microservices architecture with the following core services:

Services

1. Auth Service (auth) - User authentication using Better Auth with email/password and GitHub OAuth
2. Board Command Service (board-command) - Write operations for boards and tasks
3. Board Query Service (board-query) - Read operations with caching
4. Activity Service (activity) - Real-time activity logging via Kafka events
5. Audit Service (audit) - Immutable audit trail for compliance
6. API Docs Service (api-docs) - Centralized API documentation

All services are deployed to both local (Docker Compose) and production (GKE) environments.

Microservices Patterns

1. CQRS (Command Query Responsibility Segregation)

• Command Service: Handles all write operations
• Query Service: Optimized for read operations with Redis caching
• Async synchronization via Kafka events

2. Event Sourcing (Partial)

• All state changes published as events to Kafka
• Audit service maintains immutable event log

3. API Gateway Pattern

• Nginx ingress controller routes traffic
• Path-based routing to appropriate services

4. Database per Service

• Each service has its own MongoDB database or collection
• No shared databases between services

5. Saga Pattern (Orchestration)

• Multi-step workflows coordinated via Kafka events
• Example: Board creation triggers notifications and audit logs

6. Circuit Breaker (via Retry Logic)

• Services implement retry mechanisms for Kafka connections

7. Reactive Programming (RxJS)

• Observable Streams: Kafka events processed as reactive streams
• Operators: map, filter, tap, catchError for event transformation
• Backpressure: Built-in handling via RxJS
• Error Recovery: Graceful error handling with stream continuation

Event Flow

1. User action → Command Service
2. Command Service writes to DB
3. Command Service publishes event to Kafka
4. Query Service consumes event, invalidates cache
5. Activity Service logs the event
6. Audit Service stores immutable record

Getting Started

Local Development

To run the project locally using Docker Compose:

1. Ensure you have Docker and Docker Compose installed.

2. Start the services:

   docker-compose up --build

   More details in the local docker compose documentation.

GKE Deployment

To deploy the project to Google Kubernetes Engine (GKE) using Helm:

Quick Start:

./setup.sh <YOUR_PROJECT_ID>

Manual Deployment: See the Deployment Checklist for step-by-step instructions.

Key Features:

• Automated cluster setup and configuration
• Kafka with KRaft mode (no Zookeeper)
• MongoDB 3-node replica set
• Redis caching layer
• Nginx Ingress with dynamic IP support (nip.io)
• GitHub OAuth authentication

Accessing Kafka UI

Kafka UI is not exposed via Ingress by default. To access it:

kubectl port-forward svc/cascade-kafka-ui 8080:80

Then open http://localhost:8080 in your browser.

Authentication

Cascade supports multiple authentication methods:

Email/Password Authentication

Users can sign up and sign in using email and password (powered by Better Auth).

GitHub OAuth

Users can sign in with their GitHub accounts for a seamless experience.

Setup Instructions: See GitHub OAuth Setup Guide for detailed configuration steps.

Quick Setup:

1. Create a GitHub OAuth App at https://github.com/settings/developers

2. Deploy with secrets:

   helm upgrade cascade helm/cascade \
     --set secrets.githubClientId="your-client-id" \
     --set secrets.githubClientSecret="your-secret"

3. Configure callback URL: http://<INGRESS_IP>/api/auth/callback/github

API Documentation

API documentation is available via Scalar for each microservice when running:

• Centralized API Docs: http://localhost:3006

Documentation

• Architecture Overview - High-level architecture diagrams
• GKE Architecture Guide - Detailed documentation on how Cascade works in Kubernetes
  • Service discovery and communication patterns
  • Database architecture and synchronization
  • Caching strategy and data flow
  • Event-driven architecture with Kafka
  • Complete deployment topology
• Activity & Audit Services - Observability and compliance features
  • Real-time activity monitoring
  • Immutable audit trail
  • Deployment and usage guide

Scripts

• setup.sh: Initializes the environment and prepares dependencies.
• cleanup.sh: Cleans up local or remote resources.
• build-and-push.sh: Builds Docker images and pushes them to a container registry.

License

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

Star History