# martin226/slideitin architecture

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

- Interactive diagram: https://gitdiagram.com/martin226/slideitin
- Repository: https://github.com/martin226/slideitin

## Overview

##### Main Project Components
- Frontend:
- Located in the “frontend/” directory, it’s a Next.js application (built with React, TypeScript, and Tailwind CSS).
- Responsible for the user interface, handling uploads, theme selection, configuration, and displaying real-time progress.
- Backend API Service:
- Found under “backend/api/” with Go code (Gin framework). It handles receiving client requests, managing business logic, interfacing with Google Cloud Firestore for job status, and setting up Cloud Tasks.
- Uses server-sent events (SSE) to relay real-time updates to the frontend.
- Slides Service Microservice:
- Located in “backend/slides-service/”, also in Go, and dedicated to slide generation tasks.
- Integrates with the Gemini 1.5 Flash API for AI-driven content creation and uses Marp for converting markdown into presentation slides.
- Cloud and Third-Party Services:
- Google Cloud Firestore for storage and job status tracking.
- Google Cloud Tasks for asynchronous job processing.
- External AI API (Gemini 1.5 Flash) and presentation tool (Marp).

##### Architectural Relationships
- The frontend interacts with the backend API via RESTful/SSE endpoints.
- The backend API receives file uploads and user preferences and then enqueues jobs (using Cloud Tasks) for slide generation.
- The slides-service microservice processes these jobs: it calls the Gemini API for content generation, applies the chosen theme (with available CSS files under “services/slides/themes/”), and finally produces the slide deck.
- Data flows through clearly defined channels, from the user to the frontend, then to the backend API, and finally to the slides service microservice.
- The entire process is orchestrated via Google Cloud’s build and deployment pipelines (as seen in “cloudbuild.yaml” and “lb.yaml”).

##### Architectural Patterns and Design Principles
- Microservices architecture: Separating the main API from the slide generation service enhances scalability and maintainability.
- Clear separation of concerns: Frontend handles presentation, the API handles data/business logic, and the slide service focuses on domain-specific operations.
- Cloud-native deployment: Deployment via Docker and Cloud Run indicates containerization and the use of managed cloud infrastructure.
- Real-time communication using Server-Sent Events guiding user feedback during slide generation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    CLIENT["User/Client (Web Browser)"]:::client

    %% Frontend Layer
    subgraph "Frontend"
        FRONTEND["Frontend (Next.js Application)"]:::frontend
    end

    %% Backend API Service
    subgraph "Backend API Service"
        API["Backend API Service (Gin)"]:::backend
        API_Main["main.go"]:::backend
        API_Controllers["Controllers"]:::backend
        API_Models["Models"]:::backend
        API_JobQueue["Job Queue (job_queue.go)"]:::backend
    end

    %% Cloud Services
    subgraph "Cloud Services"
        FIRESTORE["Google Cloud Firestore"]:::cloud
        CLOUDTASKS["Google Cloud Tasks"]:::cloud
    end

    %% Slides Generation Microservice
    subgraph "Slides Generation Microservice"
        SLIDESERVICE["Slides Generation Microservice (Go)"]:::microservice
        SS_Main["main.go"]:::microservice
        SS_TaskController["Task Controller (task_controller.go)"]:::microservice
        SS_Prompts["Prompts Service"]:::microservice
        SS_Themes["Slides Themes (services/slides/themes)"]:::microservice
    end

    %% External Services
    subgraph "External Services"
        GEMINI["Gemini 1.5 Flash API"]:::external
        MARP["Marp (Slide Conversion)"]:::external
    end

    %% Cloud Deployment Configuration
    subgraph "Cloud Deployment Configuration"
        CLOUDBUILD["Cloudbuild Config"]:::deployment
        LB["Load Balancer Config (lb.yaml)"]:::deployment
    end

    %% Connections
    CLIENT -->|"upload/themeSelection"| FRONTEND
    FRONTEND -->|"REST/SSEcall"| API
    API -->|"enqueueJob"| CLOUDTASKS
    API -->|"jobStatus"| FIRESTORE
    API -->|"triggerJob"| SLIDESERVICE
    SLIDESERVICE -->|"AIContentGen"| GEMINI
    SLIDESERVICE -->|"mdToSlides"| MARP
    API -->|"SSEupdates"| FRONTEND

    %% Internal connections within Backend API Service
    API --> API_Main
    API_Main --> API_Controllers
    API_Controllers --> API_Models
    API_Controllers --> API_JobQueue

    %% Internal connections within Slides Generation Microservice
    SLIDESERVICE --> SS_Main
    SS_Main --> SS_TaskController
    SS_TaskController --> SS_Prompts
    SS_TaskController --> SS_Themes

    %% Click Events for Component Mapping
    click FRONTEND "https://github.com/martin226/slideitin/tree/main/frontend/"
    click API "https://github.com/martin226/slideitin/tree/main/backend/api/"
    click API_Main "https://github.com/martin226/slideitin/blob/main/backend/api/main.go"
    click API_Controllers "https://github.com/martin226/slideitin/tree/main/backend/api/controllers/"
    click API_Models "https://github.com/martin226/slideitin/tree/main/backend/api/models/"
    click API_JobQueue "https://github.com/martin226/slideitin/blob/main/backend/api/services/queue/job_queue.go"
    click SLIDESERVICE "https://github.com/martin226/slideitin/tree/main/backend/slides-service/"
    click SS_Main "https://github.com/martin226/slideitin/blob/main/backend/slides-service/main.go"
    click SS_TaskController "https://github.com/martin226/slideitin/blob/main/backend/slides-service/controllers/task_controller.go"
    click SS_Prompts "https://github.com/martin226/slideitin/tree/main/backend/slides-service/services/prompts/"
    click SS_Themes "https://github.com/martin226/slideitin/tree/main/backend/slides-service/services/slides/themes/"
    click CLOUDBUILD "https://github.com/martin226/slideitin/blob/main/cloudbuild.yaml"
    click LB "https://github.com/martin226/slideitin/blob/main/lb.yaml"

    %% Styles
    classDef client fill:#e3f2fd,stroke:#2196F3,stroke-width:2px;
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef backend fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef microservice fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef cloud fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef external fill:#E1BEE7,stroke:#6A1B9A,stroke-width:2px;
    classDef deployment fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
```
