🚀 CraftPilot AI - SaaS Backend Platform

                    ┌─────────────────────────────────────────┐
                    │            🌐 Frontend Layer            │
                    │        Web UI  •  Mobile  •  API       │
                    └─────────────────┬───────────────────────┘
                                      │
                    ┌─────────────────┴───────────────────────┐
                    │         🚪 API Gateway (8080)          │
                    │     Authentication  •  Rate Limiting   │
                    │        Routing  •  Load Balancing      │
                    └─────┬─────────┬─────────┬───────────────┘
                          │         │         │
           ┌──────────────┴───┐ ┌───┴───┐ ┌───┴─────────────────────┐
           │                  │ │       │ │                         │
    ┌──────▼──────┐    ┌──────▼──────┐ ┌▼──────┐    ┌──────────────▼──────┐
    │ 👤 User      │    │ 🤖 LLM      │ │🖼️ Image│    │ 💳 Subscription     │
    │ Service      │    │ Service     │ │Service │    │ Service             │
    │ (8081)       │    │ (8082)      │ │(8083)  │    │ (8084)              │
    └──────┬──────┘    └──────┬──────┘ └┬──────┘    └──────────────┬──────┘
           │                  │         │                          │
    ┌──────▼──────┐    ┌──────▼──────┐ ┌▼──────┐    ┌──────────────▼──────┐
    │ 💰 Credit    │    │ 🔔 Notification│📊 Analytics│ 🛡️ Admin            │
    │ Service      │    │ Service     │ │Service │    │ Service             │
    │ (8085)       │    │ (8086)      │ │(8087)  │    │ (8088)              │
    └──────┬──────┘    └──────┬──────┘ └┬──────┘    └──────────────┬──────┘
           │                  │         │                          │
           └──────────────────┼─────────┼──────────────────────────┘
                              │         │
              ┌───────────────▼─────────▼───────────────┐
              │        📡 Service Discovery             │
              │         Eureka Server (8761)           │
              └───────────────┬─────────────────────────┘
                              │
    ┌─────────────────────────┼─────────────────────────────────────┐
    │                         │                                     │
┌───▼────┐  ┌──────▼──────┐  ┌▼──────┐  ┌─────────▼─────────┐  ┌───▼────┐
│🗄️ Redis │  │📊 Prometheus │  │Kafka  │  │  🔥 Firebase       │  │📈Grafana│
│ Cache   │  │  Metrics    │  │Message│  │  Firestore        │  │Dashboard│
│         │  │             │  │Broker │  │  Authentication   │  │        │
└─────────┘  └─────────────┘  └───────┘  └───────────────────┘  └────────┘

           🚀 Reactive • ⚡ Real-time • 🔒 Secure • 📈 Scalable

Advanced AI-powered SaaS platform — structured as a microservices architecture

🔗 Demo • 📖 Documentation • 🐛 Report an Issue • 💬 Discussions

📋 Table of Contents

Overview
Security
Features
Architecture
Services
Tech Stack
Setup
Usage
API Documentation
Monitoring & Observability
Contributing
License

🔐 SECURITY NOTICE: This repository contains template configurations with placeholder passwords. Before deployment, you MUST change all default passwords and configure proper secret management. See SECURITY.md for detailed security setup instructions.

🌟 Overview

CraftPilot AI is a comprehensive AI-powered SaaS platform designed for modern enterprises. It leverages a microservices architecture to deliver scalable, resilient, and high-performance AI solutions.

🎯 Main Goals

AI Integration: Robust conversational experiences with LLMs like GPT and Claude
Visual AI: Advanced image generation and processing capabilities
Enterprise Ready: Enterprise-grade security, monitoring and scalability
Real-time: Reactive programming for real-time data processing
Cloud Native: Cloud-first approach with Kubernetes and Docker

🔐 Security

⚠️ WARNING: This project currently contains development template configurations.

🚨 Pre-production Requirements

Before using this project in production, make sure to:

📋 Read SECURITY.md - detailed security setup guide
📄 Review DEPLOYMENT_SECURITY.md - production deployment security checklist
🔑 Replace all placeholder passwords (CHANGE_ME_IN_PRODUCTION)
🔥 Configure Firebase service account
🗝️ Set up GitHub Secrets (for CI/CD)
🛡️ Configure SSL/TLS certificates

