# sikozonpc/ecom-go-api-project architecture

> Architecture diagram of the GitHub repository sikozonpc/ecom-go-api-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sikozonpc/ecom-go-api-project
- Repository: https://github.com/sikozonpc/ecom-go-api-project

## Overview

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: [`cmd/api.go`](https://github.com/sikozonpc/ecom-go-api-project/blob/main/cmd/api.go) (Bootstrap), [`internal/products/handlers.go`](https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/products/handlers.go) (Prod Handlers), [`internal/products/service.go`](https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/products/service.go) (Product Service), [`internal/orders/handlers.go`](https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/orders/handlers.go) (Order Handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_cmd_main["Main<br/>entrypoint<br/>[main.go]"]
  node_cmd_api["Bootstrap<br/>wiring<br/>[api.go]"]
end

subgraph group_api["API Layer"]
  node_json_helper["JSON Helper<br/>shared utility<br/>[json.go]"]
end

subgraph group_products["Products"]
  node_products_handlers["Prod Handlers<br/>http adapter<br/>[handlers.go]"]
  node_products_service["Product Service<br/>use case<br/>[service.go]"]
  node_products_types["Product Types<br/>domain model"]
end

subgraph group_orders["Orders"]
  node_orders_handlers["Order Handlers<br/>http adapter<br/>[handlers.go]"]
  node_orders_service["Order Service<br/>use case<br/>[service.go]"]
  node_orders_types["Order Types<br/>domain model<br/>[types.go]"]
end

subgraph group_infra["Persistence"]
  node_pg_adapter[("Postgres Adapter<br/>db adapter")]
  node_sqlc_queries["SQLC Queries<br/>generated db layer<br/>[queries.sql.go]"]
  node_sqlc_schema["Query Schema<br/>sql definitions<br/>[queries.sql]"]
  node_migrations["Migrations<br/>schema versioning"]
  node_postgres_db[("PostgreSQL<br/>database")]
end

subgraph group_support["Support"]
  node_env_loader["Env Loader<br/>config<br/>[env.go]"]
  node_docker_compose["Compose Stack<br/>runtime config"]
end

node_external_client(("Client<br/>external"))

node_external_client -->|"invoke"| node_cmd_main
node_cmd_main -->|"boot"| node_cmd_api
node_cmd_api -->|"config"| node_env_loader
node_cmd_api -->|"routes"| node_products_handlers
node_cmd_api -->|"routes"| node_orders_handlers
node_products_handlers -->|"parse/format"| node_json_helper
node_orders_handlers -->|"parse/format"| node_json_helper
node_products_handlers -->|"calls"| node_products_service
node_orders_handlers -->|"calls"| node_orders_service
node_products_service -->|"uses"| node_products_types
node_orders_service -->|"uses"| node_orders_types
node_products_service -->|"data access"| node_pg_adapter
node_orders_service -->|"data access"| node_pg_adapter
node_pg_adapter -->|"executes"| node_sqlc_queries
node_sqlc_queries -.->|"generated from"| node_sqlc_schema
node_sqlc_queries -->|"persists"| node_postgres_db
node_migrations -->|"migrate"| node_postgres_db
node_docker_compose -.->|"provisions"| node_postgres_db

click node_cmd_main "https://github.com/sikozonpc/ecom-go-api-project/blob/main/cmd/main.go"
click node_cmd_api "https://github.com/sikozonpc/ecom-go-api-project/blob/main/cmd/api.go"
click node_products_handlers "https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/products/handlers.go"
click node_products_service "https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/products/service.go"
click node_orders_handlers "https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/orders/handlers.go"
click node_orders_service "https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/orders/service.go"
click node_orders_types "https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/orders/types.go"
click node_json_helper "https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/json/json.go"
click node_env_loader "https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/env/env.go"
click node_pg_adapter "https://github.com/sikozonpc/ecom-go-api-project/tree/main/internal/adapters/postgresql"
click node_sqlc_queries "https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/adapters/postgresql/sqlc/queries.sql.go"
click node_sqlc_schema "https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/adapters/postgresql/sqlc/queries.sql"
click node_migrations "https://github.com/sikozonpc/ecom-go-api-project/tree/main/internal/adapters/postgresql/migrations"
click node_docker_compose "https://github.com/sikozonpc/ecom-go-api-project/blob/main/docker-compose.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmd_main,node_cmd_api toneBlue
class node_json_helper toneAmber
class node_products_handlers,node_products_service,node_products_types toneMint
class node_orders_handlers,node_orders_service,node_orders_types toneRose
class node_pg_adapter,node_sqlc_queries,node_sqlc_schema,node_migrations,node_postgres_db toneIndigo
class node_env_loader,node_docker_compose toneTeal
class node_external_client toneNeutral
```

## Components

### Runtime

Process entrypoint and server bootstrap

- [Main](https://github.com/sikozonpc/ecom-go-api-project/blob/main/cmd/main.go): entrypoint · Program entrypoint · `cmd/main.go`
- [Bootstrap](https://github.com/sikozonpc/ecom-go-api-project/blob/main/cmd/api.go): wiring · App setup and server startup · `cmd/api.go`

### API Layer

HTTP transport and shared request/response helpers

- [JSON Helper](https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/json/json.go): shared utility · Request decoding and response encoding · `internal/json/json.go`

### Products

Product bounded context

- [Prod Handlers](https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/products/handlers.go): http adapter · Product request handlers · `internal/products/handlers.go`
- [Product Service](https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/products/service.go): use case · Product business logic · `internal/products/service.go`
- **Product Types**: domain model · Product data structures

### Orders

Order bounded context

- [Order Handlers](https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/orders/handlers.go): http adapter · Order request handlers · `internal/orders/handlers.go`
- [Order Service](https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/orders/service.go): use case · Order business logic · `internal/orders/service.go`
- [Order Types](https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/orders/types.go): domain model · Order data structures · `internal/orders/types.go`

### Persistence

Database adapter and generated query layer

- [Postgres Adapter](https://github.com/sikozonpc/ecom-go-api-project/tree/main/internal/adapters/postgresql): db adapter · Infrastructure boundary for PostgreSQL access · `internal/adapters/postgresql`
- [SQLC Queries](https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/adapters/postgresql/sqlc/queries.sql.go): generated db layer · Generated typed queries and models · `internal/adapters/postgresql/sqlc/queries.sql.go`
- [Query Schema](https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/adapters/postgresql/sqlc/queries.sql): sql definitions · Source SQL used by sqlc · `internal/adapters/postgresql/sqlc/queries.sql`
- [Migrations](https://github.com/sikozonpc/ecom-go-api-project/tree/main/internal/adapters/postgresql/migrations): schema versioning · Database migration files · `internal/adapters/postgresql/migrations`
- **PostgreSQL**: database · Primary persistence store

### Support

Shared configuration and utility code

- [Env Loader](https://github.com/sikozonpc/ecom-go-api-project/blob/main/internal/env/env.go): config · Environment configuration loading · `internal/env/env.go`
- [Compose Stack](https://github.com/sikozonpc/ecom-go-api-project/blob/main/docker-compose.yaml): runtime config · Local service orchestration · `docker-compose.yaml`

### Other components

- **Client**: external · API consumer or caller

## Connections

- 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