# elyseemb/ecommercewithgolang architecture

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

- Interactive diagram: https://gitdiagram.com/elyseemb/ecommercewithgolang
- Repository: https://github.com/elyseemb/ecommercewithgolang

## Overview

##### Project type and purpose
- This is a backend service for an e-commerce application written in Go.
- It exposes RESTful HTTP endpoints for managing items and taxonomies (categories).
- It supports two database modes (SQLite by default, optional Postgres via Docker Compose).
- It uses a Clean/Hexagonal architecture (layers: domain, application, infrastructure, interfaces).

##### File structure
- cmd/main.go: starts the HTTP server
- cmd/migrate/main.go: runs DB migrations
- internal/interfaces/router.go + api handlers: HTTP entry points
- internal/application: service (use-case) layer
- internal/domain: core entities and repository interfaces
- internal/infrastructure: concrete implementations for DB connections and persistence
- compose/: Docker Compose setup for Postgres
- pkg/constants: shared constants

##### README
- Confirms Go and SQLite as primary technologies
- Mentions “Ecommerce Application” with item and taxonomy management

a. Main components
- HTTP Server (Gin/Chi or built-in net/http) – entry point
- Router & API Handlers – maps HTTP routes to application services
- Application Services – item_app, taxonomy_app use-cases
- Domain Layer – entities (Item, Taxonomy, Promotion) and repository interfaces
- Persistence Layer – concrete repos (SQLite/Postgres) implementing the interfaces
- Database – SQLite file or Postgres container
- CLI Migration Tool – runs SQL migrations before startup

b. Relationships & data flow
1. Client → HTTP Server → Router
2. Router → Handler (ItemHandler/TaxonomyHandler)
3. Handler → Application Service (e.g. CreateItem)
4. Service → Domain Entity / Repository Interface
5. Repository Interface → Persistence Implementation (item_repository)
6. Persistence → Database (exec SQL queries)
7. Database → Persistence → returns data back up the chain → HTTP Response

c. Architectural patterns & design principles
- Dependency inversion: application layer depends on domain interfaces, not concrete DB code
- Separation of concerns: clear layers (interfaces/controllers, services, domain, infrastructure)
- Single Responsibility: each package focuses on one role
- CLI command isolation: migrations separated from main server

d. Key technologies & frameworks
- Go modules (go.mod)
- net/http or a router library (defined in internal/interfaces/router.go)
- SQLite (default) and Postgres (infrastructure/database/pg.go)
- SQL migrations under internal/infrastructure/database/migrations

