Skip to content

index.md

Latest commit

 

History

History
394 lines (317 loc) · 15.1 KB

index.md

File metadata and controls

394 lines (317 loc) · 15.1 KB

Java Spring Boot REST API Boilerplate - Project Overview

AI Context: This is the single source of truth for project overview. For current status: see docs/status/progress.yaml For implementation details: see docs/architecture/overview.md

Project Overview

A production-ready Java Spring Boot boilerplate for building scalable REST APIs with enterprise-grade patterns, comprehensive security, and AI-friendly architecture principles.

Mission Statement

Provide a robust, maintainable foundation for Java Spring Boot REST API development that follows best practices, implements proven architectural patterns, and accelerates time-to-market for enterprise applications.

Target Audience

  • Backend developers building REST APIs
  • Development teams adopting Spring Boot
  • Organizations requiring enterprise-grade API infrastructure
  • Developers learning Spring Boot best practices

Quick Start

  1. Setup: See docs/guides/getting-started.md for environment setup
  2. Status: Check docs/status/progress.yaml for current progress
  3. Getting Started: Review docs/guides/getting-started.md for quick start guide
  4. Standards: Follow standards/coding.md for development guidelines

Tech Stack

  • Runtime: Java 21 LTS
  • Framework: Spring Boot 3.x
  • Build Tool: Maven
  • Database: PostgreSQL (default), configurable for MySQL/H2
  • ORM: Spring Data JPA with Hibernate
  • Authentication: Spring Security with JWT
  • API Documentation: Springdoc OpenAPI (Swagger)
  • Caching: Redis (distributed), Caffeine (local)
  • Messaging: Apache Kafka, RabbitMQ
  • Testing: JUnit 5, Mockito, Spring Boot Test
  • Deployment: Docker, Kubernetes
  • Monitoring: Spring Boot Actuator, Micrometer

Project Structure

backend-java-spring-boot/
├── .ai/                    # AI-specific configuration
│   ├── context.yaml       # Master context file
│   ├── mcp-config.json    # MCP server configuration
│   └── agent-instructions.md # AI behavior guidelines
├── docs/                   # Project documentation
│   ├── index.md           # This file - single entry point
│   ├── status/            # Current state only
│   │   ├── progress.yaml  # Machine-readable status
│   │   └── priorities.md  # Current priorities only
│   ├── architecture/      # Technical implementation (planned)
│   │   ├── overview.md    # System architecture (planned)
│   │   ├── database.md    # Data model (planned)
│   │   ├── api.md         # API specifications (planned)
│   │   └── security.md    # Security architecture (planned)
│   ├── guides/            # How-to documentation
│   │   ├── getting-started.md  # Getting started guide
│   │   ├── setup.md       # Environment setup (planned)
│   │   └── deployment.md  # Deployment processes (planned)
│   ├── templates/         # Documentation templates
│   ├── session-management/ # AI session management
│   └── _working/          # Temporary work files
├── standards/              # Immutable standards
│   ├── coding.md          # Code conventions
│   ├── patterns.md        # Architectural patterns
│   ├── business-rules.md  # Domain logic
│   └── documentation.md   # Documentation standards
├── rules/                  # Spring Boot specific rules
│   ├── java-spring-boot-rules.md
│   └── questions.md
└── src/                    # Application source code
    ├── main/
    │   ├── java/
    │   │   └── com/company/project/
    │   │       ├── config/
    │   │       ├── controller/
    │   │       ├── service/
    │   │       ├── repository/
    │   │       ├── model/
    │   │       ├── exception/
    │   │       ├── security/
    │   │       └── util/
    │   └── resources/
    │       ├── application.yml
    │       ├── application-dev.yml
    │       ├── application-prod.yml
    │       └── db/migration/
    └── test/
        └── java/

Current Status

  • Phase: Boilerplate Setup
  • Completion: 20%
  • Last Updated: 2025-10-08
  • Next Priority: Core project structure and example implementations

Recent Achievements

  • ✅ Documentation architecture established
  • ✅ Standards and patterns defined
  • ✅ AI-friendly structure implemented

Current Focus

  • 🔄 Core Maven project setup
  • 🔄 Example controller/service/repository implementations
  • 🔄 Security configuration with JWT

Key Features

