Fablewhirl

A microservice-based character sheet editor for Dungeons & Dragons 5th Edition.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Microservices
   • Infrastructure
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. API Endpoints
5. CI/CD
6. Monitoring
7. Roadmap
8. Contributing
9. License
10. Contact

About The Project

Fablewhirl is a character sheet editor for Dungeons & Dragons 5th Edition, designed to streamline character creation and management. Built as a microservice-based monorepository with Spring Boot, it leverages a horizontally scalable architecture with Kubernetes orchestration, Kafka for asynchronous processing, and Keycloak for secure authentication. The platform supports both development and production environments, with robust monitoring via Prometheus and Grafana. I guess this project could be an great example for new developers to see how a large-scale backend is actually built and coded.

Key features:

• Scalable microservice architecture with service discovery via Netflix Eureka.
• Secure authentication and caching with Keycloak and Redis.
• CI/CD pipeline for automated builds and deployments.
• K8s manifests for infrastructure and microservices.

(back to top)

Microservices

Fablewhirl is structured into seven microservices, each with bounded responsibilities:

• Eureka Server: Manages service discovery using Netflix Eureka with @DiscoveryClient.
• Auth Service: Handles authentication via Keycloak, issuing access and refresh tokens.
• User Service: Manages user profiles and metadata, integrated with Keycloak tokens.
• Character Service: Manages D&D E5 character sheets, including attributes and inventory.
• Thread Service: Manages posts for user-generated content and discussions.
• Comment Service: Handles comment logic and responses for user interactions.
• API Gateway: Routes requests to appropriate microservices, acting as a single entry point.

(back to top)

Infrastructure

• Authentication: Keycloak provides OAuth2-based authentication with access and refresh tokens for secure user metadata access.
• Messaging: Kafka enables asynchronous data processing for scalable, event-driven communication.
• Caching: Redis caches user tokens and narrative threads for improved performance.
• Storage: MinIO provides local storage with AWS S3 compatibility for scalable file management.
• Orchestration: Kubernetes manages nine containers (7 microservices + infrastructure services) with replicas and secrets for security.
• CI/CD: GitHub Actions automates building and deploying microservices, with dependency caching for efficiency.

(back to top)

Built With

• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 

Built With(back to top)

Getting Started

Set up Fablewhirl locally using Docker Compose for the dev environment or deploy to Kubernetes for production.

Prerequisites

Ensure you have the following installed:

• Java 21
• Gradle
• Docker and Docker Compose
• kubectl (for prod environment)
• Keycloak, PostgreSQL, MongoDB, Kafka, Redis, MinIO (or use Docker Compose)

  java --version
  gradle --version
  docker --version

Installation

1. Clone the repository:

   git clone https://github.com/fl1s/fablewhirl.git

2. Navigate to the project directory:

   cd fablewhirl

3. Build all microservices with Gradle:

   ./gradlew build

4. Start the dev environment with Docker Compose:

   docker-compose up -d

5. Verify services are running:

   docker ps

6. (Optional) For prod, apply Kubernetes manifests:

   kubectl apply -f k8s/

7. Configure Keycloak:

• Realm config file: fablewhirl-realm.json
• Location: /.config/keycloak
• Import it into your Keycloak server manually or via REST API.

  cp .env.dev.example .env.dev.yml
  cp .env.prod.example .env.prod.yml

8. Set secrets in Vault: Environment variables for microservices are now stored securely in Spring Cloud Vault(HashiCorp) instead of local .env files.
   You can manually populate them using the Vault CLI:

Example (dev): auth-service

vault kv put secret/dev/auth-service \
  EUREKA.INSTANCE.HOSTNAME=localhost \
  EUREKA.CLIENT.SERVICE_URL.DEFAULT_ZONE=http://localhost:8761/eureka/ \
  JWT_ISSUER_URI=http://localhost:8443/realms/fablewhirl-realm \
  KAFKA.BOOTSTRAP_SERVERS=localhost:9092 \
  REDIS.URL=redis://localhost:6379 \
  KEYCLOAK.REALM=fablewhirl-realm \
  KEYCLOAK.RESOURCE=auth-service \
  KEYCLOAK.CREDENTIALS.CLIENT_ID=auth-service \
  KEYCLOAK.CREDENTIALS.SECRET=aurh49l7fHgD1K4DQ8RlUmzAMPAxWtd8 \
  KEYCLOAK.AUTH_SERVER_URL=http://localhost:8443/ \
  KEYCLOAK.JWKS_CERTS=http://localhost:8443/realms/fablewhirl-realm/protocol/openid-connect/certs

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- USAGE -->
## Usage

1. Start all microservices via Docker Compose (dev) or Kubernetes (prod).
2. Access the API Gateway at `http://localhost:3000` (or your configured port).
3. Use the Postman collection to interact with the APIs (see [API Endpoints](#api-endpoints)).

Example: Create a new character via the Character Service:
```sh
curl -X POST http://localhost:3000/api/v1/auth/sign-up -H "Content-Type: application/json" -d '{"email":"user@example.com","username":"COOLSKELETON95","password":"boNESS","bio":"D&D EnTHUGsiast!"}'

(back to top)

API Endpoints

Fablewhirl provides a comprehensive set of API endpoints for all microservices. A Postman collection with environment variables for dev and prod is included:

• File: fablewhirl.postman-collectionV2.json or fablewhirl.postman-collectionV2.1.json
• Location: /.config/postman

Import the JSON file into Postman to test all endpoints. The collection includes variables for {{jwt_token}} and {{api-gateway}}.

(back to top)

CI/CD

Fablewhirl uses GitHub Actions for automated CI/CD:

• Build: Gradle builds all microservices with dependency caching.
• Docker Images: Each microservice is containerized and pushed to a registry.
• Deployment: Kubernetes manifests are applied to deploy nine containers (seven microservices plus infrastructure services) with replicas and secrets.

Check the .github/workflows/ directory for pipeline details.

(back to top)

Monitoring

Prometheus and Grafana are integrated for real-time monitoring:

• Prometheus: Collects metrics on system performance, API latency, and resource usage.
• Grafana: Visualizes metrics with dashboards for monitoring microservice health.

Access Grafana at http://localhost:3001 (dev) or your prod URL after setup.

(back to top)

Roadmap

• Implement microservice architecture with Eureka and Keycloak
• Set up Kafka for async processing
• Integrate Prometheus and Grafana for monitoring
• Add real-time collaboration for character sheet editing
• Support for D&D E5 homebrew content
• Enhance MinIO with advanced S3 features

See the open issues for a full list of proposed features and known issues.

(back to top)

Contributing

Contributions are welcome to enhance Fablewhirl! Follow these steps:

1. Fork the Project.
2. Create your Feature Branch:

   git checkout -b feature/AmazingFeature

3. Commit your Changes:

   git commit -m 'feat: add some fuzzBuzzCoolFeature'

4. Push to the Branch:

   git push --set-upstream origin feature/amazing-feature

5. Open a Pull Request.

Read our Contributing Guidelines for more details.

Top Contributors

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

fl1s - GitHub

Project Link: https://github.com/fl1s/fablewhirl

(back to top)