# gideonag/photo-blog-app-backend architecture

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

- Interactive diagram: https://gitdiagram.com/gideonag/photo-blog-app-backend
- Repository: https://github.com/gideonag/photo-blog-app-backend

## Overview

##### Project type and purpose
- This is a Java-based, AWS Serverless backend for a photo-blog application.
- It exposes REST APIs (via API Gateway) that handle user auth, photo CRUD, processing, notifications, and disaster-recovery.
- Infrastructure is defined in a SAM template (template.yaml + samconfig.toml) and deployed via GitHub Actions (backend-deploy.yml).

##### Main components
a. Client layer
- Web or mobile client that calls REST endpoints
b. API Gateway
- Entry point routing HTTP requests to Lambda functions
c. AWS Lambda functions (grouped by domain)
- Auth domain: AuthHandler, CognitoService
- Photo domain: PhotoUploadHandler, PhotoQueryHandler, PhotoDeleteHandler, PhotoShareHandler, RecycleBinHandler
- Processing domain: ImageProcessingHandler, ImageProcessor, ProcessingRetryHandler
- Notifications domain: LoginNotificationHandler, ProcessingNotificationHandler, SystemAlertHandler, EmailService
- Disaster-recovery domain: BackupHandler, CognitoBackupHandler, RestoreHandler
d. AWS Services
- Amazon Cognito (user-pools & identity-pools) for authentication
- Amazon DynamoDB for metadata (tables for photos, users, statuses)
- Amazon S3 for storing photo files
- Amazon SNS & SES (via SNSUtil, SESUtil) for messaging and email alerts
e. Infrastructure / CI-CD
- AWS SAM (CloudFormation)
- GitHub Actions for build & deploy

##### Relationships and data-flow
- Client → API Gateway → specific Lambda
- Lambdas call utility classes (DynamoDBUtil, S3Util, SNSUtil, SESUtil)
- Write/read metadata in DynamoDB; read/write photo blobs in S3
- Processing Lambda triggered by S3 events (or invoked by API) and posts status updates
- Notification Lambdas subscribe to SNS topics to send emails via SES
- Backup/Restore Lambdas use DynamoDB and Cognito APIs for disaster-recovery

