# talhayaseen57/blacksheep architecture

> Architecture diagram of the GitHub repository talhayaseen57/blacksheep, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/talhayaseen57/blacksheep
- Repository: https://github.com/talhayaseen57/blacksheep

## Overview

##### Project Type and Purpose
- BlackSheep is a full-stack, server-side rendered e-commerce web application built with Spring Boot (Java), Thymeleaf, and PostgreSQL.
- It follows the classic MVC (Model-View-Controller) layered architecture, with user-facing pages delivered via Thymeleaf templates and dynamic behavior via JavaScript.
- Persistence is handled via Spring Data JPA repositories to a PostgreSQL database. Security is managed with Spring Security. Deployed on Heroku using an embedded Tomcat.

##### File Structure Highlights
- src/main/java/com/blacksheep
- web: Controllers (CartController, ProductsController, PaymentController, etc.)
- service: Business logic services (ProductService, PaymentService, CustomerService, ProfileService)
- repositories: Spring Data JPA interfaces for domain entities (ProductRepository, OrderRepository, etc.)
- domain/POJOS: JPA Entities (Product, Order, Customer, Guest, Item, Profile) and form DTOs.
- security: Spring Security config and custom user details.
- exceptions: Custom exceptions for error handling.
- src/main/resources
- static: CSS, JS, images.
- templates: Thymeleaf templates for pages and error fragments.
- application.properties: Database & server config.
- database.sql: Initial schema and seed data.
- Procfile/pom.xml: Deployment config (Heroku) and build.

##### Main Components & Their Interactions
- Client Browser: Renders HTML/CSS/JS, initiates HTTP(S) requests (GET/POST).
- Web Server (Spring Boot/Tomcat): Receives requests, routes to Controllers.
- Controllers (MVC Layer):
- Validate input, delegate to Services, choose views.
- Service Layer:
- Encapsulates business rules, orchestrates transactions, calls Repositories.
- Repository Layer (Spring Data JPA):
- CRUD and query operations on PostgreSQL.
- Database (PostgreSQL): Stores domain data (products, orders, customers).
- Security Layer (Spring Security):
- Intercepts requests, enforces authentication/authorization, integrates with CustomerDetailsServiceImpl.
- Static Resource Handler:
- Serves CSS/JS/images directly.
- External Services:
- Heroku deployment platform.
- (Optionally) any external payment gateway invoked by PaymentService.

