# martinsd3v/planets architecture

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

- Interactive diagram: https://gitdiagram.com/martinsd3v/planets
- Repository: https://github.com/martinsd3v/planets

## Overview

##### Project Type and Purpose
- This is a backend microservice written in Go, applying Hexagonal (Ports & Adapters) architecture, DDD, SOLID and Clean Code principles.
- It exposes REST endpoints for two domains: “users” (with JWT-protected CRUD and authentication) and “planets” (public list/read, JWT-protected create/update/delete).
- It uses MongoDB for persistence, Memcache for caching, OpenTelemetry + Jaeger for tracing, an HTTP client to fetch Star-Wars film data, and Echo as the web framework.

##### File-Structure Analysis
- adapters/
- rest/… – HTTP server (routers, controllers, middlewares)
- persistence/mongodb/… – MongoDB connection & repository implementations
- core/
- domains/{planet,user}/entities, repositories (port interfaces), services (use-case implementations + tests)
- tools/providers – cross-cutting services (cache, hash, JWT, HTTP client, logger, tracer) and validations
- docker-compose.yml, planet.Dockerfile – container orchestration
- postman, seeds – test data & environment

##### Key Architectural Patterns
- Hexagonal Architecture: core domain in the center, exposing port interfaces; adapters plug in via those ports.
- Dependency Injection via Go methods, keeping core independent of framework or DB details.
- Cross-cutting concerns (logging, tracing, caching, auth) delegated to provider modules.

##### Main Components
A. Core Domain (Hexagon)
- User Domain Service Port
- Planet Domain Service Port
- Entities & Port Interfaces (UserRepository, PlanetRepository)
B. Adapters
- REST Adapter (Echo Framework) – Routers → Controllers → Domain Services
- Persistence Adapter (MongoDB) – implements repository ports
C. Tools/Providers (Cross-cutting)
- JWT Provider (auth middleware)
- Cache Provider (Memcache)
- HTTP Client Provider (calls external Star-Wars API for films)
- Logger Provider
- Tracer Provider (OpenTelemetry → Jaeger)
- Hash Provider (password hashing)
D. External Systems
- MongoDB instance
- Memcache server
- External Star-Wars API
- Jaeger UI/Backend

##### Relationships & Data Flow
1. Client → REST Adapter (HTTP POST/GET)
2. Middleware (Trace start, JWT validation)
3. Controller maps HTTP → Domain request DTO
4. Domain Service (core) executes business logic
– may call Cache Provider → Memcache
– may call HTTP Client Provider → External API for film data
– calls Repository Port → Persistence Adapter → MongoDB
– uses Hash Provider or JWT Provider as needed
5. Domain returns DTO → Controller → HTTP response
6. Trace ends, log emitted