🔐 Security Features

Firebase Authentication - JWT token based authentication
Redis AUTH - authenticated cache access
Role-based Access Control (RBAC) - permission management
API Rate Limiting - DDoS protection
Circuit Breaker Pattern - failure isolation
Distributed Tracing - security monitoring

📋 Security Checklist

Create a .env from .env.example and change credentials
Configure Firebase credentials
Set repository secrets in GitHub
Apply network security rules
Configure SSL certificates
Run security scanning

⚠️ Do not run in production with default credentials!

✨ Features

🤖 AI & Machine Learning

Large Language Models (LLM) integrations
Image Generation and processing services
User Memory Service for personalized experiences
Analytics Service for AI usage insights

🏢 Enterprise Features

Multi-tenant architecture
Role-based access control (RBAC)
Subscription Management system
Credit-based usage tracking
Real-time notifications

🔧 Platform Features

Reactive Programming (Spring WebFlux)
Event-driven architecture (Kafka)
Circuit Breaker pattern (Resilience4j)
API Gateway for centralized routing
Service Discovery (Eureka)
Distributed tracing and monitoring

🏗️ Architecture

graph TB
    subgraph "External Layer"
        UI[Web/Mobile UI]
        API_CLIENTS[API Clients]
    end

    subgraph "Gateway Layer"
        GATEWAY[API Gateway<br/>Port: 8080]
    end

    subgraph "Discovery Layer"
        EUREKA[Eureka Server<br/>Port: 8761]
    end

    subgraph "Core Services"
        USER[User Service<br/>Port: 8081]
        LLM[LLM Service<br/>Port: 8082]
        IMAGE[Image Service<br/>Port: 8083]
        SUB[Subscription Service<br/>Port: 8084]
        CREDIT[Credit Service<br/>Port: 8085]
    end

    subgraph "Support Services"
        NOTIFICATION[Notification Service<br/>Port: 8086]
        ANALYTICS[Analytics Service<br/>Port: 8087]
        ADMIN[Admin Service<br/>Port: 8088]
        MEMORY[User Memory Service<br/>Port: 8089]
        ACTIVITY[Activity Log Service<br/>Port: 8090]
    end

    subgraph "Infrastructure"
        REDIS[(Redis Cache)]
        FIREBASE[(Firebase/Firestore)]
        KAFKA[Kafka Message Broker]
        PROMETHEUS[Prometheus]
        GRAFANA[Grafana]
    end

    UI --> GATEWAY
    API_CLIENTS --> GATEWAY
    GATEWAY --> USER
    GATEWAY --> LLM
    GATEWAY --> IMAGE
    GATEWAY --> SUB

    USER --> FIREBASE
    USER --> REDIS
    LLM --> REDIS
    IMAGE --> REDIS

    USER -.-> KAFKA
    LLM -.-> KAFKA
    ACTIVITY -.-> KAFKA

    PROMETHEUS --> GRAFANA

🔄 Communication Patterns

Synchronous: REST APIs (Spring WebFlux)
Asynchronous: Event-driven messaging (Kafka)
Service Discovery: Eureka Server
Load Balancing: Spring Cloud LoadBalancer
Circuit Breaker: Resilience4j

🚀 Services

🛡️ Core Infrastructure

Service	Port	Description	Technologies
API Gateway	8080	Main entry point, routing, authentication	Spring Cloud Gateway, Firebase Auth
Eureka Server	8761	Service discovery and registry	Netflix Eureka
CraftPilot Commons	-	Shared libraries and utilities	Activity logging, Configuration

👤 Business Services

Service	Port	Description	Features
User Service	8081	User management and preferences	Profile management, Preferences, Circuit breaker
LLM Service	8082	Language model integration	OpenRouter API, Chat histories, Conversation management
Image Service	8083	AI-assisted image generation	Image generation, Processing, Storage
Subscription Service	8084	Subscription and plan management	Plan management, Billing, Usage tracking
Credit Service	8085	Credit system management	Credit allocation, Usage monitoring, Limits

📊 Support Services

Service	Port	Description	Features
Notification Service	8086	Notification system	Push notifications, Email, SMS
Analytics Service	8087	Platform analytics	Usage analytics, Reporting, Insights
Admin Service	8088	Admin panel	User management, System monitoring, Admin tools
User Memory Service	8089	User memory	Context storage, Personalization
Activity Log Service	8090	Activity tracking	Audit logs, User activities, Compliance

