⚙️ Autonova Backend - Microservices

Spring Boot microservices architecture for the Autonova automobile service management platform

Architecture • Services • Quick Start • API Docs

---

📋 Table of Contents

• Overview
• Architecture
• Services
• Technologies
• Quick Start
• API Documentation
• Configuration
• Testing
• Monitoring
• Troubleshooting

---

🎯 Overview

The Autonova backend is a microservices-based system built with Spring Boot and Spring Cloud. It provides RESTful APIs for managing vehicle services, appointments, customer data, employee tasks, and billing. The system uses Netflix Eureka for service discovery, Spring Cloud Gateway for API routing, and RabbitMQ for event-driven communication.

Key Features:

• 🏗️ 9+ Microservices - Independently deployable services
• 🔐 Secure Authentication - JWT + OAuth2 Google login
• 📊 Service Discovery - Dynamic registration with Eureka
• 🔄 Event-Driven - RabbitMQ for async messaging
• 🐳 Docker Ready - Full containerization support
• 📈 Monitoring - Spring Actuator health checks
• 📖 API Docs - Swagger/OpenAPI documentation

---

🏗️ Architecture

System Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                     API Gateway (:8080)                          │
│     (Spring Cloud Gateway - Routing, Load Balancing, CORS)      │
└────────────────────────┬────────────────────────────────────────┘
                         │
          ┌──────────────┼──────────────┐
          │              │              │
    ┌─────▼─────┐  ┌─────▼─────┐  ┌────▼──────┐
    │  Service  │  │  Auth     │  │ Customer  │
    │ Discovery │  │  Service  │  │  Service  │
    │  (Eureka) │  │   :8081   │  │   :8087   │
    │   :8761   │  └─────┬─────┘  └─────┬─────┘
    └───────────┘        │              │
                         │              │
              ┌──────────┴──────────────┴──────────────┐
              │                                        │
         ┌────▼────┐    ┌──────────┐    ┌────────────▼──┐
         │Employee │    │Appointment│   │   Progress    │
         │Dashboard│    │  Booking  │   │  Monitoring   │
         │  :8084  │    │   :8083   │   │    :8085      │
         └────┬────┘    └─────┬─────┘   └───────┬───────┘
              │               │                  │
              └───────────────┼──────────────────┘
                              │
                         ┌────▼─────┐
                         │PostgreSQL│
                         │  :5432   │
                         └──────────┘
                              │
                         ┌────▼─────┐
                         │ RabbitMQ │
                         │:5672,15672│
                         └──────────┘

Architecture Patterns:

• Microservices Architecture - Loosely coupled, independently deployable services
• API Gateway Pattern - Centralized entry point for all client requests
• Service Discovery - Dynamic service registration and discovery with Eureka
• Event-Driven Architecture - Asynchronous communication via RabbitMQ
• Database per Service - Each service has its own database schema
• CQRS - Command Query Responsibility Segregation for complex queries

---

🔧 Services

Service	Port	Description	Key Features
Gateway Service	8080	API Gateway - Single entry point	Routing, CORS, Load balancing
Discovery Service	8761	Eureka - Service registry	Service registration, Health checks
Auth Service	8081	Authentication & authorization	JWT, OAuth2, User management, RBAC
Customer Service	8087	Customer & vehicle management	CRUD operations, Vehicle tracking
Employee Dashboard	8084	Employee tasks & time logs	Task assignment, Time tracking
Appointment Booking	8083	Service booking management	Scheduling, Availability checks
Progress Monitoring	8085	Real-time service tracking	Status updates, Progress notifications
Time Logging	8086	Time tracking analytics	Log management, Reports, Analytics
Notification Service	8088	Email/SMS notifications	Template engine, Multi-channel alerts
Project Service	8082	Project management (.NET)	.NET Core integration, Project CRUD

Service-Specific Documentation:

• 🔐 Auth Service README - Authentication & user management
• 👥 Customer Service README - Customer & vehicle operations
• 💼 Employee Dashboard README - Employee features

---

🛠️ Technologies

Core Framework:

• Java 17 - Programming language
• Spring Boot 3.3.3 - Application framework
• Spring Cloud 2023.0.3 - Microservices infrastructure
• Maven 3.9 - Build automation and dependency management

Spring Stack:

• Spring Security 6 - Authentication and authorization
• Spring Data JPA - Database ORM and repositories
• Spring Cloud Gateway - API Gateway
• Spring Cloud Netflix Eureka - Service discovery
• Spring AMQP - RabbitMQ integration
• Spring Actuator - Health monitoring and metrics
• Spring Boot DevTools - Development productivity

Database & Messaging:

• PostgreSQL 17 - Primary database
• Flyway - Database migration tool
• RabbitMQ 4.1.4 - Message broker (AMQP protocol)

Security:

• JJWT 0.11.5 - JWT token generation and validation
• BCrypt - Password hashing algorithm
• OAuth2 Client - Google authentication integration

Testing:

• JUnit 5 - Unit testing framework
• Spring Boot Test - Integration testing
• Mockito - Mocking framework
• H2 Database - In-memory testing database

