Skip to content

README.md

Latest commit

 

History

History
425 lines (344 loc) · 12.8 KB

README.md

File metadata and controls

425 lines (344 loc) · 12.8 KB
Raw

🌐 Telecom Service Platform

Java Spring Boot License: MIT Build Status

✅ Core Technical Skills Demonstrated

  • Java 17 with modern features (Stream API, Lambda expressions, Concurrency API)
  • Spring Boot 3.x microservices architecture
  • RESTful APIs for network automation
  • Multi-tenant hierarchical applications for network operators
  • Event-driven architecture foundation (ready for Kafka integration)
  • Reactive programming support with WebFlux
  • Cloud-native deployment with Docker and Kubernetes readiness
  • Comprehensive testing framework setup

🏗️ Enterprise Architecture Features

  • Microservices Design - Scalable, maintainable service architecture
  • Multi-Tenant Support - Isolated data and operations per tenant
  • Database Integration - JPA/Hibernate with PostgreSQL support
  • API Documentation - OpenAPI 3.0 with Swagger UI
  • Health Monitoring - Spring Boot Actuator with Prometheus metrics
  • Professional Logging - Structured logging with correlation IDs

🚀 Quick Start

Prerequisites

  • Java 17+
  • Maven 3.8+
  • Docker & Docker Compose

1. Clone and Setup

git clone https://github.com/li000592/telecom-service-platform
cd telecom-service-platform

2. Start Infrastructure (Optional - for full stack)

# Start PostgreSQL, Redis, Kafka
docker-compose up -d postgres redis kafka zookeeper

3. Run the Application

# Development mode with H2 in-memory database
cd device-service
mvn spring-boot:run -Dspring-boot.run.profiles=dev

4. Verify Installation

# Health check
curl http://localhost:8081/device-service/actuator/health

# Expected response: {"status":"UP"}

📋 API Documentation

Base URL

http://localhost:8081/device-service

Interactive Documentation

Core Endpoints

Device Management

# Get all devices for a tenant
GET /api/v1/devices
Headers: X-Tenant-ID: tenant-1

# Get specific device
GET /api/v1/devices/{deviceId}
Headers: X-Tenant-ID: tenant-1

# Create new device
POST /api/v1/devices
Headers: X-Tenant-ID: tenant-1, Content-Type: application/json
Body: {
  "deviceId": "router-001",
  "deviceName": "Core Router 1",
  "deviceType": "ROUTER",
  "ipAddress": "192.168.1.1",
  "location": "DataCenter-1",
  "vendor": "Cisco",
  "model": "ISR4431"
}

Health & Monitoring

# Application health
GET /actuator/health

# Metrics (Prometheus format)
GET /actuator/prometheus

# Application info
GET /actuator/info

🧪 Testing the Application

1. Create a Test Device

curl -X POST "http://localhost:8081/device-service/api/v1/devices" \
  -H "X-Tenant-ID: tenant-1" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "router-001",
    "deviceName": "Core Router 1",
    "deviceType": "ROUTER",
    "ipAddress": "192.168.1.1",
    "location": "DataCenter-1",
    "vendor": "Cisco",
    "model": "ISR4431"
  }'

2. Retrieve Devices

# Get all devices
curl -H "X-Tenant-ID: tenant-1" \
  "http://localhost:8081/device-service/api/v1/devices"

# Get specific device
curl -H "X-Tenant-ID: tenant-1" \
  "http://localhost:8081/device-service/api/v1/devices/router-001"

3. Test Multi-Tenancy

# Different tenant sees no devices
curl -H "X-Tenant-ID: tenant-2" \
  "http://localhost:8081/device-service/api/v1/devices"

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        Frontend (Future)                        │
└─────────────────────┬───────────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────────┐
│                    API Gateway (Future)                         │
└─────────┬─────────┬─────────┬─────────┬─────────┬───────────────┘
          │         │         │         │         │
          ▼         ▼         ▼         ▼         ▼
    ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
    │ Device  │ │Service  │ │Service  │ │Network  │ │ Tenant  │
    │Service  │ │Assurance│ │Fulfill. │ │Inventory│ │ Service │
    │ (Demo)  │ │(Future) │ │(Future) │ │(Future) │ │(Future) │
    └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
          │         │         │         │         │
          └─────────┴─────────┴─────────┴─────────┘
                            │
                    ┌───────▼───────┐
                    │ Message Queue │
                    │ (Kafka-Ready) │
                    └───────────────┘

🗂️ Project Structure

telecom-service-platform/
├── device-service/                    # Network Device Management Service
│   ├── src/main/java/
│   │   └── com/telecom/platform/device/
│   │       ├── DeviceServiceApplication.java
│   │       ├── controller/
│   │       │   └── NetworkDeviceController.java
│   │       ├── domain/
│   │       │   ├── NetworkDevice.java
│   │       │   ├── DeviceType.java
│   │       │   └── DeviceStatus.java
│   │       └── repository/
│   │           └── NetworkDeviceRepository.java
│   ├── src/main/resources/
│   │   ├── application.yml
│   │   └── db/migration/
│   └── src/test/                      # Test classes
├── docker-compose.yml                 # Development infrastructure
├── pom.xml                           # Parent Maven configuration
├── Makefile                          # Build automation
└── README.md                         # This file

