Skip to content

About

Artezan is a marketplace that connects customers who need work done with service providers who can perform that work. It is a 12-factor cloud-native microservices platform built with Spring Boot 3/4, Spring Cloud, Kafka KRaft, Resilience4j, Redis, Zipkin distributed tracing, Prometheus, Grafana & Loki log aggregation.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

37 Commits

Folders and files

Repository files navigation

🚀 Artezan — Enterprise 12-Factor Microservices Platform

Spring Boot Spring Cloud Java Docker Kafka Resilience4j

A production-grade, 12-factor cloud-native microservices backend for the Artezan task & service marketplace platform.

Re-architected from a monolith into a decoupled, fault-tolerant, fully observable, and containerized distributed system featuring Resilience4j circuit breakers, Kafka Dead Letter Topics (DLT), Spring Cloud Config Server secret encryption, Prometheus/Grafana metrics & logs, and Zipkin distributed tracing.


🏛️ System Architecture

                       ┌──────────────────────────────────────────────┐
                       │           React / Vite / Mobile App          │
                       └──────────────────────┬───────────────────────┘
                                              │ HTTP / REST (Global CORS ✅)
                                              ▼
                       ┌──────────────────────────────────────────────┐
                       │          API Gateway (Port 8080)             │
                       │   Rate Limiting (Redis) | JWT Auth | Docs    │
                       └──────┬────────────────────────────┬──────────┘
                              │                            │
           ┌──────────────────┴──────────┐                 │  Feign / HTTP (Resilience4j Circuit Breaker ✅)
           │                             │                 ▼
┌──────────▼──────────┐       ┌──────────▼──────────┐   ┌───────────────────────────┐
│ Service Registry    │       │ Config Server       │   │ Microservices (Ports 8081-8088)
│ (Eureka Port 8761)  │       │ (Port 8888 {cipher})│   │ User | Booking | Listing  │
└─────────────────────┘       └─────────────────────┘   │ Task | Review | Payment   │
                                                        │ Notification | Media      │
                                                        └─────────────┬─────────────┘
                                                                      │
                                                ┌─────────────────────┴─────────────────────┐
                                                │ Kafka (Events + Dead Letter Topic DLT)    │
                                                │ PostgreSQL (Flyway V1 Schema Migrations)  │
                                                └───────────────────────────────────────────┘

                               ┌──────────────────────────────────────────────┐
                               │           Observability & Monitoring         │
                               │  Prometheus (9090) | Grafana Dashboards(3000)│
                               │  Zipkin Tracing (9411) | Loki Logs (3100)   │
                               └──────────────────────────────────────────────┘

📦 Service Inventory & Documentation

Click any service name to view its dedicated, detailed module documentation:

Service Name Port Description Database / Engine Documentation
config-server 8888 Centralized Configuration Server ({cipher} secret decryption) config-repo/ Read Documentation
service-registry 8761 Netflix Eureka Service Discovery & Registration In-Memory Read Documentation
api-gateway 8080 API Gateway, Redis Rate Limiter & Global CORS Redis (6379) Read Documentation
user-service 8081 Authentication, JWT, Customer & Provider Accounts PostgreSQL (user_db) Read Documentation
booking-service 8082 Booking Lifecycle State Machine & Agreements PostgreSQL (booking) Read Documentation
listing-service 8083 Service Listings Directory & Provider Offerings PostgreSQL (listing) Read Documentation
task-service 8084 Task Hub Posting & Provider Bidding System PostgreSQL (task) Read Documentation
review-service 8085 Customer Ratings & Provider Feedback Aggregation PostgreSQL (review) Read Documentation
payment-service 8086 Stripe Payment Intents & PayPal REST SDK Integration PostgreSQL (payment) Read Documentation
notification-service 8087 In-App Alerts & Transactional Emails (Kafka + DLT) PostgreSQL (notification) Read Documentation
media-service 8088 Image & Document Cloud Storage (Cloudinary API) Cloudinary Read Documentation

