# mohamedhussieen/go-task architecture

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

- Interactive diagram: https://gitdiagram.com/mohamedhussieen/go-task
- Repository: https://github.com/mohamedhussieen/go-task

## Overview

##### Project type and purpose
- This is a Go-based, Dockerized RESTful API for an e-commerce platform.
- It handles user authentication (JWT + role-based), product CRUD, order processing, credit-card storage, and Stripe payment integration.
- Persistence is via PostgreSQL; the service is orchestrated with Docker Compose.

##### File structure
- cmd/api/main.go: application entrypoint (HTTP server).
- internal/api/handlers: HTTP handlers grouped by resource (auth, products, orders, credit cards, Stripe).
- internal/api/middleware: auth middleware (JWT enforcement, role checks).
- internal/models: domain models (User, Product, Order, CreditCard, etc.).
- internal/db/postgres: DB connection setup and SQL helpers.
- migrations/: SQL scripts for schema evolution.
- Dockerfile & docker-compose.yml: container build & orchestration.
- postman/: API collection for testing/documentation.

##### README for additional insights
- Tech stack: Go 1.19+, PostgreSQL 15, Stripe Go SDK, JWT for auth.
- Runtime env via `.env`; Docker Compose spins up `api` + `postgres`.
- API endpoints are grouped into public, user-protected, and admin-protected.
- Database schema tables: users, products, orders (+ items), credit_cards.

##### Main components & their interactions
a. API Server Container (Go)
- HTTP Router → Middleware (JWT auth, role checks) → Handlers → internal/db → PostgreSQL
- Handlers use models, validate input, orchestrate business logic
- Stripe client invoked by the “process-payment” handler for external payment API calls
b. PostgreSQL Container
- Hosts persistent data (users, products, orders, cards)
- Initialized/migrated via migrations on startup
c. External Services & Clients
- Stripe API (HTTPS) for payment processing
- Clients (Web/Mobile/Postman) make HTTP calls to API endpoints
d. Docker Compose
- Defines and links the `api` and `postgres` containers, injects environment variables

##### Architectural patterns & design principles
- Layered architecture:
1) Routing & HTTP layer
2) Middleware (cross-cutting concerns)
3) Handler layer (resource-specific controllers)
4) Data access layer (internal/db with SQL helpers)
5) Domain models
- Separation of concerns: auth vs business logic vs data access
- Security: JWT stateless auth, role-based authorization in middleware
- Infrastructure as code: Docker + Docker Compose + SQL migrations