Core Features

  • Layered Architecture: Clean separation with Controller/Service/Repository/Model layers
  • RESTful API: Complete REST API implementation with best practices
  • Security: Spring Security with JWT authentication and role-based authorization
  • Data Persistence: Spring Data JPA with PostgreSQL, migration support with Flyway
  • API Documentation: Interactive Swagger UI with Springdoc OpenAPI
  • Validation: Bean Validation with custom validators
  • Exception Handling: Global exception handling with @ControllerAdvice
  • Logging: SLF4J with Logback, structured logging patterns

Advanced Features

  • Caching: Multi-level caching with Redis and Caffeine
  • Async Processing: @Async support with custom thread pools
  • Message Queuing: Kafka and RabbitMQ integration patterns
  • Scheduled Tasks: @Scheduled tasks with configuration
  • File Upload/Download: File handling with validation
  • Email Service: Async email sending with templates
  • WebSockets: Real-time communication patterns
  • Event-Driven: Spring Events for decoupled communication

Development Features

  • Testing: Comprehensive test patterns (unit, integration, e2e)
  • Monitoring: Spring Boot Actuator with custom metrics
  • Docker Support: Docker and Docker Compose configurations
  • Database Migrations: Flyway for version-controlled schema changes
  • Environment Profiles: Dev, staging, production configurations
  • Code Quality: Checkstyle, SpotBugs, PMD configurations

Architecture Highlights

Design Principles

  • Single Source of Truth: Each piece of information exists in exactly one location
  • AI-First Design: Structure optimized for AI agent consumption
  • Progressive Disclosure: Information layers from high-level to implementation details
  • Machine-Readable Data: Status and progress in structured formats
  • SOLID Principles: Clean architecture with high cohesion, low coupling
  • Layered Architecture: Clear separation of concerns

Key Architectural Decisions

  1. Layered Architecture Pattern

    • Rationale: Clear separation of concerns, maintainability, testability
    • Layers: Controller → Service → Repository → Model
    • Benefits: Easy to understand, test, and modify

  2. DTO Pattern for API Contracts

    • Rationale: Decouple internal entities from API contracts
    • Implementation: Separate request/response DTOs with MapStruct
    • Benefits: API versioning, security, flexibility

  3. JWT for Authentication

    • Rationale: Stateless authentication for scalability
    • Implementation: Spring Security with JWT tokens
    • Benefits: Scalable, mobile-friendly, microservices-ready

  4. PostgreSQL as Primary Database

    • Rationale: Enterprise-grade features, excellent Spring Boot support
    • Implementation: Spring Data JPA with Hibernate
    • Benefits: ACID compliance, JSON support, extensibility

Technology Choices

  • Java 21 LTS: Latest long-term support with modern features (records, pattern matching, text blocks)
  • Spring Boot 3.x: Latest stable version with improved performance and native compilation support
  • Maven: Industry-standard build tool with excellent Spring Boot integration
  • Springdoc OpenAPI: Modern, actively maintained OpenAPI/Swagger implementation
  • JUnit 5: Modern testing framework with improved features
  • Docker: Containerization for consistent deployment

Development Workflow

Getting Started

# Clone repository
git clone [repository-url]

# Navigate to project
cd backend-java-spring-boot

# Install dependencies
mvn clean install

# Run application
mvn spring-boot:run

# Access API documentation
# http://localhost:8080/swagger-ui.html

Development Standards

  • Code Style: Follow standards/coding.md
  • Architecture: Follow standards/patterns.md
  • Testing: Maintain 80%+ test coverage
  • Documentation: Update docs with code changes
  • Code Review: All changes require review

Available Maven Commands

mvn spring-boot:run     # Run application
mvn clean install       # Build project
mvn test                # Run tests
mvn verify              # Run tests with coverage
mvn javadoc:javadoc     # Generate JavaDoc
mvn checkstyle:check    # Check code style
mvn package             # Build JAR file

AI Development Assistance

MCP Integration

This project uses Model Context Protocol (MCP) for enhanced AI development assistance:

  • Documentation Server: Access to all project documentation
  • Standards Server: Access to coding standards and patterns
  • Rules Server: Access to Java/Spring Boot specific rules

AI Context Files

  • Master Context: .ai/context.yaml - Project metadata and status
  • Agent Instructions: .ai/agent-instructions.md - AI behavior guidelines
  • MCP Configuration: .ai/mcp-config.json - Server setup
  • Rules: rules/java-spring-boot-rules.md - Framework-specific rules