##### Architectural patterns & design principles
- Serverless microservices: each handler is a single-responsibility function
- Event-driven integrations: S3 events → processing, SNS topics → notifications
- Infrastructure-as-Code: SAM template defines all resources
- Domain grouping: handlers and models reflect clear Bounded Contexts

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Web/Mobile Client"]:::client
    API["API Gateway"]:::gateway

    subgraph "Auth Domain"
        AuthHandler["AuthHandler"]:::compute
        CognitoService["CognitoService"]:::auth
    end

    subgraph "Photo Domain"
        PhotoUploadHandler["PhotoUploadHandler"]:::compute
        PhotoQueryHandler["PhotoQueryHandler"]:::compute
        PhotoDeleteHandler["PhotoDeleteHandler"]:::compute
        PhotoShareHandler["PhotoShareHandler"]:::compute
        RecycleBinHandler["RecycleBinHandler"]:::compute
    end

    subgraph "Processing Domain"
        ImageProcessingHandler["ImageProcessingHandler"]:::compute
        ImageProcessor["ImageProcessor"]:::compute
        ProcessingRetryHandler["ProcessingRetryHandler"]:::compute
    end

    subgraph "Notifications Domain"
        LoginNotificationHandler["LoginNotificationHandler"]:::compute
        ProcessingNotificationHandler["ProcessingNotificationHandler"]:::compute
        SystemAlertHandler["SystemAlertHandler"]:::compute
        EmailService["EmailService"]:::messaging
    end

    subgraph "Disaster-Recovery Domain"
        BackupHandler["BackupHandler"]:::compute
        CognitoBackupHandler["CognitoBackupHandler"]:::compute
        RestoreHandler["RestoreHandler"]:::compute
    end

    subgraph "Utilities"
        DynamoDBUtil["DynamoDBUtil"]:::storage
        S3Util["S3Util"]:::storage
        SNSUtil["SNSUtil"]:::messaging
        SESUtil["SESUtil"]:::messaging
    end

    subgraph "AWS Services"
        Cognito["Amazon Cognito"]:::authService
        DynamoDB["DynamoDB"]:::storage
        S3["S3"]:::storage
        SNS["Amazon SNS"]:::messaging
        SES["Amazon SES"]:::messaging
    end

    subgraph "CI/CD Pipeline"
        GH["GitHub Actions"]:::pipeline
        SAM["SAM CLI / CloudFormation"]:::pipeline
    end

    Client -->|HTTP| API
    API --> AuthHandler
    API --> PhotoUploadHandler
    API --> PhotoQueryHandler
    API --> PhotoDeleteHandler
    API --> PhotoShareHandler
    API --> RecycleBinHandler
    API --> BackupHandler
    API --> CognitoBackupHandler
    API --> RestoreHandler

    AuthHandler --> CognitoService
    AuthHandler --> DynamoDBUtil
    AuthHandler --> Cognito

    PhotoUploadHandler --> S3Util
    PhotoUploadHandler --> DynamoDBUtil
    PhotoQueryHandler --> DynamoDBUtil
    PhotoDeleteHandler --> S3Util
    PhotoDeleteHandler --> DynamoDBUtil
    PhotoShareHandler --> SNSUtil
    RecycleBinHandler --> DynamoDBUtil

    S3 -->|ObjectCreated| ImageProcessingHandler
    ImageProcessingHandler --> S3Util
    ImageProcessingHandler --> ImageProcessor
    ImageProcessor --> DynamoDBUtil
    ProcessingRetryHandler --> DynamoDBUtil

    SNS --> LoginNotificationHandler
    LoginNotificationHandler --> SNSUtil
    LoginNotificationHandler --> SESUtil
    SNS --> ProcessingNotificationHandler
    ProcessingNotificationHandler --> SNSUtil
    ProcessingNotificationHandler --> SESUtil
    SystemAlertHandler --> SNSUtil

    BackupHandler --> DynamoDBUtil
    CognitoBackupHandler --> Cognito
    RestoreHandler --> DynamoDBUtil
    RestoreHandler --> Cognito

    GH --> SAM

    classDef compute fill:#f6a50e,stroke:#333,stroke-width:1px
    classDef gateway fill:#2ca8d8,stroke:#333,stroke-width:1px
    classDef storage fill:#97c2fc,stroke:#333,stroke-width:1px
    classDef messaging fill:#8fbc8f,stroke:#333,stroke-width:1px
    classDef auth fill:#9b59b6,stroke:#333,stroke-width:1px
    classDef authService fill:#9b59b6,stroke:#333,stroke-width:1px
    classDef pipeline fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef client fill:#ffe4b5,stroke:#333,stroke-width:1px

    click AuthHandler "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/auth/AuthHandler.java"
    click CognitoService "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/auth/CognitoService.java"
    click PhotoUploadHandler "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/photos/PhotoUploadHandler.java"
    click PhotoQueryHandler "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/photos/PhotoQueryHandler.java"
    click PhotoDeleteHandler "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/photos/PhotoDeleteHandler.java"
    click PhotoShareHandler "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/photos/PhotoShareHandler.java"
    click RecycleBinHandler "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/photos/RecycleBinHandler.java"
    click ImageProcessingHandler "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/processing/ImageProcessingHandler.java"
    click ImageProcessor "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/processing/ImageProcessor.java"
    click ProcessingRetryHandler "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/processing/ProcessingRetryHandler.java"
    click LoginNotificationHandler "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/notifications/LoginNotificationHandler.java"
    click ProcessingNotificationHandler "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/notifications/ProcessingNotificationHandler.java"
    click SystemAlertHandler "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/notifications/SystemAlertHandler.java"
    click EmailService "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/notifications/EmailService.java"
    click BackupHandler "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/disaster/BackupHandler.java"
    click CognitoBackupHandler "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/disaster/CognitoBackupHandler.java"
    click RestoreHandler "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/disaster/RestoreHandler.java"
    click DynamoDBUtil "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/utils/DynamoDBUtil.java"
    click S3Util "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/utils/S3Util.java"
    click SNSUtil "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/utils/SNSUtil.java"
    click SESUtil "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/utils/SESUtil.java"
    click Photo "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/models/Photo.java"
    click ProcessingStatus "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/models/ProcessingStatus.java"
    click User "https://github.com/gideonag/photo-blog-app-backend/blob/main/src/main/java/com/photoblog/models/User.java"
    click template "https://github.com/gideonag/photo-blog-app-backend/blob/main/template.yaml"
    click samconfig "https://github.com/gideonag/photo-blog-app-backend/blob/main/samconfig.toml"
    click GH "https://github.com/gideonag/photo-blog-app-backend/blob/main/.github/workflows/backend-deploy.yml"
```