##### How to represent this
1) Client (Browser/Mobile/Postman)
2) API Service (Go)
3) PostgreSQL Database
4) External Payment Gateway (Stripe)
- HTTP Router
- Auth Middleware (JWT, role check)
- Handlers (Auth, Products, Orders, CreditCards, Stripe)
- Data Access Layer (internal/db/postgres)
- Models
– Client → HTTP Router (port 8080)
– HTTP Router → Middleware → Handlers
– Handlers → Data Access Layer → Database
– Payment Handler → Stripe API
– Database responses flow back up to the client
– Containers (bold outline) vs internal modules (thin outline)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Client["Client\n(Web/Mobile/Postman)"]:::external

    %% Containers
    subgraph "API Service (Go)" 
        style APIService stroke:#333,stroke-width:2px
        APIService["API Service"]:::container

        Router["HTTP Router\n(port 8080)"]:::module
        AuthM["Auth Middleware\n(JWT, Role Checks)"]:::module

        subgraph "Handlers"
            AuthHandler["Auth Handler"]:::module
            ProductsHandler["Products Handler"]:::module
            OrdersHandler["Orders Handler"]:::module
            CreditCardsHandler["Credit Cards Handler"]:::module
            StripeHandler["Stripe Payment Handler"]:::module
            AdminHandler["Admin Handler"]:::module
        end

        DataAccess["Data Access Layer\n(SQL Helpers)"]:::module

        subgraph "Domain Models"
            UserModel["User"]:::module
            ProductModel["Product"]:::module
            OrderModel["Order"]:::module
            CreditCardModel["CreditCard"]:::module
            AuthModel["Auth"]:::module
        end
    end

    %% Database
    Database["PostgreSQL Database\n(port 5432)"]:::database
    Migrations["Migrations"]:::module

    %% External Services
    Stripe["Stripe API"]:::external

    %% Connections
    Client -->|HTTP 8080| Router
    Router -->|request| AuthM
    AuthM -->|authorized| AuthHandler
    AuthM -->|authorized| ProductsHandler
    AuthM -->|authorized| OrdersHandler
    AuthM -->|authorized| CreditCardsHandler
    AuthM -->|authorized| StripeHandler
    AuthM -->|authorized| AdminHandler

    AuthHandler -->|uses| DataAccess
    ProductsHandler -->|uses| DataAccess
    OrdersHandler -->|uses| DataAccess
    CreditCardsHandler -->|uses| DataAccess
    StripeHandler -->|uses| DataAccess
    AdminHandler -->|uses| DataAccess

    DataAccess -->|SQL| Database
    Migrations -->|migrate| Database

    StripeHandler -->|HTTPS| Stripe
    Database -->|data| AuthHandler
    Database -->|data| ProductsHandler
    Database -->|data| OrdersHandler
    Database -->|data| CreditCardsHandler
    Database -->|data| AdminHandler

    %% Click Events
    click APIService "https://github.com/mohamedhussieen/go-task/blob/master/cmd/api/main.go"
    click Router "https://github.com/mohamedhussieen/go-task/blob/master/cmd/api/main.go"
    click AuthM "https://github.com/mohamedhussieen/go-task/blob/master/internal/api/middleware/auth.go"
    click AuthHandler "https://github.com/mohamedhussieen/go-task/blob/master/internal/api/handlers/auth.go"
    click ProductsHandler "https://github.com/mohamedhussieen/go-task/blob/master/internal/api/handlers/products.go"
    click OrdersHandler "https://github.com/mohamedhussieen/go-task/blob/master/internal/api/handlers/orders.go"
    click CreditCardsHandler "https://github.com/mohamedhussieen/go-task/blob/master/internal/api/handlers/credit_cards.go"
    click StripeHandler "https://github.com/mohamedhussieen/go-task/blob/master/internal/api/handlers/stripe.go"
    click AdminHandler "https://github.com/mohamedhussieen/go-task/blob/master/internal/api/handlers/admin.go"
    click DataAccess "https://github.com/mohamedhussieen/go-task/blob/master/internal/db/postgres/db.go"
    click UserModel "https://github.com/mohamedhussieen/go-task/blob/master/internal/models/user.go"
    click ProductModel "https://github.com/mohamedhussieen/go-task/blob/master/internal/models/product.go"
    click OrderModel "https://github.com/mohamedhussieen/go-task/blob/master/internal/models/order.go"
    click CreditCardModel "https://github.com/mohamedhussieen/go-task/blob/master/internal/models/credit_card.go"
    click AuthModel "https://github.com/mohamedhussieen/go-task/blob/master/internal/models/auth.go"
    click Migrations "https://github.com/mohamedhussieen/go-task/blob/master/migrations/01_init.sql"
    %% Note: other migrations not individually clicked
    click Dockerfile "https://github.com/mohamedhussieen/go-task/tree/master/Dockerfile"
    click docker_compose "https://github.com/mohamedhussieen/go-task/blob/master/docker-compose.yml"
    click Postman "https://github.com/mohamedhussieen/go-task/blob/master/postman/Go_Task_API.postman_collection.json"
    click Mod "https://github.com/mohamedhussieen/go-task/blob/master/go.mod"
    click Sum "https://github.com/mohamedhussieen/go-task/blob/master/go.sum"
    click Readme "https://github.com/mohamedhussieen/go-task/blob/master/README.md"

    %% Styles
    classDef container stroke:#2B6CB0,stroke-width:2px,fill:#BEE3F8
    classDef module stroke:#4A5568,stroke-width:1px,fill:#EDF2F7
    classDef external stroke:#D53F8C,stroke-dasharray: 3 2,fill:#FDEDEA
    classDef database fill:#FFF5B1,stroke:#DD6B20,stroke-width:2px
```
