# s21platform/avatar-service architecture

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

- Interactive diagram: https://gitdiagram.com/s21platform/avatar-service
- Repository: https://github.com/s21platform/avatar-service

## Overview

##### Main Components
- Service Entrypoint: The “cmd/service/main.go” file indicates where the service is started.
- Configuration Module: The “internal/config” folder (with files like config.go and keys.go) is responsible for initializing application settings.
- Business Logic: Found in “internal/service” (service.go and contract.go), this layer contains the core logic for avatar operations.
- Data Models: The “internal/model” directory defines core data structures (e.g., avatar_info.go).
- Infrastructure and Utilities: The “internal/infra” folder contains modules for logging, authentication, and metrics.
- Persistence / Repositories:
- PostgreSQL: “internal/repository/postgres” handles database operations (e.g., storing the avatar metadata, user UUIDs, timestamps).
- S3: “internal/repository/s3” deals with uploading images and managing links via Yandex S3.
- Migrations: The “migrations” directory contains SQL scripts and docker-related files for managing database schema changes.
- External Services: As described in the README, these include:
- Yandex S3 for physical image storage.
- PostgreSQL for metadata and audit purposes.
- Kafka for sending messages upon avatar updates.
- Webp conversion library for image processing.

##### Determining Relationships and Interactions
- Entry Point Flow: The service starts in cmd/service/main.go, which initializes configuration and then starts the core service.
- The Business Logic (internal/service) acts as the orchestrator—it handles avatar changes, calls upon the repository layers, and triggers side effects.
- The Repository Layers interact with external systems:
- The PostgreSQL repository handles read/write operations to the database.
- The S3 repository interacts with Yandex S3 for storing avatar images.
- The service layer may trigger the Webp conversion process (via the go-webp library) before uploading images.
- After critical operations (like an avatar change), a Kafka producer sends a message to an external USER-SERVICE (using the segmentio/kafka-go library).
- The infrastructure components (auth, logger, and metrics) are used across modules for enhanced monitoring, security, and logging.

##### Architectural Patterns and Design Principles
- Layered Architecture: The project is structured into distinct layers (configuration, business logic, repository, and infrastructure), which facilitates separation of concerns.
- Dependency Injection & Abstraction: By separating repository implementations and service contracts, testing and further extensions are simplified.
- External Service Integration: Clearly defined integration points with external systems, such as S3, PostgreSQL, Kafka, and image processing tools.

##### Final Recommendations
- Be very detailed–capture every critical component and the interactions between them.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Service Entrypoint: cmd/service/main.go"]:::internal
    B["Configuration Module: internal/config"]:::internal
    C["Business Logic/Service: internal/service"]:::internal
    D["Data Models: internal/model"]:::internal
    E["Infrastructure & Utilities: internal/infra"]:::internal
    F["PostgreSQL Repository: internal/repository/postgres"]:::internal
    G["S3 Repository: internal/repository/s3"]:::internal
    H["Migrations: migrations"]:::internal

    I["PostgreSQL Database"]:::external
    J["External Storage (Yandex S3)"]:::external
    K["External Message Broker (Kafka)"]:::external
    L["Image Processing (Webp Conversion)"]:::external

    %% Main flow
    A --> B
    B --> C
    C --> D
    C --> F
    C --> G
    C --> K
    C --> L

    %% Repositories to external services
    F -->|"writes_to"| I
    G -->|"uploads_to"| J
    H -->|"migrates"| I

    %% Infrastructure usage by internal components
    A -->|"uses"| E
    B -->|"uses"| E
    C -->|"uses"| E
    F -->|"uses"| E
    G -->|"uses"| E

    %% Styles
    classDef internal fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef external fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;

    %% Click events
    click A "https://github.com/s21platform/avatar-service/blob/main/cmd/service/main.go"
    click B "https://github.com/s21platform/avatar-service/tree/main/internal/config"
    click C "https://github.com/s21platform/avatar-service/tree/main/internal/service"
    click D "https://github.com/s21platform/avatar-service/tree/main/internal/model"
    click E "https://github.com/s21platform/avatar-service/tree/main/internal/infra"
    click F "https://github.com/s21platform/avatar-service/tree/main/internal/repository/postgres"
    click G "https://github.com/s21platform/avatar-service/tree/main/internal/repository/s3"
    click H "https://github.com/s21platform/avatar-service/tree/main/migrations"
```