##### Architectural Patterns & Design Principles
- Layered Architecture (Controller → Service → Repository → Database).
- MVC for web interaction.
- Domain-Driven Design: Entities in domain package.
- Spring Security filter chain for authentication/authorization.
- Exception handling via @ControllerAdvice and custom exceptions.
- Separation of concerns: templates vs. static assets vs. business logic.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Browser layer
    subgraph "Client Browser"
        direction TB
        Templates["Thymeleaf Templates"]:::ui
        StaticAssets["Static Assets (CSS/JS/Images)"]:::static
    end

    %% Spring Boot Application
    subgraph "Spring Boot App"
        direction TB
        %% Controllers
        subgraph "Controllers" 
            direction TB
            CartController["CartController"]:::controller
            ProductsController["ProductsController"]:::controller
            PaymentController["PaymentController"]:::controller
            ProfileController["ProfileController"]:::controller
            LoginController["LoginController"]:::controller
            DashboardController["DashboardController"]:::controller
            ContactFormController["ContactFormController"]:::controller
        end

        %% Services
        subgraph "Service Layer"
            direction TB
            ProductService["ProductService"]:::service
            PaymentService["PaymentService"]:::service
            CustomerService["CustomerService"]:::service
            ProfileService["ProfileService"]:::service
            CustomerDetailsService["CustomerDetailsServiceImpl"]:::service
        end

        %% Repositories
        subgraph "Repository Layer"
            direction TB
            ProductRepo["ProductRepository"]:::repo
            OrderRepo["OrderRepository"]:::repo
            OrderItemRepo["OrderItemRepository"]:::repo
            CustomerRepo["CustomerRepository"]:::repo
            GuestRepo["GuestRepository"]:::repo
        end

        SecurityFilter["Spring Security Filter Chain"]:::security
        ExceptionHandler["@ControllerAdvice Exception Handler"]:::exception
        StaticHandler["Static Resource Handler"]:::static

        %% Main Application
        MainApp["BlackSheepApplication"]:::backend
        ServletInit["ServletInitializer"]:::backend
    end

    %% Database
    PostgreSQL[(PostgreSQL)]:::db

    %% External Services
    PaymentGateway["Payment Gateway"]:::external
    Heroku["Heroku Deployment"]:::external

    %% Connections
    Templates -->|"serves view"| Browser
    StaticAssets -->|"serves resources"| Browser
    Browser["User Browser"]:::ui -->|"HTTP Request"| CartController
    Browser -->|"HTTP Request"| ProductsController
    Browser -->|"HTTP Request"| PaymentController
    Browser -->|"HTTP Request"| ProfileController
    Browser -->|"HTTP Request"| LoginController
    Browser -->|"HTTP Request"| DashboardController
    Browser -->|"HTTP Request"| ContactFormController

    CartController -->|"calls"| ProductService
    ProductsController -->|"calls"| ProductService
    PaymentController -->|"calls"| PaymentService
    ProfileController -->|"calls"| ProfileService
    LoginController -->|"auth via"| CustomerDetailsService
    DashboardController -->|"calls"| CustomerService
    ContactFormController -->|"calls"| CustomerService

    ProductService -->|"reads/writes"| ProductRepo
    PaymentService -->|"reads/writes"| OrderRepo
    PaymentService -->|"reads/writes"| OrderItemRepo
    CustomerService -->|"reads/writes"| CustomerRepo
    CustomerService -->|"reads/writes"| GuestRepo

    ProductRepo -->|"JPA"| PostgreSQL
    OrderRepo -->|"JPA"| PostgreSQL
    OrderItemRepo -->|"JPA"| PostgreSQL
    CustomerRepo -->|"JPA"| PostgreSQL
    GuestRepo -->|"JPA"| PostgreSQL

    PaymentService -->|"calls"| PaymentGateway
    Heroku -->|"hosts "| MainApp

    %% Security and Exception
    SecurityFilter -->|intercepts| CartController
    SecurityFilter -->|intercepts| ProductsController
    SecurityFilter -->|intercepts| PaymentController
    SecurityFilter -->|intercepts| ProfileController
    SecurityFilter -->|intercepts| LoginController
    SecurityFilter -->|intercepts| DashboardController
    SecurityFilter -->|intercepts| ContactFormController

    CartController -->|handles errors via| ExceptionHandler
    ProductsController -->|handles errors via| ExceptionHandler
    PaymentController -->|handles errors via| ExceptionHandler

    %% Main App Initialization
    MainApp -->|boots| ServletInit
    ServletInit -->|initializes| SecurityFilter
    ServletInit -->|initializes| StaticHandler

    %% Click Events
    click Templates "https://github.com/talhayaseen57/blacksheep/tree/main/BlackSheep/src/main/resources/templates"
    click StaticAssets "https://github.com/talhayaseen57/blacksheep/tree/main/BlackSheep/src/main/resources/static"
    click MainApp "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/BlackSheepApplication.java"
    click ServletInit "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/ServletInitializer.java"
    click CartController "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/web/CartController.java"
    click ProductsController "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/web/ProductsController.java"
    click PaymentController "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/web/PaymentController.java"
    click ProfileController "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/web/ProfileController.java"
    click LoginController "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/web/LoginController.java"
    click DashboardController "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/web/DashboardController.java"
    click ContactFormController "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/web/ContactFormController.java"
    click ProductService "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/service/ProductService.java"
    click PaymentService "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/service/PaymentService.java"
    click CustomerService "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/service/CustomerService.java"
    click ProfileService "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/service/ProfileService.java"
    click CustomerDetailsService "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/service/CustomerDetailsServiceImpl.java"
    click ProductRepo "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/repositories/ProductRepository.java"
    click OrderRepo "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/repositories/OrderRepository.java"
    click OrderItemRepo "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/repositories/OrderItemRepository.java"
    click CustomerRepo "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/repositories/CustomerRepository.java"
    click GuestRepo "https://github.com/talhayaseen57/blacksheep/blob/main/BlackSheep/src/main/java/com/blacksheep/repositories/GuestRepository.java"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef controller fill:#FFE5B4,stroke:#333,stroke-width:1px
    classDef service fill:#FFF5BA,stroke:#333,stroke-width:1px
    classDef repo fill:#D3FFD3,stroke:#333,stroke-width:1px
    classDef security fill:#FFD1DC,stroke:#333,stroke-width:1px
    classDef exception fill:#FFC0CB,stroke:#333,stroke-width:1px
    classDef static fill:#E0FFFF,stroke:#333,stroke-width:1px
    classDef db fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef backend fill:#F0F0F0,stroke:#333,stroke-width:1px
```
