# jpcamilo/challenge_meli architecture

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

- Interactive diagram: https://gitdiagram.com/jpcamilo/challenge_meli
- Repository: https://github.com/jpcamilo/challenge_meli

## Overview

##### Project Type and Purpose
- This is a backend microservices solution focused on secure, efficient handling of large file uploads. It consists of two Spring-based services plus external support systems:
- file-gateway: a Spring Cloud Gateway that authenticates/authorizes requests and routes them.
- file-management: a Spring Boot reactive service that implements chunked upload, storage, metadata management.
- External components: Keycloak (OIDC/OAuth2), PostgreSQL, and optional cloud storage (GCP).

##### File Structure Analysis
- Top-level modules:
- file-gateway/…: contains a Spring Cloud Gateway project (pom.xml, Dockerfile, CORS/SecurityConfig, main application).
- file-management/…: contains a Spring Boot application with layered packages (config, controller, service, repository, model, exception), reactive controllers, chunked upload service, GCP storage adapter.
- Common cross-cutting concerns: security configs, application-*.yml, test suites.
- Supporting files: init.sql (DB schema), realm-export-meli.json (Keycloak realm setup).

##### README Insights
- Architecture summary confirms: API gateway, backend file service, Keycloak, PostgreSQL.
- Emphasis on: chunked (multipart) upload, reactive non-blocking flows, OAuth2/OIDC, extensible storage (local vs. GCP).

##### Essential Details to Capture
- API Gateway filters and route definitions.
- Reactive chunk upload lifecycle: receive chunk → temporary storage → metadata update → final assembly.
- Authentication handshake: client obtains token from Keycloak, then calls gateway.
- Database initialization via init.sql.
- Configuration injection for GCP storage (upload-service-key.json).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client["Client (Browser/CLI)"]:::externalOrange

    %% API Gateway Layer
    subgraph "Security & Routing"
        direction TB
        FGApp["File Gateway\nApplication"]:::serviceBlue
        SecConfig["SecurityConfig"]:::serviceBlue
        CORS["CORS Filter"]:::serviceBlue
        RouteConf["Gateway Config\n(application.yml)"]:::serviceBlue
        DockerFG["Dockerfile"]:::serviceBlue
    end

    %% Auth Server
    Keycloak["Keycloak OIDC Server"]:::externalOrange

    %% File Management Layer
    subgraph "File Management Service"
        direction TB
        FMApp["File Management\nApplication"]:::serviceBlue
        GlobalEx["GlobalExceptionHandler"]:::serviceBlue
        SecPermit["SecurityPermitSwaggerConfig"]:::serviceBlue
        SwaggerCFG["SwaggerConfig"]:::serviceBlue
        GCPcfg["GCPConfig"]:::serviceBlue
        Controller["FileUploadReactiveController"]:::serviceBlue
        ChunkIntf["IChunkedFileUploadService"]:::serviceBlue
        ChunkImpl["ChunkedFileUploadServiceImpl"]:::serviceBlue
        StorageIntf["ReactiveFileStorageService"]:::serviceBlue
        StorageImpl["ReactiveFileStorageServiceImpl"]:::serviceBlue
        Model["FileMetadata"]:::serviceBlue
        Repo["FileMetadataRepository"]:::serviceBlue
        AppConfFM["application.yml"]:::serviceBlue
        InitSQL["init.sql"]:::storeGreen
        Realm["realm-export-meli.json"]:::externalOrange
    end

    %% Storage & Metadata
    subgraph "Storage & Metadata"
        direction TB
        Postgres["PostgreSQL"]:::storeGreen
        subgraph "File Storage Options"
            LocalFS["Local File System"]:::storeGreen
            GCPBucket["GCP Bucket"]:::storeGreen
        end
    end

    %% Connections
    Client -->|"Authorization: Bearer JWT"| FGApp
    FGApp -->|"JWT Validation"| Keycloak
    FGApp -->|"Forward REST Calls"| FMApp
    FMApp -->|"CRUD Metadata"| Postgres
    FMApp -->|"Store/Retrieve Chunks"| StorageIntf
    StorageIntf -->|"Local Impl"| LocalFS
    StorageIntf -->|"GCP Impl"| GCPBucket

    %% Click Events for file-gateway
    click FGApp "https://github.com/jpcamilo/challenge_meli/blob/main/file-gateway/src/main/java/com/meli/file_gateway/FileGatewayApplication.java"
    click SecConfig "https://github.com/jpcamilo/challenge_meli/blob/main/file-gateway/src/main/java/com/meli/file_gateway/SecurityConfig.java"
    click CORS "https://github.com/jpcamilo/challenge_meli/blob/main/file-gateway/src/main/java/com/meli/file_gateway/CORS.java"
    click RouteConf "https://github.com/jpcamilo/challenge_meli/blob/main/file-gateway/src/main/resources/application.yml"
    click DockerFG "https://github.com/jpcamilo/challenge_meli/tree/main/file-gateway/Dockerfile"

    %% Click Events for file-management
    click FMApp "https://github.com/jpcamilo/challenge_meli/blob/main/file-management/src/main/java/com/meli/file_management/FileManagementApplication.java"
    click GlobalEx "https://github.com/jpcamilo/challenge_meli/blob/main/file-management/src/main/java/com/meli/file_management/exception/GlobalExceptionHandler.java"
    click SecPermit "https://github.com/jpcamilo/challenge_meli/blob/main/file-management/src/main/java/com/meli/file_management/config/SecurityPermitSwaggerConfig.java"
    click SwaggerCFG "https://github.com/jpcamilo/challenge_meli/blob/main/file-management/src/main/java/com/meli/file_management/config/SwaggerConfig.java"
    click GCPcfg "https://github.com/jpcamilo/challenge_meli/blob/main/file-management/src/main/java/com/meli/file_management/config/GCPConfig.java"
    click Controller "https://github.com/jpcamilo/challenge_meli/blob/main/file-management/src/main/java/com/meli/file_management/controller/FileUploadReactiveController.java"
    click ChunkIntf "https://github.com/jpcamilo/challenge_meli/blob/main/file-management/src/main/java/com/meli/file_management/service/IChunkedFileUploadService.java"
    click ChunkImpl "https://github.com/jpcamilo/challenge_meli/blob/main/file-management/src/main/java/com/meli/file_management/service/impl/ChunkedFileUploadServiceImpl.java"
    click StorageIntf "https://github.com/jpcamilo/challenge_meli/blob/main/file-management/src/main/java/com/meli/file_management/service/ReactiveFileStorageService.java"
    click StorageImpl "https://github.com/jpcamilo/challenge_meli/blob/main/file-management/src/main/java/com/meli/file_management/service/impl/ReactiveFileStorageServiceImpl.java"
    click Model "https://github.com/jpcamilo/challenge_meli/blob/main/file-management/src/main/java/com/meli/file_management/model/FileMetadata.java"
    click Repo "https://github.com/jpcamilo/challenge_meli/blob/main/file-management/src/main/java/com/meli/file_management/repository/FileMetadataRepository.java"
    click AppConfFM "https://github.com/jpcamilo/challenge_meli/blob/main/file-management/src/main/resources/application.yml"
    click InitSQL "https://github.com/jpcamilo/challenge_meli/blob/main/init.sql"
    click Realm "https://github.com/jpcamilo/challenge_meli/blob/main/realm-export-meli.json"

    %% Styles
    classDef serviceBlue fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef storeGreen fill:#E2F0D9,stroke:#237A00,stroke-width:1px
    classDef externalOrange fill:#FFE5B4,stroke:#D26900,stroke-width:1px
```