- Clear labels on every component (e.g., “MongoDB Adapter” vs. “PlanetRepository Port”).
- Arrowheads to indicate data/request flow direction.
- Optionally, versioning/deployment notes (Docker Compose deploying all containers together).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client"]:::external

    %% REST Adapter
    subgraph "REST Adapter" 
        direction TB
        MAIN["Main (Echo Server)"]:::adapter
        ROUTERS["Routers"]:::adapter
        CONTROLLERS["Controllers"]:::adapter
        MIDDLEWARE["Auth Middleware"]:::adapter
        TRACE_UTIL["Trace Utility"]:::adapter
    end

    %% Core Domain
    subgraph "Core Domain" 
        direction TB
        subgraph "User Domain" 
            direction TB
            USERVICE["UserService Port"]:::core
            UREPO["UserRepository Port"]:::core
            UENTITY["User Entity"]:::core
        end
        subgraph "Planet Domain" 
            direction TB
            PSERVICE["PlanetService Port"]:::core
            PREPO["PlanetRepository Port"]:::core
            PENTITY["Planet Entity"]:::core
        end
    end

    %% Persistence Adapter
    subgraph "Persistence Adapter (MongoDB)" 
        direction TB
        MONGO_CONN["MongoDB Connection"]:::adapter
        UREPO_IMPL["MongoDB Users Repository"]:::adapter
        PREPO_IMPL["MongoDB Planets Repository"]:::adapter
    end

    %% Providers
    subgraph "Tools & Providers" 
        direction TB
        JWT["JWT Provider"]:::provider
        CACHE["Cache Provider"]:::provider
        HTTPCLIENT["HTTP Client Provider"]:::provider
        LOGGER["Logger Provider"]:::provider
        TRACER["Tracer Provider"]:::provider
        HASH["Hash Provider"]:::provider
    end

    %% External Systems
    MemcacheDB["Memcache"]:::external
    MongoDBDB["MongoDB"]:::external
    ExternalAPI["Star-Wars API"]:::external
    JaegerUI["Jaeger"]:::external

    %% Connections
    Client -->|HTTP Request| MAIN
    MAIN -->|register routers| ROUTERS
    ROUTERS -->|invoke| CONTROLLERS
    CONTROLLERS -->|middleware| MIDDLEWARE
    MIDDLEWARE -->|trace start| TRACE_UTIL
    CONTROLLERS -->|call| USERVICE
    CONTROLLERS -->|call| PSERVICE

    USERVICE -->|uses| UREPO
    USERVICE -->|uses| CACHE
    USERVICE -->|uses| HASH
    PSERVICE -->|uses| PREPO
    PSERVICE -->|uses| CACHE
    PSERVICE -->|uses| HTTPCLIENT

    UREPO -->|implemented by| UREPO_IMPL
    PREPO -->|implemented by| PREPO_IMPL

    UREPO_IMPL -->|connects| MONGO_CONN
    PREPO_IMPL -->|connects| MONGO_CONN
    MONGO_CONN -->|CRUD| MongoDBDB

    CACHE -->|get/set| MemcacheDB
    HTTPCLIENT -->|fetch films| ExternalAPI

    TRACE_UTIL -->|trace spans| TRACER
    TRACER -->|sends traces| JaegerUI
    LOGGER -->|logs to| JaegerUI

    %% Click Events
    click USERVICE "https://github.com/martinsd3v/planets/blob/main/core/domains/user/services/services.go"
    click PSERVICE "https://github.com/martinsd3v/planets/blob/main/core/domains/planet/services/services.go"
    click UENTITY "https://github.com/martinsd3v/planets/blob/main/core/domains/user/entities/user_entity.go"
    click PENTITY "https://github.com/martinsd3v/planets/blob/main/core/domains/planet/entities/plannet_entity.go"
    click UREPO "https://github.com/martinsd3v/planets/blob/main/core/domains/user/repositories/user_repository.go"
    click PREPO "https://github.com/martinsd3v/planets/blob/main/core/domains/planet/repositories/planet_repository.go"
    click MAIN "https://github.com/martinsd3v/planets/blob/main/adapters/rest/main.go"
    click ROUTERS "https://github.com/martinsd3v/planets/blob/main/adapters/rest/routers/users/users_routers.go"
    click ROUTERS "https://github.com/martinsd3v/planets/blob/main/adapters/rest/routers/planets/planets_routers.go"
    click CONTROLLERS "https://github.com/martinsd3v/planets/blob/main/adapters/rest/controllers/users/users_controller.go"
    click CONTROLLERS "https://github.com/martinsd3v/planets/blob/main/adapters/rest/controllers/planets/planets_controller.go"
    click MIDDLEWARE "https://github.com/martinsd3v/planets/blob/main/adapters/rest/middlewares/auth/auth_middleware.go"
    click TRACE_UTIL "https://github.com/martinsd3v/planets/blob/main/adapters/rest/util/trace_endpoint_util.go"
    click MONGO_CONN "https://github.com/martinsd3v/planets/blob/main/adapters/persistence/mongodb/database.go"
    click UREPO_IMPL "https://github.com/martinsd3v/planets/blob/main/adapters/persistence/mongodb/repositories/users/mongodb_users_repository.go"
    click PREPO_IMPL "https://github.com/martinsd3v/planets/blob/main/adapters/persistence/mongodb/repositories/planets/mongodb_planets_repository.go"
    click CACHE "https://github.com/martinsd3v/planets/blob/main/core/tools/providers/cache/mem_cache.go"
    click CACHE "https://github.com/martinsd3v/planets/blob/main/core/tools/providers/cache/cache_provider.go"
    click JWT "https://github.com/martinsd3v/planets/blob/main/core/tools/providers/jwt/jwt_provider.go"
    click JWT "https://github.com/martinsd3v/planets/blob/main/core/tools/providers/jwt/token.go"
    click HTTPCLIENT "https://github.com/martinsd3v/planets/blob/main/core/tools/providers/http_client/http_client_provider.go"
    click HTTPCLIENT "https://github.com/martinsd3v/planets/blob/main/core/tools/providers/http_client/http_client.go"
    click LOGGER "https://github.com/martinsd3v/planets/blob/main/core/tools/providers/logger/logger_provider.go"
    click LOGGER "https://github.com/martinsd3v/planets/blob/main/core/tools/providers/logger/logger.go"
    click TRACER "https://github.com/martinsd3v/planets/blob/main/core/tools/providers/tracer/tracer_provider.go"
    click TRACER "https://github.com/martinsd3v/planets/blob/main/core/tools/providers/tracer/jaeger_tracer.go"
    click HASH "https://github.com/martinsd3v/planets/blob/main/core/tools/providers/hash/password_hash.go"
    click HASH "https://github.com/martinsd3v/planets/blob/main/core/tools/providers/hash/hash_provider.go"

    %% Styles
    classDef core fill:#d0e7f9,stroke:#3b7dbf,color:#000
    classDef adapter fill:#daf5d4,stroke:#4caf50,color:#000
    classDef provider fill:#ffe0b2,stroke:#fb8c00,color:#000
    classDef external fill:#e0e0e0,stroke:#9e9e9e,color:#000
```