⚡ Quick Start (Single-Command Docker Orchestration)

Prerequisites

  • Docker Engine 24+ and Docker Compose v2+
  • Ports 8080-8088, 8761, 8888, 9090, 9411, 3000, 3100, 6379, 9092 free on host.

Step 1: Environment Setup

Copy the environment template file:

cp .env.example .env

Step 2: Spin Up the 16-Container Infrastructure

Start all containers in detached mode:

docker-compose up -d

Step 3: Verify Container Health

docker-compose ps

All 16 containers will transition to Healthy state.


📊 Live Observability & Management Dashboards

Dashboard / Tool Access URL Default Credentials Description
API Gateway (Swagger UI) http://localhost:8080/swagger-ui.html — Aggregated OpenAPI 3.0 Documentation
Eureka Service Registry http://localhost:8761 — Real-time Service Instance Registry
Spring Cloud Config Server http://localhost:8888/booking-service/default — Dynamic Property Delivery & {cipher} Decryption
Grafana Dashboards http://localhost:3000 admin / admin Unified Metrics & Log Queries
Prometheus Metrics http://localhost:9090 — Actuator Scraping Targets & Query Engine
Zipkin Distributed Tracing http://localhost:9411 — Visual Latency Waterfall Charts (traceId)
Loki Log Aggregator http://localhost:3100 — Real-time Log Stream Processing

🛡️ Enterprise Resilience & Fault Tolerance

  1. Resilience4j Circuit Breaking:

    • CircuitBreaker (trips after 50% failure rate in 10-call sliding window; 30s open state).
    • Retry (3 attempts with exponential backoff).
    • TimeLimiter (3s execution timeouts).
    • 13 Fallback Classes (UserFeignFallback, ListingFeignFallback, etc.) ensuring graceful degradation (503 Service Unavailable with diagnostic contracts) instead of cascading thread exhaustion.
  2. Kafka Dead Letter Topics (DLT):

    • Configured DefaultErrorHandler + DeadLetterPublishingRecoverer in Kafka consumer microservices.
    • Retries failed event records 3 times before routing payloads to <topic-name>.DLT for audit and manual reconciliation.
  3. API Gateway Redis Rate Limiting & CORS:

    • IP-based Token Bucket rate limiting via spring-boot-starter-data-redis-reactive.
    • Global CorsConfig allowing preflight OPTIONS requests from React (3000) and Vite (5173) frontend origins.

📜 12-Factor App Compliance

  • I. Codebase: One Git repository tracking microservices and deployment configs.
  • II. Dependencies: Isolated in multi-stage JDK/JRE Docker build containers.
  • III. Config: Environment variables (.env) and Spring Cloud Config Server ({cipher}).
  • IV. Backing Services: Postgres, Kafka, Redis, Zipkin, Loki attached as environment URLs.
  • V. Build, Release, Run: Distinct compilation (JDK 25) and execution (JRE 25 Alpine) Docker stages.
  • VI. Processes: 100% stateless microservice processes using JWT authentication.
  • VII. Port Binding: Services export HTTP endpoints via embedded Tomcat port binding.
  • VIII. Concurrency: Horizontal scaling (docker-compose up --scale user-service=3).
  • IX. Disposability: Fast boot times and graceful shutdown with Eureka deregistration.
  • X. Dev/Prod Parity: Identical local docker-compose.yaml and cloud production topology.
  • XI. Logs: Event stream logging to stdout, captured by Promtail & Grafana Loki.
  • XII. Admin Processes: Idempotent Flyway database migrations (V1__init_schema.sql).

📄 License & Maintainer

Distributed under the MIT License. Developed by Dean.

About

Artezan is a marketplace that connects customers who need work done with service providers who can perform that work. It is a 12-factor cloud-native microservices platform built with Spring Boot 3/4, Spring Cloud, Kafka KRaft, Resilience4j, Redis, Zipkin distributed tracing, Prometheus, Grafana & Loki log aggregation.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages