# pufa-computing/backend architecture

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

- Interactive diagram: https://gitdiagram.com/pufa-computing/backend
- Repository: https://github.com/pufa-computing/backend

## Overview

##### Component Relationships

- Bidirectional communication where applicable

##### External Services Integration
- External service connections:
- Mailgun for email services
- S3 for file storage
- Redis for rate limiting and caching

##### Security Components
- Security-related components:
- JWT token handling
- 2FA authentication
- RBAC permission checking
- Rate limiting mechanism

##### Additional Elements

Supporting components:
- Database migrations system
- File upload handling
- Image optimization pipeline
- Error handling flow

##### Specific Implementation Details

Important utilities and cross-cutting concerns:
- Custom response handling
- Error response formatting
- Token management
- File upload processing
- URL friendly conversion
- Image optimization

##### Layered architecture
- Clear separation between handlers, services, and data access
- Middleware chain

##### Security flow
- Detail the authentication and authorization flow
- Where RBAC checks occur

##### Data flow
- How requests flow from client to database
- Error handling paths

##### Scalability points
- Where rate limiting occurs
- Caching mechanisms
- Potential scaling points

Remember to include version information and any deployment-specific configurations that might affect the architecture.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        C[Client Requests]:::client
    end

    subgraph Gateway
        RL[Rate Limiter]:::security
        RH["Routes Handler"]:::gateway
        click RH "https://github.com/PUFA-Computing/backend/blob/master/api/routes.go"
        click RL "https://github.com/PUFA-Computing/backend/blob/master/internal/middleware/ratelimiter.go"

        MW[Middleware Chain]:::security
        click MW "https://github.com/PUFA-Computing/backend/blob/master/internal/middleware/middleware.go"
    end

    subgraph Handlers
        direction TB
        AH[Auth Handler]:::handler
        UH[User Handler]:::handler
        EH[Event Handler]:::handler
        NH[News Handler]:::handler
        ASH[Aspirations Handler]:::handler
        PH[Permission Handler]:::handler
        RLH[Role Handler]:::handler
        VH[Version Handler]:::handler

        click AH "https://github.com/PUFA-Computing/backend/blob/master/internal/handlers/auth/auth_handlers.go"
        click UH "https://github.com/PUFA-Computing/backend/blob/master/internal/handlers/user/user_handlers.go"
        click EH "https://github.com/PUFA-Computing/backend/blob/master/internal/handlers/event/event_handlers.go"
        click NH "https://github.com/PUFA-Computing/backend/blob/master/internal/handlers/news/news_handlers.go"
        click ASH "https://github.com/PUFA-Computing/backend/blob/master/internal/handlers/aspirations/aspirations_handlers.go"
        click PH "https://github.com/PUFA-Computing/backend/blob/master/internal/handlers/permission/permission_handlers.go"
        click RLH "https://github.com/PUFA-Computing/backend/blob/master/internal/handlers/role/role_handlers.go"
        click VH "https://github.com/PUFA-Computing/backend/blob/master/internal/handlers/version/version_handlers.go"
    end

    subgraph Services
        direction TB
        AS[Auth Service]:::service
        US[User Service]:::service
        ES[Event Service]:::service
        MS[Mail Service]:::service
        S3[S3 Service]:::service
        OTP[OTP Manager]:::service
        VS[Version Service]:::service

        click AS "https://github.com/PUFA-Computing/backend/blob/master/internal/services/auth_services.go"
        click US "https://github.com/PUFA-Computing/backend/blob/master/internal/services/user_services.go"
        click ES "https://github.com/PUFA-Computing/backend/blob/master/internal/services/event_services.go"
        click MS "https://github.com/PUFA-Computing/backend/blob/master/internal/services/mailgun_service.go"
        click S3 "https://github.com/PUFA-Computing/backend/blob/master/internal/services/s3_services.go"
        click OTP "https://github.com/PUFA-Computing/backend/blob/master/internal/services/otp_manager_service.go"
        click VS "https://github.com/PUFA-Computing/backend/blob/master/internal/services/version_services.go"
    end

    subgraph Security
        direction TB
        AU[Authentication]:::security
        TM[Token Management]:::security
        FA[2FA/TOTP]:::security
        PU[Permission Utils]:::security

        click AU "https://github.com/PUFA-Computing/backend/blob/master/pkg/utils/auth.go"
        click TM "https://github.com/PUFA-Computing/backend/blob/master/pkg/utils/token.go"
        click FA "https://github.com/PUFA-Computing/backend/blob/master/pkg/utils/totp.go"
        click PU "https://github.com/PUFA-Computing/backend/blob/master/pkg/utils/permission.go"
    end

    subgraph Utils
        direction TB
        FU[File Upload]:::util
        IO[Image Optimization]:::util
        RES[Response Handler]:::util
        ERR[Error Handler]:::util
        URL[URL Processor]:::util

        click FU "https://github.com/PUFA-Computing/backend/blob/master/pkg/utils/fileupload.go"
        click IO "https://github.com/PUFA-Computing/backend/blob/master/pkg/utils/optimize_image.go"
        click RES "https://github.com/PUFA-Computing/backend/blob/master/pkg/utils/custom_response.go"
        click ERR "https://github.com/PUFA-Computing/backend/blob/master/pkg/utils/error_response.go"
        click URL "https://github.com/PUFA-Computing/backend/blob/master/pkg/utils/url_friendly.go"
    end

    subgraph Database
        direction TB
        DB[(PostgreSQL)]:::database
        click DB "https://github.com/PUFA-Computing/backend/blob/master/internal/database/database.go"

        subgraph Models
            UM[User Model]:::model
            EM[Event Model]:::model
            NM[News Model]:::model
            PM[Permission Model]:::model
            RM[Role Model]:::model

            click UM "https://github.com/PUFA-Computing/backend/blob/master/internal/models/user.go"
            click EM "https://github.com/PUFA-Computing/backend/blob/master/internal/models/event.go"
            click NM "https://github.com/PUFA-Computing/backend/blob/master/internal/models/news.go"
            click PM "https://github.com/PUFA-Computing/backend/blob/master/internal/models/permission.go"
            click RM "https://github.com/PUFA-Computing/backend/blob/master/internal/models/role.go"
        end

        MIG[Migrations]:::database
        click MIG "https://github.com/PUFA-Computing/backend/tree/master/migrations/"
    end

    subgraph External
        MG[Mailgun]:::external
        S3S[S3 Storage]:::external
        RD[(Redis)]:::external
    end

    C --> RL
    RL --> RH
    RH --> MW
    MW --> Handlers
    Handlers --> Services
    Services --> Security
    Services --> Utils
    Services --> Database
    Services --> External

    classDef client fill:#E1F5FE,stroke:#01579B
    classDef gateway fill:#E8F5E9,stroke:#2E7D32
    classDef handler fill:#F3E5F5,stroke:#7B1FA2
    classDef service fill:#FFF3E0,stroke:#EF6C00
    classDef security fill:#FFEBEE,stroke:#C62828
    classDef util fill:#F3E5F5,stroke:#6A1B9A
    classDef database fill:#E8EAF6,stroke:#283593
    classDef external fill:#EFEBE9,stroke:#4E342E
    classDef model fill:#E0F2F1,stroke:#004D40
```