AI-Friendly Features

  • Single Source of Truth: No duplicate information across files
  • Machine-Readable Status: YAML-based progress tracking
  • Context Injection: AI instructions embedded in relevant sections
  • Progressive Disclosure: Information organized by detail level
  • Layered Architecture: Clear structure for AI understanding

Performance & Quality

Performance Targets

  • Response Time: < 200ms for 95th percentile
  • Throughput: 1000+ requests/second
  • Database Connection Pool: 20 connections
  • JVM Heap: 512MB-2GB (configurable)

Quality Metrics

  • Test Coverage: 80%+ code coverage
  • Code Quality: A-grade SonarQube rating
  • Security: OWASP Top 10 compliance
  • API Documentation: 100% endpoint coverage

Security Considerations

Authentication & Authorization

  • JWT Tokens: Stateless authentication with configurable expiration
  • Role-Based Access: ADMIN, CLIENT, AGENCY roles
  • Password Security: BCrypt hashing with salt
  • Session Management: Stateless with JWT

Data Protection

  • Input Validation: Bean Validation on all endpoints
  • SQL Injection Prevention: Parameterized queries with JPA
  • XSS Prevention: Output encoding
  • CORS: Configurable cross-origin policies

Compliance

  • OWASP Top 10: Protection against common vulnerabilities
  • GDPR: Data privacy and user rights support
  • Audit Logging: Complete audit trail

Deployment & Infrastructure

Environments

  • Development: H2 in-memory database, debug logging
  • Staging: PostgreSQL, info logging, similar to production
  • Production: PostgreSQL, optimized settings, error logging

Deployment Strategy

  • Docker: Containerized application
  • Kubernetes: Orchestration with deployment manifests
  • CI/CD: GitHub Actions / Jenkins pipeline
  • Blue-Green: Zero-downtime deployments

Infrastructure

  • Hosting: Cloud-agnostic (AWS, Azure, GCP)
  • Database: Managed PostgreSQL (RDS, Cloud SQL, etc.)
  • Caching: Managed Redis (ElastiCache, etc.)
  • Messaging: Managed Kafka/RabbitMQ

Monitoring & Observability

Application Monitoring

  • Metrics: Micrometer with Prometheus
  • Health Checks: Spring Boot Actuator endpoints
  • Logging: Structured logging with correlation IDs
  • Tracing: Distributed tracing with Sleuth/Zipkin

Infrastructure Monitoring

  • JVM Metrics: Memory, CPU, garbage collection
  • Database Metrics: Connection pool, query performance
  • API Metrics: Request count, response times, error rates

Alerting

  • Critical: System down, database unreachable
  • High: Error rate > 5%, response time > 1s
  • Medium: CPU > 80%, memory > 80%

Business Context

Use Cases

  • Building REST APIs for web/mobile applications
  • Microservices architecture
  • Enterprise backend systems
  • SaaS platform backends

Success Metrics

  • Developer Productivity: Reduce API development time by 50%
  • Code Quality: Maintain 80%+ test coverage
  • Performance: < 200ms average response time
  • Reliability: 99.9% uptime

Related Documentation

Core Documentation

Additional Resources (Planned)

Getting Help

For Developers

  • Start with this file for project overview
  • Check status files for current progress
  • Refer to docs/guides/getting-started.md for implementation details
  • Follow coding standards for development
  • Check rules files for Java/Spring Boot specifics

For AI Assistants

  • Check docs/status/progress.yaml for current status
  • Refer to standards/coding.md for code generation
  • Use rules/java-spring-boot-rules.md for framework specifics
  • Use context injection patterns for consistency

For Stakeholders

  • Review this overview for project understanding
  • Check status files for progress updates
  • Refer to architecture docs for technical decisions
  • Contact development team for specific questions

Contributing

Development Process

  1. Fork Repository: Create your own copy
  2. Create Branch: Use feature branch naming (feature/user-authentication)
  3. Follow Standards: Adhere to coding standards
  4. Write Tests: Maintain test coverage (80%+)
  5. Update Documentation: Keep docs current
  6. Submit PR: Request code review

Code Review Checklist

  • Code follows standards/coding.md
  • Tests added/updated with 80%+ coverage
  • JavaDoc updated for public APIs
  • OpenAPI annotations complete
  • No security vulnerabilities
  • Performance impact considered
  • Documentation updated

This documentation follows AI-friendly architecture principles with single source of truth, machine-readable data, and context injection patterns for optimal AI development assistance.

Last Updated: 2025-10-08