🌊 Monitoring & DevOps

Service	Port	Description
Lighthouse Service	8091	Health monitoring and lighthouse metrics
Lighthouse Worker	-	Background tasks and scheduled jobs

🛠️ Tech Stack

☕ Backend Framework

Java 21 - Modern Java features
Spring Boot 3.3.1 - Enterprise application framework
Spring Cloud 2023.0.2 - Microservices toolkit
Spring WebFlux - Reactive programming
Maven - Dependency management

🗄️ Database & Storage

Firebase/Firestore - NoSQL document database
Redis - In-memory caching and session storage
Google Cloud Storage - File storage

📨 Messaging & Events

Apache Kafka - Event streaming platform
Spring Kafka - Kafka integration

🔐 Security & Authentication

Firebase Authentication - User authentication
JWT Tokens - Stateless authentication
Spring Security - Security framework

📊 Monitoring & Observability

Prometheus - Metrics collection
Grafana - Monitoring dashboards
Micrometer - Application metrics
Distributed Tracing - Request tracing

🐳 DevOps & Deployment

Docker - Containerization
Kubernetes - Container orchestration
GitHub Actions - CI/CD pipeline
Spring Boot Actuator - Health checks

🔧 Resilience & Performance

Resilience4j - Circuit breaker, retry, rate limiting
Spring Cloud LoadBalancer - Client-side load balancing
Redis - Distributed caching

🚀 Setup

📋 Requirements

Java 21+
Maven 3.8+
Docker & Docker Compose
Redis (local or container)
Firebase Project (for authentication)

1️⃣ Clone the project

git clone https://github.com/omerada/CraftPilot-API.git
cd CraftPilot-API

2️⃣ Environment Setup

# Place the Firebase configuration file
cp firebase-service-account.json scripts/

# Environment variables
export FIREBASE_PROJECT_ID=your-project-id
export REDIS_HOST=localhost
export REDIS_PORT=6379

3️⃣ Infrastructure Services

# Start Redis and the monitoring stack
docker-compose -f docker-compose.infra.yml up -d

# Check status
docker-compose -f docker-compose.infra.yml ps

4️⃣ Application Build

# Build all modules
mvn clean install

# Or package only
mvn clean package -DskipTests

5️⃣ Service Startup (Development)

# 1. Eureka Server
cd eureka-server && mvn spring-boot:run

# 2. API Gateway
cd api-gateway && mvn spring-boot:run

# 3. Core Services (run in parallel)
cd user-service && mvn spring-boot:run &
cd llm-service && mvn spring-boot:run &
cd image-service && mvn spring-boot:run &

🐳 Production with Docker

# Build all services
mvn clean package -DskipTests

# Build Docker images
docker build -t craftpilot/eureka-server eureka-server/
docker build -t craftpilot/api-gateway api-gateway/
docker build -t craftpilot/user-service user-service/
# ... other services

# Run with Docker Compose
docker-compose up -d

💻 Usage

🌐 Endpoints

Service	URL	Notes
API Gateway	http://localhost:8080	Main API endpoint
Eureka Dashboard	http://localhost:8761	Service discovery UI
Swagger UI	http://localhost:8080/swagger-ui.html	API documentation
Prometheus	http://localhost:9090	Metrics
Grafana	http://localhost:3000	Monitoring dashboard

🔑 Authentication

# API call with Firebase Authentication token
curl -H "Authorization: Bearer YOUR_FIREBASE_TOKEN" \
     http://localhost:8080/api/users/profile

💬 LLM Service Usage

# Start a new conversation
curl -X POST http://localhost:8080/api/llm/conversations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Conversation"}'

# Send a message
curl -X POST http://localhost:8080/api/llm/conversations/{id}/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello, AI!"}'

🖼️ Image Service Usage

# Image generation
curl -X POST http://localhost:8080/api/images/generate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A beautiful sunset", "size": "1024x1024"}'

📚 API Documentation

🔍 Swagger UI

Interactive API docs for all services:

Main API: http://localhost:8080/swagger-ui.html
User Service: http://localhost:8081/swagger-ui.html
LLM Service: http://localhost:8082/swagger-ui.html
Image Service: http://localhost:8083/swagger-ui.html

