# soffa-projects/foundation-java architecture

> Architecture diagram of the GitHub repository soffa-projects/foundation-java, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/soffa-projects/foundation-java
- Repository: https://github.com/soffa-projects/foundation-java

## Overview

##### Overall Project Purpose and Type
- This is a modular, multi-module infrastructure project that appears to provide a “foundation” for building services. It bundles multiple libraries and utilities (API annotations, auto-configurations, data integration, pubsub, email, storage, tracing, etc.) to enable building robust enterprise applications.
- The project is organized as several Gradle modules (e.g., foundation‑api, foundation‑application, foundation‑commons, foundation‑service, and multiple “foundation‑support” modules) alongside sample projects that demonstrate its usage.

##### Main Components
- Foundation API Module:
– Contains annotations (such as @ApplicationRequired, @Authenticated, @Store, etc.) and core models (like Request, Result, and various domain objects).
– Serves as the contract and metadata definition for the framework.
- Foundation Application Module:
– Provides core application logic including auto-configuration (e.g., Spring Boot integrations) and context management (e.g., request context, tenant handling).
– Defines service-related components like REST clients, security aspects, jobs, events, and feature integrations.
- Foundation Commons Module:
– Contains reusable utilities and helper classes (e.g., for HTTP, templates, object mapping, logging, and common operations).
- Foundation Service & Service Test Modules:
– Implements core service functionality, along with security, aspect-oriented programming (AOP) for cross-cutting concerns (logging, tenants, journal, etc.), and endpoints.
– Provides testing frameworks (with service tests and sample test cases) to ensure components work together.
- Foundation Support Modules:
– Data: Configures database connectivity, data repositories, and supports data layer operations including changelogs.
– Email: Integrates with email solutions through multiple adapters (fake, SendGrid, SMTP), including configuration classes.
– PubSub: Offers messaging capabilities with various adapters (Kafka, NATS, RabbitMQ, Simple pubsub) and related auto-configuration.
- Storage: Manages object storage integration, supporting third-party adapters (e.g., S3 and fake implementations).
- Tracing: Likely adds observability and tracing support to monitor the systems.
- (Foundation Support GraphQL is present but less detailed from the file tree – however, it fits the pattern as a feature extension.)
- Sample Applications:
– In the “samples” directory, there are several sample projects (service-data, service-pubsub, and service) which demonstrate how to bootstrap and integrate with the foundation libraries.

##### Component Relationships
- The core “foundation‑api” and “foundation‑commons” modules are the base libraries that are used by the “foundation‑application” and “foundation‑service” modules.
- “Foundation‑application” provides Spring Boot auto-configuration that automatically wires in components from “foundation‑support‑*” modules as well as data/security components.
- The “foundation‑service” module uses AOP aspects (found in its “aop” package) to apply cross-cutting concerns across service operations.
- Each “foundation‑support” module integrates with external systems (e.g., databases, email, pubsub, storage) and provides configuration and adapter implementations that plug into the core.
- The samples demonstrate how an end application would assemble these modules and rely on the auto-configuration provided by the framework.

##### Architectural Patterns and Technologies
- Layered Architecture: Clearly segregated layers such as API/contract, core application logic, cross-cutting concerns (AOP), and infrastructure integrations.
- Modularity: Each module has a focused responsibility. The use of Spring Boot auto-configuration indicates reliance on dependency injection and inversion of control.
- Aspect-Oriented Programming (AOP): For security, logging (LogContextAspect), and other cross-cutting concerns.
- Messaging/Integration Patterns: Use of pubsub paradigms (with adapters for Kafka, NATS, etc.) and the presence of auto configuration for event-driven communication.
- Testing: Inclusion of dedicated test modules and sample projects to validate integration and correctness.

##### Instructing the Principal Software Engineer
- Call-outs for technologies and design patterns like Spring Boot auto configuration, AOP aspects, and dependency injection.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Base Layer"
        api["Foundation API Module"]:::base
        commons["Foundation Commons Module"]:::base
    end

    subgraph "Core Application Layer"
        app["Foundation Application Module"]:::core
    end

    subgraph "Service Layer"
        service["Foundation Service Module"]:::service
        test["Service Test Module"]:::service
    end

    subgraph "Support Layer"
        data["Foundation Support Data Module"]:::support
        email["Foundation Support Email Module"]:::support
        pubsub["Foundation Support PubSub Module"]:::support
        storage["Foundation Support Storage Module"]:::support
        tracing["Foundation Support Tracing Module"]:::support
        graphql["Foundation Support GraphQL Module"]:::support
    end

    subgraph "Sample Applications"
        sample["Sample Applications"]:::sample
    end

    %% Connections between layers
    app -->|"depends_on"| api
    app -->|"depends_on"| commons

    service -->|"uses"| api
    service -->|"uses"| commons

    %% Auto-configuration wiring from Core Application to Support modules
    app -->|"auto_configures"| data
    app -->|"auto_configures"| email
    app -->|"auto_configures"| pubsub
    app -->|"auto_configures"| storage
    app -->|"auto_configures"| tracing
    app -->|"auto_configures"| graphql

    %% Service layer integration with support modules
    service -->|"integrates"| data
    service -->|"integrates"| email
    service -->|"integrates"| pubsub
    service -->|"integrates"| storage
    service -->|"integrates"| tracing
    service -->|"integrates"| graphql

    %% Sample applications demonstrate usage of core modules
    sample -->|"demonstrates"| app
    sample -->|"demonstrates"| service

    %% Click Events for components
    click api "https://github.com/soffa-projects/foundation-java/tree/legacy/foundation-api/src/main/java/io/soffa/foundation/annotations"
    click app "https://github.com/soffa-projects/foundation-java/blob/legacy/foundation-application/src/main/java/ext/springboot/FoundationAppAutoConfiguration.java"
    click commons "https://github.com/soffa-projects/foundation-java/tree/legacy/foundation-commons/src/main/java/io/soffa/foundation/commons"
    click service "https://github.com/soffa-projects/foundation-java/tree/legacy/foundation-service/src/main/java/io/soffa/foundation/service/core/aop"
    click test "https://github.com/soffa-projects/foundation-java/tree/legacy/foundation-service-test/src/main/java/io/soffa/foundation/test"
    click data "https://github.com/soffa-projects/foundation-java/tree/legacy/foundation-support-data/src/main/java/io/soffa/foundation/service/data"
    click email "https://github.com/soffa-projects/foundation-java/tree/legacy/foundation-support-email/src/main/java/io/soffa/foundation/support/email"
    click pubsub "https://github.com/soffa-projects/foundation-java/tree/legacy/foundation-support-pubsub/src/main/java/io/soffa/foundation/service/pubsub"
    click storage "https://github.com/soffa-projects/foundation-java/tree/legacy/foundation-support-storage/src/main/java/io/soffa/foundation/service/storage"
    click tracing "https://github.com/soffa-projects/foundation-java/tree/legacy/foundation-support-tracing"
    click graphql "https://github.com/soffa-projects/foundation-java/tree/legacy/foundation-support-graphql"
    click sample "https://github.com/soffa-projects/foundation-java/tree/legacy/samples"

    %% Styles for color coding
    classDef base fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef core fill:#A9DFBF,stroke:#239B56,stroke-width:2px;
    classDef service fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef support fill:#F5CBA7,stroke:#DC7633,stroke-width:2px;
    classDef sample fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
```
