# gui-ferreiraa/sustentify-app architecture

> Architecture diagram of the GitHub repository gui-ferreiraa/sustentify-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gui-ferreiraa/sustentify-app
- Repository: https://github.com/gui-ferreiraa/sustentify-app

## Overview

##### Project type and purpose
- This is a full-stack, microservices-style platform (“Sustentify”) for sustainable waste disposal and product exchange.
- It consists of three main services:
- A web UI (Angular) in the `web` folder.
- A Java Spring Boot backend API in `server`.
- A Node.js-based chat/assistant service in `chat`.
- It relies on external services: MySQL, Redis, Cloudinary (image hosting), SMTP for email, and optional LLM engines (via Ollama/Langfuse) for the assistant.

##### File structure
- Top-level service directories:
- `web` – Angular 14+ SPA with components, services, guards, interceptors, and its own Dockerfile + Nginx config.
- `server` – Spring Boot app following layered (Controller → Service → Repository) and MVC patterns, plus infra for database migrations, caching, messaging, security.
- `chat` – Node.js microservice with controllers, services, factories, Dockerfiles, and support for multiple LLM providers via `docker-compose.langfuse.yaml` and `docker-compose.ollama.yaml`.
- `infra` holds shared Docker Compose files, network setup, monitoring (Prometheus, Jaeger), and deployment scripts.
- `.github/workflows` defines CI/CD pipelines to build, push images to Docker Hub or deploy to a VPS.

##### Key README insights
- Environment variables cover ports, DB, Redis, JWT, CORS, Cloudinary, SMTP.
- Instructions to start individual services or the full stack via Docker Compose.
- Two Docker networks: `assistant-network` (for `chat`) and `server-network` (for `server` + `web` + infra).

a. Main components
- Browser / User → Angular Web App
- Angular Web App (Nginx container)
- Backend API (Spring Boot container)
- Chat Assistant API (Node.js container)
- Data stores: MySQL container, Redis container
- External services: Cloudinary API, SMTP server, LLM Provider(s)
- Observability: Prometheus, Jaeger, Grafana (optional)
- CI/CD Pipelines (GitHub Actions)
b. Relationships & data flows
- User’s browser ↔︎ Web App (HTTP)
- Web App → Backend API (REST + JWT)
- Backend → MySQL (JDBC) & Redis (cache)
- Backend → Cloudinary (upload/download)
- Backend → SMTP (send emails)
- Web App → Chat Assistant API (WebSocket or HTTP)
- Chat Assistant ↔︎ LLM engines (via Docker Compose)
- All services registered for tracing → Jaeger; metrics scraped by Prometheus
c. Architectural patterns & principles
- Layered MVC in Spring Boot (Controllers → Services → Repositories)
- Angular module-component-service separation, guard-interceptor pattern
- Microservices with discrete Docker Compose files, isolated networks
- CI/CD pipelines for automated build/test/deploy
- Externalize configuration via environment variables
- Observability via distributed tracing & metrics
d. Key technologies & libraries
- Frontend: Angular, NgRx (if used), Nginx
- Backend: Spring Boot, Spring Security (JWT), JPA/Hibernate, Flyway (DB migrations), Spring Cache (Redis), Cloudinary SDK, SMTP JavaMail
- Chat: Node.js, Express (controllers/services), Langfuse/Ollama connectors
- Infra: Docker, Docker Compose, Prometheus, Jaeger, GitHub Actions

##### Final advice
- Environment boundaries: Docker network separations, service-to-service TTLs, and load balancing (if any).
- Don’t omit security flows: where JWTs are issued, validated, and passed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    direction TB

    %% User
    User["User Browser"]:::external

    %% Web Service
    subgraph "Web Service"
        WebUI["Angular Web UI"]:::frontend
        Nginx["Nginx Proxy"]:::frontend
    end

    %% Backend Service
    subgraph "Server Service"
        SpringBoot["Spring Boot API"]:::backend
    end

    %% Assistant Service
    subgraph "Assistant Service"
        ChatAPI["Chat Assistant API"]:::assistant
    end

    %% Data Layer
    subgraph "Data Layer"
        MySQL["MySQL Database"]:::datastore
        Redis["Redis Cache"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        Cloudinary["Cloudinary API"]:::external
        SMTP["SMTP Email"]:::external
        LLM["LLM Provider"]:::external
    end

    %% Observability & Infra
    subgraph "Observability & Infra"
        Prometheus["Prometheus"]:::observability
        Jaeger["Jaeger"]:::observability
    end

    %% CI/CD
    subgraph "CI/CD Pipelines"
        CICD["GitHub Actions"]:::cicd
    end

    %% Connections
    User -->|"HTTP"| Nginx
    Nginx -->|"serves SPA"| WebUI
    WebUI -->|"REST + JWT"| SpringBoot
    WebUI -->|"WebSocket/HTTP"| ChatAPI

    SpringBoot -->|"JDBC"| MySQL
    SpringBoot -->|"Cache"| Redis
    SpringBoot -->|"Upload/Download"| Cloudinary
    SpringBoot -->|"Send Emails"| SMTP

    ChatAPI -->|"Query"| LLM

    SpringBoot -->|Tracing & Metrics| Jaeger
    ChatAPI -->|Tracing & Metrics| Jaeger
    WebUI -->|Metrics| Prometheus
    SpringBoot -->|Metrics| Prometheus
    ChatAPI -->|Metrics| Prometheus

    CICD -->|"build & deploy"| WebUI
    CICD -->|"build & deploy"| SpringBoot
    CICD -->|"build & deploy"| ChatAPI

    %% Click Events
    click WebUI "https://github.com/gui-ferreiraa/sustentify-app/tree/main/web/"
    click Nginx "https://github.com/gui-ferreiraa/sustentify-app/blob/main/web/nginx.conf"
    click SpringBoot "https://github.com/gui-ferreiraa/sustentify-app/tree/main/server/src/main/java/com/sustentify/sustentify_app"
    click ChatAPI "https://github.com/gui-ferreiraa/sustentify-app/tree/main/chat/"
    click Prometheus "https://github.com/gui-ferreiraa/sustentify-app/blob/main/infra/docker/config/prometheus.yml"
    click Jaeger "https://github.com/gui-ferreiraa/sustentify-app/blob/main/infra/docker/config/jaeger-ui.json"
    click CICD "https://github.com/gui-ferreiraa/sustentify-app/tree/main/.github/workflows/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#66b0ff
    classDef backend fill:#d4edda,stroke:#60c470
    classDef assistant fill:#ffe5b4,stroke:#ffb347
    classDef datastore fill:#e2e3e5,stroke:#b5b5b7
    classDef external fill:#f8d7da,stroke:#f28c8c
    classDef observability fill:#fff3cd,stroke:#ffe066
    classDef cicd fill:#fff3cd,stroke:#ffe066
```