Documentation & Monitoring:

• Springdoc OpenAPI 3 - API documentation (Swagger UI)
• Micrometer - Application metrics
• Logback - Logging framework
• SLF4J - Logging facade

DevOps:

• Docker - Containerization
• Docker Compose - Multi-container orchestration
• GitHub Actions - CI/CD pipeline

---

🚀 Quick Start

Prerequisites

# Check installations
java -version    # Java 17 or higher
mvn -version     # Maven 3.9+
docker --version # Docker 20.10+
docker-compose --version

Option 1: Docker Compose (Recommended)

1. Start Infrastructure Services

cd infra
cp .env.example .env  # Create environment file

# Edit .env with your configurations
nano .env

# Start PostgreSQL, RabbitMQ, and Eureka
docker-compose up -d

Services Started:

• ✅ PostgreSQL (:5432)
• ✅ RabbitMQ (:5672, :15672 management UI)
• ✅ Eureka Discovery (:8761)

2. Build and Start All Services

# From autonova-backend root
docker-compose up --build

Or start individual services:

docker-compose up -d gateway-service
docker-compose up -d auth-service
docker-compose up -d customer-service

3. Verify Services

• Eureka Dashboard: http://localhost:8761
• RabbitMQ Management: http://localhost:15672 (admin/admin123)
• Gateway Health: http://localhost:8080/actuator/health

Option 2: Local Development (Without Docker)

1. Start Infrastructure

cd infra
docker-compose up -d postgres rabbitmq

2. Build All Services

# From autonova-backend root
mvn clean install -DskipTests

3. Run Services Individually

Terminal 1 - Discovery Service (Start First):

cd discovery-service
mvn spring-boot:run