📖 OpenAPI Specifications

# OpenAPI JSON specs
curl http://localhost:8080/v3/api-docs
curl http://localhost:8081/v3/api-docs
curl http://localhost:8082/v3/api-docs

🔐 Authentication

All API endpoints require a Firebase JWT token:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6...

📊 Monitoring & Observability

📈 Metrics

Prometheus Endpoints:

Application metrics: /actuator/prometheus
Custom business metrics: Spring Micrometer
JVM metrics: Memory, GC, threads

Key Metrics:

# Request rates
http_server_requests_total
http_server_requests_duration_seconds

# Business metrics
craftpilot_user_registrations_total
craftpilot_llm_requests_total
craftpilot_image_generations_total
craftpilot_credit_usage_total

📊 Dashboards

Grafana Dashboards:

Application Overview: System health, request rates
Business Metrics: User activities, service usage
Infrastructure: JVM metrics, Redis performance
Alerts: Error rates, response times

🔍 Distributed Tracing

Using Spring Cloud Sleuth for request tracing:

# Trace headers
X-Trace-Id: 1234567890abcdef
X-Span-Id: abcdef1234567890

🚨 Health Checks

# Service health
curl http://localhost:8080/actuator/health
curl http://localhost:8081/actuator/health

# Detailed health info
curl http://localhost:8080/actuator/health/details

🏃‍♂️ Development

🛠️ Local Development Setup

# Run with hot reload in development
mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Dspring.profiles.active=dev"

# Debug mode
mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005"

🧪 Testing

# Unit tests
mvn test

# Integration tests
mvn verify

# Test coverage
mvn jacoco:report

🔄 Code Quality

# Code formatting
mvn spotless:apply

# Static analysis
mvn spotbugs:check
mvn checkstyle:check

🤝 Contributing

📝 Contribution Guidelines

Fork the project
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push (git push origin feature/amazing-feature)
Open a Pull Request

🐛 Bug Reports

Use the Issue templates to report bugs.

💡 Feature Requests

Share ideas via the Discussions section.

📋 Development Standards

Java Code Style: Google Java Style Guide
Commit Convention: Conventional Commits
Testing: Minimum 80% test coverage
Documentation: JavaDoc and API documentation

📄 License

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

🙏 Thanks

Spring Team - For the framework and ecosystem
Firebase Team - For authentication and database services
OpenRouter - LLM API provider
Contributors - Open source community

📞 Contact

Website: craftpilot.io
Email: support@craftpilot.com
GitHub: CraftPilot Organization
Discord: Community Server

⭐ If you like the project, please give it a star!

🔝 Back to top

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

🚀 CraftPilot AI - SaaS Backend Platform

📋 Table of Contents

🌟 Overview

🎯 Main Goals

🔐 Security

🚨 Pre-production Requirements

🔐 Security Features

📋 Security Checklist

✨ Features

🤖 AI & Machine Learning

🏢 Enterprise Features

🔧 Platform Features

🏗️ Architecture

🔄 Communication Patterns

🚀 Services

🛡️ Core Infrastructure

👤 Business Services

📊 Support Services

🌊 Monitoring & DevOps

🛠️ Tech Stack

☕ Backend Framework

🗄️ Database & Storage

📨 Messaging & Events

🔐 Security & Authentication

📊 Monitoring & Observability

🐳 DevOps & Deployment

🔧 Resilience & Performance

🚀 Setup

📋 Requirements

1️⃣ Clone the project

2️⃣ Environment Setup

3️⃣ Infrastructure Services

4️⃣ Application Build

5️⃣ Service Startup (Development)

🐳 Production with Docker

💻 Usage

🌐 Endpoints

🔑 Authentication

💬 LLM Service Usage

🖼️ Image Service Usage

📚 API Documentation

🔍 Swagger UI

📖 OpenAPI Specifications

🔐 Authentication

📊 Monitoring & Observability

📈 Metrics

📊 Dashboards

🔍 Distributed Tracing

🚨 Health Checks

🏃‍♂️ Development

🛠️ Local Development Setup

🧪 Testing

🔄 Code Quality

🤝 Contributing

📝 Contribution Guidelines

🐛 Bug Reports

💡 Feature Requests

📋 Development Standards

📄 License

🙏 Thanks

📞 Contact