How bagashiz/go-pos works
Project type and purpose
• This is a backend-only RESTful Point-of-Sale (POS) service written in Go.
• It follows Hexagonal (Ports & Adapters) architecture.
• It uses Gin for HTTP, PostgreSQL (via pgx & Squirrel) as primary persistence, Redis (go-redis) for caching, and Paseto for auth tokens.
• Swagger docs are exposed via gin-swagger.
File structure
• cmd/http/main.go – program entrypoint; spins up Gin router, mounts middleware, handlers, Swagger.
• internal/adapter – all adapters:
• handler/http – inbound HTTP controllers, router, middleware, validation, response formatting.
• auth/paseto – token creation/verification.
• storage/postgres – migrations & repository implementations.
• storage/redis – caching adapter.
• config, logger – loading config, structured logging.
• internal/core – the hexagonal core:
• domain – entities and value objects (User, Order, Product, etc.).
• port – interfaces (AuthPort, UserPort, ProductPort, CachePort…).
• service – business logic implementing use cases, wired to ports.
• util – helper functions (password hashing, caching utilities).
• docs – Swagger JSON/YAML for API docs.
• Dockerfile, docker-compose.yml – containerization.
• Taskfile.yml – orchestration (build, run migrations, start).
README
• Confirms REST API, hexagonal architecture, technology stack.
• Points to API docs at /docs/index.html and DB schema at schema.dbml / docs/swagger.*
• Describes dev flow: .env, docker-compose, Taskfile.
a. Main Components
• Client (Web UI, Postman, Mobile) – generates HTTP requests.
• API Layer (Gin) – request router, middleware (auth, logging, validation).
• Handler Layer – HTTP handlers for User, Product, Category, Order, Payment.
• Service Layer – core business logic (auth, user management, product catalog, orders, payments).
• Domain Model – core entities & value objects.
• Ports (Interfaces) – abstract outbound calls (UserPort, PaymentPort, CachePort, AuthPort…).
• Adapters:
• Postgres Adapter – repository implementations, migrations.
• Redis Adapter – cache implementation.
• Paseto Adapter – token service.
• Config & Logger – environment config loader, structured logging.
• External Systems: PostgreSQL DB, Redis Cache.
• API Docs (Swagger UI).
b. Relationships & Interactions
• Client → HTTP Middleware (Auth, Logging) → Handler → Service → Domain & Ports → Adapter → External Systems.
• Service layer calls Ports (interfaces). Ports are implemented by Adapters.
• Config/Logger used by both HTTP and Adapters.
• Migrations applied to Postgres at startup or via Taskfile.
c. Architectural Patterns & Principles
• Hexagonal Architecture: clear separation of core (domain & service) from frameworks & infrastructure.
• Dependency Inversion: core depends only on interfaces.
• Single Responsibility: handlers orchestrate HTTP; services host business rules; adapters handle I/O.
• Layered flow: HTTP → Handler → Service → Persistence/Cache.
d. Key Technologies
• Gin (HTTP).
• Squirrel + pgx (Postgres).
• go-redis (Redis).
• Paseto (token auth).
• Swaggo/Gin-Swagger (API docs).
• Taskfile for tasks; Docker/Docker-Compose for containers.
Essential Elements to Capture
• Separation of concerns: HTTP vs. business logic vs. persistence.
• Core hexagon: domain types at center, ports on its edges.
• Adapter wrappers fulfilling those ports.
• Cross-cutting: config loader, logger.
• API documentation endpoint as a side note.