# teamsphereco/teamsphere-api architecture

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

- Interactive diagram: https://gitdiagram.com/teamsphereco/teamsphere-api
- Repository: https://github.com/teamsphereco/teamsphere-api

## Overview

##### Project type and purpose
- This is the backend service of Teamsphere, a chat application built with Spring Boot. It handles user authentication (JWT with Spring Security), one-on-one chat, profile image storage (Cloudflare Images), and sets the foundation for future group chat via STOMP over RabbitMQ. It’s packaged as a Docker container and orchestrated alongside MySQL, RabbitMQ, and an observability stack (Grafana, Loki, Promtail).

##### File structure
- Top-level “backend-service” contains a classic layered Spring Boot app:
- config (JWT, WebSocket, CORS, AppProperties)
- controllers (REST & WebSocket endpoints)
- services & impl (business logic)
- repository (Spring Data JPA)
- models (JPA entities)
- DTO & mappers (API payload mapping)
- filters (request logging, correlation IDs)
- Resources hold multiple YAML profiles (dev, local, prod) and bootstrap configuration.
- Root contains Docker Compose (mysql, rabbitmq), observability config folders (grafana, loki, promtail), and a Dockerfile under /images.
- CI pipelines live in .github/workflows.

##### Extract key architectural insights from README
- REST API for chat, JWT-secured endpoints
- STOMP/WebSocket support planned for group chat
- External dependencies: MySQL, RabbitMQ, Cloudflare Images
- Deployed on DigitalOcean via Docker Compose
- Observability via Loki/Promtail (logs) and Grafana (dashboards)