Wait for Eureka to start (check http://localhost:8761)

Terminal 2 - Gateway Service:

cd gateway-service
mvn spring-boot:run

Terminal 3 - Auth Service:

cd auth-service
mvn spring-boot:run

Terminal 4 - Customer Service:

cd customer-service
mvn spring-boot:run

Terminal 5 - Employee Dashboard:

cd employee-dashboard-service
mvn spring-boot:run

4. Run .NET Project Service

cd services/project-service
dotnet restore
dotnet build
dotnet run --urls "http://localhost:8082"

Option 3: Production Build (JAR)

# Build JAR files
mvn clean package -DskipTests

# Run each service
java -jar gateway-service/target/gateway-service-*.jar
java -jar auth-service/target/auth-service-*.jar
# ... repeat for other services

---

📖 API Documentation

Swagger UI Access

Once services are running, access Swagger documentation:

• Gateway Aggregated API: http://localhost:8080/swagger-ui.html
• Auth Service: http://localhost:8081/swagger-ui.html
• Customer Service: http://localhost:8087/swagger-ui.html
• Employee Dashboard: http://localhost:8084/swagger-ui.html

Key Endpoints

Auth Service (/api/auth)

POST   /api/auth/login              # User login (returns JWT)
POST   /api/auth/signup             # User registration
POST   /api/auth/refresh            # Refresh JWT token
GET    /api/auth/google             # OAuth2 Google login redirect
POST   /api/auth/logout             # Logout (invalidate token)
POST   /api/auth/forgot-password    # Request password reset
POST   /api/auth/reset-password     # Reset password with token

User Management (/api/users)

GET    /api/users                   # List all users (Admin only)
POST   /api/users                   # Create new user
GET    /api/users/{id}              # Get user details
PUT    /api/users/{id}              # Update user
DELETE /api/users/{id}              # Delete user (Admin only)
GET    /api/users/me                # Get current user profile

Customer Service (/api/customers)

GET    /api/customers               # List customers
POST   /api/customers               # Create customer
GET    /api/customers/{id}          # Get customer details
PUT    /api/customers/{id}          # Update customer
DELETE /api/customers/{id}          # Delete customer
GET    /api/customers/{id}/vehicles # Get customer vehicles

Appointment Service (/api/appointments)

GET    /api/appointments            # List appointments
POST   /api/appointments            # Create appointment
GET    /api/appointments/{id}       # Get appointment details
PUT    /api/appointments/{id}       # Update appointment
DELETE /api/appointments/{id}       # Cancel appointment

Employee Dashboard (/api/employees)

GET    /api/employees/tasks         # Get assigned tasks
GET    /api/employees/time-logs     # Get time logs
POST   /api/employees/time-logs     # Create time log entry
GET    /api/employees/performance   # Get performance metrics

Authentication

All protected endpoints require JWT token in Authorization header:

Authorization: Bearer <your-jwt-token>

---

⚙️ Configuration

Environment Variables

Create .env file in infra/ directory:

# Database Configuration
POSTGRES_DB=autonova
POSTGRES_USER=admin
POSTGRES_PASSWORD=secure_password_123

# RabbitMQ Configuration
RABBITMQ_USER=admin
RABBITMQ_PASS=secure_rabbitmq_pass
RABBITMQ_HOST=localhost
RABBITMQ_PORT=5672

# JWT Configuration
JWT_SECRET=your-256-bit-secret-key-minimum-32-characters
JWT_EXPIRATION=3600000  # 1 hour in milliseconds

# OAuth2 Configuration
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=http://localhost:8080/login/oauth2/code/google

# Service Ports
GATEWAY_PORT=8080
EUREKA_PORT=8761
AUTH_SERVICE_PORT=8081
CUSTOMER_SERVICE_PORT=8087
EMPLOYEE_SERVICE_PORT=8084

# Spring Profiles
SPRING_PROFILES_ACTIVE=dev

Database Configuration

Automatic Database Creation

The Docker Compose setup includes automatic database initialization:

# infra/init-scripts/ contains initialization SQL
# Databases created automatically on first run:
- autonova (main database)
- auth_service_db
- customer_service_db
- employee_service_db

Manual Database Setup

-- Connect to PostgreSQL
psql -h localhost -U admin -d postgres

-- Create databases
CREATE DATABASE autonova;
CREATE DATABASE auth_service_db;
CREATE DATABASE customer_service_db;

-- Verify
\l

Flyway Migrations

Database schemas are managed with Flyway:

src/main/resources/db/migration/
├── V1__Create_users_table.sql
├── V2__Create_vehicles_table.sql
└── V3__Create_appointments_table.sql

Migrations run automatically on application startup.

---

🧪 Testing

Run All Tests

# From autonova-backend root
mvn test

Run Tests for Specific Service

cd auth-service
mvn test

cd customer-service
mvn test

Integration Tests

mvn verify -P integration-tests

Test Coverage Report

mvn jacoco:report

# View report
open target/site/jacoco/index.html

Run Single Test Class

mvn test -Dtest=UserServiceTest

---

📊 Monitoring

Health Checks

Check service health via Actuator endpoints:

# Gateway health
curl http://localhost:8080/actuator/health

# Auth service health
curl http://localhost:8081/actuator/health

# All registered services (Eureka)
curl http://localhost:8761/eureka/apps

Metrics

# Application metrics
curl http://localhost:8080/actuator/metrics

# JVM memory
curl http://localhost:8080/actuator/metrics/jvm.memory.used

# HTTP request stats
curl http://localhost:8080/actuator/metrics/http.server.requests

Service Discovery

View all registered services at Eureka Dashboard:

• http://localhost:8761

RabbitMQ Monitoring

RabbitMQ Management Console:

• URL: http://localhost:15672
• Username: admin
• Password: admin123

---

🐛 Troubleshooting

Common Issues

1. Services Won't Start

# Check if ports are available
lsof -i :8080  # Gateway
lsof -i :8081  # Auth service
lsof -i :5432  # PostgreSQL

# Kill processes if needed
kill -9 <PID>

2. Service Not Registering with Eureka

# Check Eureka is running
curl http://localhost:8761/actuator/health

# Verify application.yml has correct eureka config
eureka:
  client:
    serviceUrl:
      defaultZone: http://localhost:8761/eureka/

3. Database Connection Issues

# Check PostgreSQL is running
docker ps | grep postgres

# Test connection
psql -h localhost -U admin -d autonova

# Check logs
docker logs <postgres-container-id>

4. RabbitMQ Connection Failed

# Verify RabbitMQ is running
docker ps | grep rabbitmq

# Check RabbitMQ logs
docker logs <rabbitmq-container-id>

# Test connection
curl http://localhost:15672

5. JWT Token Validation Fails

# Verify JWT_SECRET is set correctly in .env
# Ensure secret is at least 256 bits (32 characters)
# Check token hasn't expired (default: 1 hour)

6. Maven Build Fails

# Clean and rebuild
mvn clean install -U

# Skip tests if needed
mvn clean install -DskipTests

# Update dependencies
mvn dependency:resolve

Debug Mode

Enable debug logging:

# application.yml
logging:
  level:
    com.autonova: DEBUG
    org.springframework.security: DEBUG
    org.springframework.cloud: DEBUG

Or via environment variable:

LOGGING_LEVEL_COM_AUTONOVA=DEBUG mvn spring-boot:run

View Logs

# Docker Compose logs
docker-compose logs -f gateway-service
docker-compose logs -f auth-service

# Follow all logs
docker-compose logs -f

# Spring Boot application logs
tail -f logs/spring.log

---

📚 Additional Resources

Documentation

• 🏠 Main Project README - Project overview
• 🎨 Frontend README - React application
• 📊 API Contracts - OpenAPI specifications
• 📧 Event Schemas - RabbitMQ event definitions

External Links

• Spring Boot Documentation
• Spring Cloud Documentation
• PostgreSQL Documentation
• RabbitMQ Documentation

---

🤝 Contributing

See main Contributing Guidelines

Backend Development Guidelines:

1. Follow Spring Boot best practices
2. Write unit tests for all service methods
3. Update Swagger documentation for new endpoints
4. Use Flyway for database schema changes
5. Follow REST API naming conventions
6. Implement proper exception handling
7. Log at appropriate levels (ERROR, WARN, INFO, DEBUG)

---

📄 License

This project is licensed under the MIT License.

---

Part of the Autonova Platform

⬆ Back to Top | Main README