How martinsd3v/planets works
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).