# thongdanghoang/greenbuildings architecture

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

- Interactive diagram: https://gitdiagram.com/thongdanghoang/greenbuildings
- Repository: https://github.com/thongdanghoang/greenbuildings

## Overview

##### Project’s Nature
- The project is a capstone system (SEP490) with multiple modular components that together form a complete enterprise solution.
- It includes backend Java services (using Spring and Gradle), a frontend Angular application, an Identity Provider (IDP) for authentication/authorization, and an infrastructure layer (with Docker Compose, Postgres, and keycloak test container integration).
- There is also a “commons” module that contains shared libraries (API, validators, DTOs, and Spring framework implementations) to be used across the enterprise and IDP services.
- There is evidence of event-driven design (Kafka consumers/producers) and integration with external providers (geocoding, exchange rate API, payment adapters, Minio file storage, Redis cache).

##### File Structure
- Top-level directories indicate a multi-module/multi-service design:
- sep490-commons: Contains common code split into an “api” portion and “springfw-impl” (for common configurations, mapping, security, exception handling, and utilities).
- sep490-enterprise: Contains the main business logic with entities, controllers (REST endpoints), services, repositories, mappers, DTOs, and event handling. This module also includes database migration scripts and configuration files (application.yml, log4j2-spring.xml, etc.).
- sep490-frontend: An Angular-based frontend project that implements several modules such as admin, authorization, enterprise, and more. It includes routing, theming (Tailwind, PrimeNG), and client-side components.
- sep490-idp: A dedicated Identity Provider responsible for authentication and authorization. This module features controllers, DTOs, service implementations, password/OTP flow, key configuration (for JWT, passkeys), and related email templates.
- sep490-infrastructure: Contains Docker Compose files, configuration for external infrastructure like PostgreSQL, Keycloak test container providers, and initialization scripts.
- There is evidence of layered architecture in the backend: controllers (REST), services (business logic), mappers and DTOs (data transformations), repositories (data persistence), and configurations (security, caching, etc.).

- Frontend (sep490-frontend): Angular application consisting of multiple modules (admin, authorization, enterprise, dev, etc.) that interact with backend services.
- Backend Enterprise Service (sep490-enterprise): Contains the core business logic, REST controllers, services for enterprise operations, adapters for external integration (geocoding, payment, exchange rates, etc.), and event producers/consumers for asynchronous operations.
- Identity Provider Service (sep490-idp): Manages authentication flows (form login, passkeys, OTP), user management, and authorization. This component interacts with user repositories, mailing services, and produces security tokens.
- Commons/Shared Library (sep490-commons): A supporting layer providing common utilities, API DTOs, common validators, and Spring framework implementations to reduce code duplication.
- Infrastructure: Includes shared database instances (PostgreSQL), caching services (Redis), object storage (via Minio), and external authentication integration (Keycloak test container) – all orchestrated using Docker Compose (sep490-infrastructure).

b. Relationships and Data Flow:
- The Frontend communicates via HTTP/REST interfaces with both the Enterprise Service and the Identity Provider.
- The Enterprise Service leverages the Commons module for shared business logic and integrations.
- The Identity Provider works independently but can share user identity and security context information with the Enterprise Service.
- External adapters (geocoding, currency conversion, payment, etc.) within the Enterprise Service connect to third-party services to retrieve or process data.
- Asynchronous communication channels (using Kafka) can be represented for event-driven interactions, such as sending enterprise events between modules.
- Infrastructure components (database, Redis, Minio) are supportive services that both the Enterprise and Identity modules use.

c. Architectural Patterns:
- Layered Architecture: Clearly differentiate between presentation (REST controllers, Angular components), application (services and business logic), data access (repositories), and cross-cutting concerns (security, validation, exception handling).
- Modular and Reusable Components: The separation into commons, enterprise, and idp encourages reuse and separation of concerns.
- Event-Driven Design: Use of Kafka events for asynchronous processing and eventual consistency.
- Containerization & Infrastructure as Code: Docker Compose orchestration along with infrastructure configuration under sep490-infrastructure.

d. Technologies:
- Frontend: Angular, Typescript, Tailwind CSS, PrimeNG.
- Backend: Java (Spring Boot), Gradle, REST, Kafka for messaging.
- Identity: Spring-based identity management, JWT, passkey support, email integration.
- Databases and Caching: PostgreSQL (within migration scripts) and Redis.
- External Services: Integration with external APIs (geocoding, exchange rate, payment gateways), file storage via Minio.
- Infrastructure: Docker, Docker Compose, Keycloak testing provider.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        FE["Angular Frontend (sep490-frontend)"]:::frontend
    end

    %% Backend Services Layer
    subgraph "Backend Services"
        ES["Enterprise Service (sep490-enterprise)"]:::backend
        IDP["Identity Provider Service (sep490-idp)"]:::backend
        COMMONS["Commons Module/Shared Library (sep490-commons)"]:::commons
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Services"
        DB["PostgreSQL Database"]:::infrastructure
        REDIS["Redis Cache"]:::infrastructure
        MINIO["Minio Storage"]:::infrastructure
        KCTest["Keycloak Test Container"]:::infrastructure
        KAFKA["Kafka Messaging"]:::infrastructure
        INFRACOMP["Infrastructure Orchestration (sep490-infrastructure)"]:::infrastructure
    end

    %% Connections from UI to Backend
    FE -->|"HTTP/REST"| ES
    FE -->|"HTTP/REST(Auth)"| IDP

    %% Backend Services using Commons library
    ES -->|"uses"| COMMONS
    IDP -->|"uses"| COMMONS

    %% Enterprise External Integrations and Event-driven design
    ES -->|"externalAdapters"| KAFKA
    ES -->|"producesEvents"| KAFKA

    %% Backend Services Infrastructure Interactions
    ES -->|"DB/Cache"| DB
    ES -->|"cache/FileStorage"| REDIS
    ES -->|"fileStorage"| MINIO
    IDP -->|"DB/Cache"| DB
    IDP -->|"cacheAccess"| REDIS

    %% Infrastructure orchestration managing services
    INFRACOMP -->|"manages"| DB
    INFRACOMP -->|"manages"| REDIS
    INFRACOMP -->|"manages"| MINIO
    INFRACOMP -->|"manages"| KCTest

    %% Class Definitions for Colors
    classDef frontend fill:#A7C7E7,stroke:#000,stroke-width:2px;
    classDef backend fill:#F9D57A,stroke:#000,stroke-width:2px;
    classDef commons fill:#D3A4FF,stroke:#000,stroke-width:2px;
    classDef infrastructure fill:#C1E1C1,stroke:#000,stroke-width:2px;

    %% Click Events for Component Mapping
    click FE "https://github.com/thongdanghoang/greenbuildings/tree/main/sep490-frontend"
    click ES "https://github.com/thongdanghoang/greenbuildings/tree/main/sep490-enterprise"
    click IDP "https://github.com/thongdanghoang/greenbuildings/tree/main/sep490-idp"
    click COMMONS "https://github.com/thongdanghoang/greenbuildings/tree/main/sep490-commons"
    click INFRACOMP "https://github.com/thongdanghoang/greenbuildings/tree/main/sep490-infrastructure"
```