## Diagram (Mermaid)

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

    %% Migration CLI
    MigrationTool["Migration CLI Tool<br>(cmd/migrate/main.go)"]:::cli
    click MigrationTool "https://github.com/elyseemb/ecommercewithgolang/blob/main/cmd/migrate/main.go"

    %% Layers
    subgraph "HTTP Layer"
        Server["HTTP Server"]:::server
        click Server "https://github.com/elyseemb/ecommercewithgolang/blob/main/cmd/main.go"
        Router["Router"]:::controller
        click Router "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/interfaces/router.go"
        ItemHandler["ItemHandler"]:::controller
        click ItemHandler "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/interfaces/api/item_handler.go"
        TaxHandler["TaxonomyHandler"]:::controller
        click TaxHandler "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/interfaces/api/taxonomy_handler.go"
    end

    subgraph "Application Layer"
        ItemService["ItemService"]:::service
        click ItemService "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/application/item_app.go"
        TaxService["TaxonomyService"]:::service
        click TaxService "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/application/taxonomy_app.go"
    end

    subgraph "Domain Layer"
        ItemEntity["Item Entity"]:::domain
        click ItemEntity "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/domain/entity/item.go"
        TaxEntity["Taxonomy Entity"]:::domain
        click TaxEntity "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/domain/entity/taxonomy.go"
        PromoEntity["Promotion Entity"]:::domain
        click PromoEntity "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/domain/entity/promotion.go"
        DBExecutorIfc["DBExecutor Interface"]:::domain
        click DBExecutorIfc "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/domain/repository/db_executor.go"
        ItemRepoIfc["ItemRepository Interface"]:::domain
        click ItemRepoIfc "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/domain/repository/item.go"
        TaxRepoIfc["TaxonomyRepository Interface"]:::domain
        click TaxRepoIfc "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/domain/repository/taxonomy.go"
        PromoRepoIfc["PromotionRepository Interface"]:::domain
        click PromoRepoIfc "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/domain/repository/promotion.go"
    end

    subgraph "Infrastructure Layer"
        subgraph "Database Config"
            DBConfig["DB Config"]:::infra
            click DBConfig "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/infrastructure/database/config.go"
            SQLiteConn["SQLite Connection"]:::infra
            click SQLiteConn "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/infrastructure/database/sqlite.go"
            PGConn["Postgres Connection"]:::infra
            click PGConn "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/infrastructure/database/pg.go"
        end
        subgraph "Migrations"
            MigrationRunner["Migration Runner"]:::infra
            click MigrationRunner "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/infrastructure/database/migration.go"
            Migrations["SQL Migrations"]:::infra
            click Migrations "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/infrastructure/database/migrations/000001_create_taxonomies_table.up.sql"
        end
        subgraph "Repositories"
            ItemRepoImpl["ItemRepository Impl"]:::infra
            click ItemRepoImpl "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/infrastructure/persistence/item_repository.go"
            TaxRepoImpl["TaxonomyRepository Impl"]:::infra
            click TaxRepoImpl "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/infrastructure/persistence/taxonomy_repository.go"
            Repos["Bulk Repositories"]:::infra
            click Repos "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/infrastructure/persistence/repositories.go"
        end
        Helpers["Utils Helpers"]:::infra
        click Helpers "https://github.com/elyseemb/ecommercewithgolang/blob/main/internal/infrastructure/utils/helpers.go"
    end

    subgraph "External Services"
        SQLiteDB["SQLite DB"]:::database
        PostgresDB["Postgres DB"]:::database
        DockerCompose["Docker Compose"]:::external
        click DockerCompose "https://github.com/elyseemb/ecommercewithgolang/blob/main/compose.yml"
        click DockerCompose "https://github.com/elyseemb/ecommercewithgolang/blob/main/compose/postgres/config.sh"
    end

    SharedConst["Shared Constants"]:::constant
    click SharedConst "https://github.com/elyseemb/ecommercewithgolang/blob/main/pkg/constants/constants.go"

    %% Flows
    Client -->|"HTTP Request"| Server
    Server --> Router
    Router --> ItemHandler
    Router --> TaxHandler
    ItemHandler --> ItemService
    TaxHandler --> TaxService
    ItemService --> ItemEntity
    ItemService --> ItemRepoIfc
    TaxService --> TaxEntity
    TaxService --> TaxRepoIfc
    ItemService --> PromoEntity
    ItemService --> PromoRepoIfc

    ItemRepoIfc --> ItemRepoImpl
    TaxRepoIfc --> TaxRepoImpl
    PromoRepoIfc --> Repos

    ItemRepoImpl --> SQLiteConn
    ItemRepoImpl --> PGConn
    TaxRepoImpl --> SQLiteConn
    TaxRepoImpl --> PGConn
    Repos --> SQLiteConn
    Repos --> PGConn

    SQLiteConn --> SQLiteDB
    PGConn --> PostgresDB

    MigrationTool --> MigrationRunner
    MigrationRunner --> Migrations
    MigrationRunner --> SQLiteConn
    MigrationRunner --> PGConn

    SharedConst -.-> Server
    SharedConst -.-> MigrationTool

    DockerCompose --> PostgresDB

    %% Styles
    classDef external fill:#ECEFF4,stroke:#4C566A,color:#2E3440;
    classDef server fill:#D8DEE9,stroke:#4C566A,color:#2E3440;
    classDef controller fill:#88C0D0,stroke:#5E81AC,color:#2E3440;
    classDef service fill:#A3BE8C,stroke:#4C566A,color:#2E3440;
    classDef domain fill:#EBCB8B,stroke:#4C566A,color:#2E3440;
    classDef infra fill:#D08770,stroke:#4C566A,color:#2E3440;
    classDef database fill:#5E81AC,stroke:#4C566A,color:#ECEFF4;
    classDef cli fill:#BF616A,stroke:#4C566A,color:#ECEFF4;
    classDef constant fill:#B48EAD,stroke:#4C566A,color:#ECEFF4;
```
