How sikozonpc/ecom-go-api-project works
1. What this repo is
- A Go-based e-commerce API with two primary business areas: products and orders.
- The architecture is centered around an HTTP API backed by PostgreSQL.
2. Process entrypoint and bootstrap
- cmd/main.go is the executable entrypoint.
- cmd/api.go likely contains the application wiring: config loading, dependency setup, HTTP server startup, and route registration.
- This is the top-level runtime boundary in the repo.
3. HTTP/API layer
- internal/products/handlers.go and internal/orders/handlers.go are the request-facing adapters.
- These handlers translate HTTP requests into calls to the application services and format responses.
- internal/json/json.go suggests a shared JSON helper used to standardize decoding/encoding and response handling.
4. Business logic boundaries
- internal/products/service.go and internal/orders/service.go contain the core use-case logic for each domain area.
- internal/products/types.go likely defines the domain/data transfer types used by the product module.
- The repo is organized by feature/domain rather than by technical layer alone.
5. Persistence layer
- internal/adapters/postgresql is the infrastructure adapter for database access.
- This is the boundary where domain/services talk to PostgreSQL through generated query code rather than raw SQL in handlers.
6. SQLC-generated database access
- internal/adapters/postgresql/sqlc contains code generated from SQL definitions.
- queries.sql is the source query file, and queries.sql.go, db.go, models.go, querier.go are generated artifacts.
- This means database interactions are strongly typed and schema-driven.
7. Schema management
- Migrations live under internal/adapters/postgresql/migrations.
- The visible tables are:
- 00001_create_products.sql
- 00002_create_orders.sql
- The database schema is versioned independently of the application code.
8. Configuration and environment
- internal/env/env.go likely centralizes environment-variable loading and validation.
- The .env file indicates local configuration is expected via environment variables rather than hardcoded settings.
9. Operational/runtime dependencies
- docker-compose.yaml is used to bring up the runtime stack locally, almost certainly including PostgreSQL and possibly the API container.
- The README shows the app is normally run with go run cmd/*.go after dependencies are available.
10. Tooling and build-time flow
- goose manages migrations; sqlc generates database access code.
- The typical lifecycle is: create migration → apply migration → regenerate SQLC code → use the generated queries from the services.
- These are not runtime services, but they materially shape the architecture by coupling schema, queries, and service code.
11. Architectural shape to diagram
- Draw it as:
- Client → HTTP handlers → domain services → PostgreSQL adapter/sqlc → PostgreSQL
- Show products and orders as parallel bounded contexts sharing the same persistence technology but having separate handlers/services and separate tables.
- Keep internal/json and internal/env as shared support utilities around the edges.
12. Notable boundary
- The repo appears to follow a clean separation between:
- transport (handlers)
- domain/use cases (service)
- infrastructure/data access (adapters/postgresql)
- That separation is the main architectural feature worth preserving in a diagram.
Main entry points: api.go Bootstrap · products/handlers.go Prod Handlers · service.go Product Service · orders/handlers.go Order Handlers
Components 17
Runtime
Process entrypoint and server bootstrap
API Layer
HTTP transport and shared request/response helpers
- JSON Helper · Request decoding and response encoding
internal/json/json.go
Products
Product bounded context
- Prod Handlers · Product request handlers
internal/products/handlers.go - Product Service · Product business logic
internal/products/service.go - Product Types · Product data structures
Orders
Order bounded context
- Order Handlers · Order request handlers
internal/orders/handlers.go - Order Service · Order business logic
internal/orders/service.go - Order Types · Order data structures
internal/orders/types.go
Persistence
Database adapter and generated query layer
- Postgres Adapter · Infrastructure boundary for PostgreSQL access
internal/adapters/postgresql - SQLC Queries · Generated typed queries and models
internal/adapters/postgresql/sqlc/queries.sql.go - Query Schema · Source SQL used by sqlc
internal/adapters/postgresql/sqlc/queries.sql - Migrations · Database migration files
internal/adapters/postgresql/migrations - PostgreSQL · Primary persistence store
Support
Shared configuration and utility code
- Env Loader · Environment configuration loading
internal/env/env.go - Compose Stack · Local service orchestration
docker-compose.yaml
Other components
- Client · API consumer or caller
Connections 18
- Client → Main: invoke · Starts the API process
- Main → Bootstrap: boot · Hands off to application wiring
- Bootstrap → Env Loader: config · Loads runtime settings
- Bootstrap → Prod Handlers: routes · Registers product endpoints
- Bootstrap → Order Handlers: routes · Registers order endpoints
- Prod Handlers → JSON Helper: parse/format · Standardizes request and response JSON
- Order Handlers → JSON Helper: parse/format · Standardizes request and response JSON
- Prod Handlers → Product Service: calls · Delegates product use cases
- Order Handlers → Order Service: calls · Delegates order use cases
- Product Service → Product Types: uses · Operates on product domain types
- Order Service → Order Types: uses · Operates on order domain types
- Product Service → Postgres Adapter: data access · Reads and writes product data through the adapter
- Order Service → Postgres Adapter: data access · Reads and writes order data through the adapter
- Postgres Adapter → SQLC Queries: executes · Uses generated typed query methods
- SQLC Queries → Query Schema: generated from · Built from SQLC source queries
- SQLC Queries → PostgreSQL: persists · Executes statements against PostgreSQL
- Migrations → PostgreSQL: migrate · Defines the database schema
- Compose Stack → PostgreSQL: provisions · Brings up the local database stack