Backend Architecture Index

Welcome to the Smart Supply Pro backend architecture documentation. This section provides comprehensive information about the system’s design, structure, and implementation patterns.

Overview

The Smart Supply Pro inventory management backend is built with Spring Boot and follows a layered architecture pattern with clear separation of concerns. The system manages supplier relationships, inventory items, stock history tracking, and advanced analytics.

Documentation Structure

Core Architecture

  • High-level Overview (English) - Comprehensive English overview of the backend architecture, layers, and key components
  • Überblick (German) - Deutschsprachige Zusammenfassung der Backend-Architektur
  • Architectural Diagrams - Visual diagrams showing system context, layers, deployment, request flows, database schema, security flows, and analytics architecture

Detailed Sections

  • Layers Architecture - Detailed breakdown of controller, service, repository, and data layers
  • Integration Architecture - Frontend-backend integration, API contracts, authentication flows, error handling, CORS configuration, and testing strategies
  • Repository Layer - Data access abstraction with 7 repositories (JpaRepository, custom analytics mixins, JPQL, native SQL)
  • Security Architecture - Authentication, authorization, OAuth2 integration, Docker security, and demo mode
  • Deployment & Infrastructure - Complete deployment pipeline from source to Fly.io, CI/CD automation, Docker image building, and operational procedures
  • Resources & Configuration - Spring Boot config files, profiles, logging, database configuration, Oracle Wallet integration
  • Data Models & Entities - Comprehensive entity documentation including Supplier, InventoryItem, StockHistory, and AppUser with relationships, lifecycle, usage examples, and testing
  • Enums Reference - Type-safe enumerations (Role, StockChangeReason, AuditSeverity) with business logic and validation
  • DTOs & Data Transfer Objects - Comprehensive DTO documentation with conventions, patterns, validation, authentication, pagination, and response shapes
  • Exception Architecture - Comprehensive exception handling with global handlers, domain exceptions, error response structure, HTTP mapping, security considerations, and best practices
  • Validation Framework - Multi-layer validation with JSR-380, custom validators, exception handling, and patterns
  • Testing Strategy - Unit testing, integration testing, security testing, and test patterns

Quick Navigation

By Audience

Developers implementing features: 1. Start with High-level Overview 2. Review Integration Architecture to understand frontend-backend communication 3. Review Layers Architecture 4. Explore relevant layer documentation (e.g., Data Models, Enums, DTOs) 5. Check Validation Framework for input handling 6. Review Exception Architecture for error handling patterns 7. Review Testing Strategy for test patterns

Frontend developers: 1. Start with Integration Architecture 2. Review API Contract & Endpoints 3. Study Error Handling Contract 4. Check Authentication Flow 5. Review CORS & Network 6. Setup Environments & URLs

DevOps / Infrastructure teams: 1. Review Deployment & Infrastructure 2. Check Resources & Configuration for environment setup 3. Review Security Architecture for OAuth2 and security configuration 4. Study Integration Architecture for network/CORS configuration

Security reviewers: 1. Start with Security Architecture 2. Review Exception Architecture - especially security exceptions and generic error messaging 3. Check Validation Framework

New team members: 1. Read High-level Overview first 2. Explore Layers Architecture to understand separation of concerns 3. Review Testing Strategy to learn team conventions

Key Architectural Principles

  1. Separation of Concerns - Clear boundaries between controller, service, repository, and data layers
  2. Dependency Injection - Spring framework manages all bean dependencies
  3. RESTful API Design - Standard HTTP methods and status codes for all endpoints
  4. Security First - OAuth2 authentication and role-based access control (RBAC)
  5. Data Validation - Multi-layer validation from DTO to entity level
  6. Exception Handling - Consistent error response format with appropriate HTTP status codes
  7. Testing - Comprehensive unit and integration tests with mocking patterns
  8. Documentation - Code comments, JavaDoc, and architectural documentation

Technology Stack

Component Technology Version
Framework Spring Boot 2.7.x
Language Java 11+
Database Oracle DB / PostgreSQL Latest
Build Tool Maven 3.x+
Testing JUnit 5, Mockito Latest
Security Spring Security, OAuth2 2.7.x
Containerization Docker Latest

Getting Started

  1. Clone the repository and navigate to the root directory
  2. Review the High-level Overview to understand the big picture
  3. Examine the Layers Architecture to learn component interactions
  4. Explore the code in /src/main/java/com/smartsupplypro/inventory/
  5. Check tests in /src/test/java/ to understand testing patterns
  6. Deploy locally using the Deployment Guide

Recent Updates

  • Enhanced backend architecture documentation with comprehensive guides
  • Improved test documentation with JavaDoc and inline comments
  • Expanded API reference with all 45 endpoints documented
  • Enhanced CI/CD pipeline with improved coverage reporting

Last updated: November 2024