##### Key reminders
- Be exhaustive but avoid clutter—group closely related classes under layer containers.
- External dependencies and data flows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Clients["Clients (Web/Mobile UI)"]:::external

    %% Backend Service Layers
    subgraph "Teamsphere Backend Service"
        direction TB
        SecFilt["Security & Filter Chain"]:::internal
        REST["REST API Layer\n(Controllers)"]:::internal
        WS["WebSocket Layer\n(STOMP)"]:::internal
        Serv["Service Layer\n(Business Logic)"]:::internal
        Persist["Persistence Layer\n(JPA Repositories)"]:::internal
        DTO["DTOs & Mappers"]:::internal
        CF["External API Client\n(Cloudflare Images)"]:::external
        Config["Configurations & Profiles"]:::internal
    end

    %% Infrastructure
    subgraph "Stateful Services"
        direction TB
        DB["DB[(MySQL Database)]"]:::stateful
        RMQ["RabbitMQ Broker"]:::stateful
    end

    subgraph "Observability Stack"
        direction TB
        Promtail["Promtail"]:::obs
        Loki["Loki"]:::obs
        Grafana["Grafana"]:::obs
    end

    DigitalOcean["DigitalOcean\n(Hosting)"]:::infra

    %% Relationships
    Clients -->|HTTPS REST| REST
    Clients -->|WSS STOMP| WS
    SecFilt --> REST
    SecFilt --> WS
    REST --> Serv
    WS --> Serv
    Serv --> Persist
    Persist -->|JDBC TCP:3306| DB
    Serv -->|STOMP| RMQ
    Serv -->|HTTPS| CF
    Serv --> Promtail
    Promtail --> Loki
    Grafana --> Loki
    DigitalOcean --> Clients
    DigitalOcean --> DB
    DigitalOcean --> RMQ
    DigitalOcean --> Promtail
    DigitalOcean --> Grafana

    %% Click Events
    click REST "https://github.com/teamsphereco/teamsphere-api/tree/master/backend-service/src/main/java/co/teamsphere/api/controller"
    click WS "https://github.com/teamsphereco/teamsphere-api/blob/master/backend-service/src/main/java/co/teamsphere/api/config/WebSocketConfig.java"
    click WS "https://github.com/teamsphereco/teamsphere-api/blob/master/backend-service/src/main/java/co/teamsphere/api/controller/RealTimeMsgController.java"
    click SecFilt "https://github.com/teamsphereco/teamsphere-api/blob/master/backend-service/src/main/java/co/teamsphere/api/config/JWTTokenProvider.java"
    click SecFilt "https://github.com/teamsphereco/teamsphere-api/blob/master/backend-service/src/main/java/co/teamsphere/api/config/JWTTokenValidator.java"
    click SecFilt "https://github.com/teamsphereco/teamsphere-api/blob/master/backend-service/src/main/java/co/teamsphere/api/config/RSAConfig.java"
    click SecFilt "https://github.com/teamsphereco/teamsphere-api/blob/master/backend-service/src/main/java/co/teamsphere/api/config/JWTTokenConst.java"
    click SecFilt "https://github.com/teamsphereco/teamsphere-api/blob/master/backend-service/src/main/java/co/teamsphere/api/config/WebConfig.java"
    click SecFilt "https://github.com/teamsphereco/teamsphere-api/tree/master/backend-service/src/main/java/co/teamsphere/api/filters"
    click Serv "https://github.com/teamsphereco/teamsphere-api/tree/master/backend-service/src/main/java/co/teamsphere/api/services"
    click Serv "https://github.com/teamsphereco/teamsphere-api/tree/master/backend-service/src/main/java/co/teamsphere/api/services/impl"
    click Persist "https://github.com/teamsphereco/teamsphere-api/tree/master/backend-service/src/main/java/co/teamsphere/api/models"
    click Persist "https://github.com/teamsphereco/teamsphere-api/tree/master/backend-service/src/main/java/co/teamsphere/api/repository"
    click DTO "https://github.com/teamsphereco/teamsphere-api/tree/master/backend-service/src/main/java/co/teamsphere/api/DTO"
    click DTO "https://github.com/teamsphereco/teamsphere-api/tree/master/backend-service/src/main/java/co/teamsphere/api/DTOmapper"
    click CF "https://github.com/teamsphereco/teamsphere-api/blob/master/backend-service/src/main/java/co/teamsphere/api/services/CloudflareApiService.java"
    click CF "https://github.com/teamsphereco/teamsphere-api/blob/master/backend-service/src/main/java/co/teamsphere/api/services/impl/CloudflareApiServiceImpl.java"
    click Config "https://github.com/teamsphereco/teamsphere-api/blob/master/backend-service/src/main/resources/application.yml"
    click Config "https://github.com/teamsphereco/teamsphere-api/blob/master/backend-service/src/main/resources/application-dev.yml"
    click Config "https://github.com/teamsphereco/teamsphere-api/blob/master/backend-service/src/main/resources/application-local.yml"
    click Config "https://github.com/teamsphereco/teamsphere-api/blob/master/backend-service/src/main/resources/application-prod.yml"
    click Config "https://github.com/teamsphereco/teamsphere-api/blob/master/backend-service/src/main/resources/bootstrap.yml"
    click Config "https://github.com/teamsphereco/teamsphere-api/tree/master/backend-service/src/main/java/co/teamsphere/api/config/properties"
    click RMQ "https://github.com/teamsphereco/teamsphere-api/blob/master/docker-compose.yml"
    click DigitalOcean "https://github.com/teamsphereco/teamsphere-api/tree/master/images/Dockerfile"
    click Grafana "https://github.com/teamsphereco/teamsphere-api/blob/master/grafana/config/grafana-datasources.yaml"
    click Loki "https://github.com/teamsphereco/teamsphere-api/blob/master/loki/config/loki-config.yaml"
    click Promtail "https://github.com/teamsphereco/teamsphere-api/blob/master/promtail/config/promtail-config.yaml"
    click .github "https://github.com/teamsphereco/teamsphere-api/blob/master/.github/workflows/dev-pipeline-backend.yml"
    click .github "https://github.com/teamsphereco/teamsphere-api/blob/master/.github/workflows/general-checks.yml"
    click .github "https://github.com/teamsphereco/teamsphere-api/blob/master/.github/workflows/prod-pipeline-backend.yml"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#3399ff,color:#000
    classDef stateful fill:#d4edda,stroke:#28a745,color:#000
    classDef external fill:#ffe5cc,stroke:#ff9933,color:#000
    classDef obs fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef infra fill:#f0f0f0,stroke:#888888,color:#000
```