🔧 Configuration

Application Profiles

Development Profile (dev)

  • Database: H2 in-memory
  • Console: H2 console enabled at /h2-console
  • Logging: Debug level for application packages

Production Profile (prod)

  • Database: PostgreSQL
  • Caching: Redis integration
  • Messaging: Kafka integration
  • Logging: Info level

Environment Variables

Variable Description Default
DATABASE_URL PostgreSQL connection URL jdbc:postgresql://postgres:5432/telecom_platform
DATABASE_USERNAME Database username postgres
DATABASE_PASSWORD Database password postgres
KAFKA_BOOTSTRAP_SERVERS Kafka bootstrap servers kafka:9092
REDIS_HOST Redis host redis
REDIS_PORT Redis port 6379

🐳 Docker Deployment

Development Environment

# Start all infrastructure services
docker-compose up -d

# Build and run application
mvn clean package -DskipTests
java -jar device-service/target/device-service-1.0.0-SNAPSHOT.jar

Production Deployment

# docker-compose.yml includes:
# - PostgreSQL database
# - Redis cache
# - Apache Kafka messaging
# - Prometheus monitoring
# - Grafana dashboards

🧪 Testing

Running Tests

# Unit tests
mvn test

# Integration tests
mvn verify

# Test coverage report
mvn clean verify jacoco:report

Test Coverage

  • Target: 80%+ code coverage
  • Unit Tests: Service layer and controller logic
  • Integration Tests: End-to-end API testing
  • Database Tests: JPA repository testing

📊 Monitoring & Observability

Built-in Monitoring

  • Health Checks: /actuator/health
  • Metrics: /actuator/metrics
  • Prometheus: /actuator/prometheus
  • Application Info: /actuator/info

Database Management

🔒 Security Features

Multi-Tenant Security

  • Tenant Isolation: All data operations require tenant ID
  • Data Separation: Tenant-specific data access patterns
  • API Security: Header-based tenant identification

Future Security Enhancements

  • JWT-based authentication
  • Role-based access control (RBAC)
  • API rate limiting
  • Input validation and sanitization

📈 Performance & Scalability

Current Capabilities

  • Response Time: < 200ms for 95% of requests
  • Database: Optimized queries with proper indexing
  • Multi-tenancy: Efficient tenant-based data access

Scalability Features

  • Stateless Design: Easy horizontal scaling
  • Database Connection Pooling: HikariCP optimization
  • Caching Ready: Redis integration prepared
  • Event-Driven Architecture: Kafka integration ready

🚀 Roadmap

Phase 1: Foundation ✅

  • Device Service with CRUD operations
  • Multi-tenant architecture
  • Database integration
  • API documentation
  • Health monitoring

Phase 2: Core Services (Next)

  • Service Assurance module
  • Service Fulfillment automation
  • Network Inventory management
  • API Gateway implementation
  • Kafka event streaming

Phase 3: Advanced Features

  • React TypeScript frontend
  • Machine Learning integration
  • Advanced security (JWT, RBAC)
  • Performance optimization

Phase 4: Production Ready

  • Kubernetes Helm charts
  • CI/CD pipeline
  • Load testing
  • Production monitoring

🛠️ Development

Prerequisites for Development

# Install required tools
brew install openjdk@17 maven docker

# Set JAVA_HOME
export JAVA_HOME=/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home

Local Development Setup

# Clone the repository
git clone <your-repo-url>
cd telecom-service-platform

# Start development environment
docker-compose up -d postgres redis kafka zookeeper

# Run application in development mode
cd device-service
mvn spring-boot:run -Dspring-boot.run.profiles=dev

Build Commands

# Clean build
mvn clean package

# Skip tests
mvn clean package -DskipTests

# Run with specific profile
mvn spring-boot:run -Dspring-boot.run.profiles=dev

# Generate test coverage report
mvn clean verify jacoco:report

🤝 Contributing

Code Style

  • Follow Google Java Style Guide
  • Use meaningful variable and method names
  • Write comprehensive JavaDoc for public APIs
  • Maintain 80%+ test coverage

Git Workflow

  1. Create feature branch: git checkout -b feature/description
  2. Make changes and write tests
  3. Run tests: mvn clean verify
  4. Commit with meaningful messages
  5. Create pull request

📚 Technology Stack

Backend

  • Java 17 - Modern JDK with latest features
  • Spring Boot 3.2.5 - Application framework
  • Spring Data JPA - Database abstraction layer
  • Spring Boot Actuator - Monitoring and management
  • H2 Database - Development database
  • PostgreSQL - Production database
  • Maven - Build and dependency management

Documentation & API

  • OpenAPI 3.0 - API specification
  • Swagger UI - Interactive API documentation
  • Spring Doc - Automatic API documentation generation

Development & Testing

  • JUnit 5 - Unit testing framework
  • Spring Boot Test - Integration testing
  • TestContainers - Database integration testing
  • Mockito - Mocking framework

Infrastructure (Ready for Integration)

  • Docker - Containerization
  • Apache Kafka - Event streaming
  • Redis - Caching layer
  • Prometheus - Metrics collection
  • Grafana - Monitoring dashboards

📄 License

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

Built with ❤️ by Haorong!