# elyseemb/urlshortener architecture

> Architecture diagram of the GitHub repository elyseemb/urlshortener, 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/urlshortener
- Repository: https://github.com/elyseemb/urlshortener

## Overview

##### Project type and purpose
- This is a serverless URL-shortening microservice written in Go, packaged with AWS SAM and deployed as one or more AWS Lambda functions behind an API Gateway. Its sole responsibility is to generate (and potentially resolve) short links, persisting them in an external datastore and collecting basic stats.

##### File structure
- `.aws-sam/` + `template.yml`: AWS SAM build artifacts and CloudFormation template for Lambda definitions, IAM roles, API Gateway.
- `compose.yml`: Docker Compose setup (likely local DynamoDB or local testing harness).
- `main.go`: Lambda entrypoint wired by SAM (invokes handlers).
- `internal/`
- `adapters/functions/generate/`: Lambda bootstrap for the “generate URL” function
- `adapters/handlers/`: HTTP‐level handlers parsing requests, calling core services
- `adapters/repository/`: persistence adapter (Link repository implementation, e.g. DynamoDB)
- `config/`: configuration loader (env variables, AWS region, table names)
- `core/domain/`: domain objects (Link, Stats)
- `core/ports/`: domain‐service interfaces (repository ports)
- `core/services/`: business logic implementing the ports (link creation, stats)
- `makefile`, `go.mod`, `go.sum`: build tooling and dependencies

##### README
- Confirms a Go-based URL shortener, deployable on AWS Lambda. No UI; purely an API.

a. Main components
1) Client (e.g. HTTP client or browser)
2) AWS API Gateway (REST API endpoint)
3) AWS Lambda “Generate” function (Go runtime)
4) Configuration module (env + SAM parameters)
5) Core service layer (domain + business logic)
6) Repository adapter (persistence)
7) DynamoDB table (or whichever datastore)
8) (Optional) Stats pipeline / CloudWatch metrics
9) Deployment artifacts (SAM/CloudFormation, S3 bucket)
b. Relationships & interactions
- Client → API Gateway (POST /generate)
- API Gateway → Lambda function
- Lambda handler loads config → invokes core service
- Core service calls repository adapter → DynamoDB
- DynamoDB returns item → core service returns short link
- Lambda returns JSON via API Gateway → Client
- (Stats domain objects feed CloudWatch or a secondary queue)
c. Architectural patterns
- Hexagonal (Ports & Adapters / Clean Architecture):
- Core domain & services (pure business logic)
- Ports define interfaces (e.g. `LinksRepository`)
- Adapters implement ports (DynamoDB, HTTP handlers, Lambda shim)
- Serverless microservice pattern: AWS SAM to define Lambda + API Gateway, minimal infra.
d. Key technologies
- Go modules, Go 1.x runtime
- AWS SAM / CloudFormation
- AWS Lambda, AWS API Gateway
- AWS DynamoDB (or chosen persistence)
- Docker Compose for local emulation (DynamoDB Local)

##### Elements
- Clear labels: “API Gateway”, “Lambda Function: generate”, “Core Service (domain + ports)”, “Repository Adapter”, “DynamoDB Table”
- Code modules inside Lambda in green (handlers, services, repositories)
- Infra as code (SAM template) in gray

## Diagram (Mermaid)

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

    %% AWS Cloud
    subgraph "AWS Cloud"
        API["API Gateway"]:::aws
        subgraph "Lambda Function: generate" 
            LB["Bootstrap (generate/main.go)"]:::code
            ME["main.go"]:::code
            CFG["Configuration Module"]:::code
            HND["HTTP Handlers"]:::code
            SVC["Core Services"]:::code
            REPO["Repository Adapter"]:::code
        end
        DB["DynamoDB Table"]:::aws
    end

    %% Infrastructure as Code
    subgraph "Deployment Infra"
        SAM["template.yml"]:::infra
        BUILD[".aws-sam/"]:::infra
        COMPOSE["compose.yml"]:::infra
        TOOL["makefile, go.mod, go.sum"]:::infra
    end

    %% Client to API
    Client -->|POST /generate| API
    API -->|Invoke| LB

    %% Lambda internals
    LB -->|"init"| ME
    ME -->|"loads"| CFG
    ME -->|"routes to"| HND
    HND -->|"calls"| SVC
    SVC -->|"implements port"| REPO
    REPO -->|"reads/writes"| DB

    %% Infra relations
    SAM -->|defines| LB
    SAM -->|builds| BUILD
    COMPOSE -->|emulates| DB
    TOOL -->|builds| LB

    %% Click Events
    click SAM "https://github.com/elyseemb/urlshortener/blob/main/template.yml"
    click BUILD "https://github.com/elyseemb/urlshortener/tree/main/.aws-sam/"
    click COMPOSE "https://github.com/elyseemb/urlshortener/blob/main/compose.yml"
    click TOOL "https://github.com/elyseemb/urlshortener/tree/main/makefile"
    click TOOL "https://github.com/elyseemb/urlshortener/blob/main/go.mod"
    click TOOL "https://github.com/elyseemb/urlshortener/blob/main/go.sum"
    click ME "https://github.com/elyseemb/urlshortener/blob/main/main.go"
    click LB "https://github.com/elyseemb/urlshortener/blob/main/internal/adapters/functions/generate/main.go"
    click HND "https://github.com/elyseemb/urlshortener/blob/main/internal/adapters/handlers/generate.go"
    click HND "https://github.com/elyseemb/urlshortener/blob/main/internal/adapters/handlers/helpers.go"
    click CFG "https://github.com/elyseemb/urlshortener/blob/main/internal/config/config.go"
    click REPO "https://github.com/elyseemb/urlshortener/blob/main/internal/adapters/repository/link.go"
    click SVC "https://github.com/elyseemb/urlshortener/blob/main/internal/core/services/link.go"
    click SVC "https://github.com/elyseemb/urlshortener/blob/main/internal/core/ports/links.go"
    click SVC "https://github.com/elyseemb/urlshortener/blob/main/internal/core/domain/link.go"
    click SVC "https://github.com/elyseemb/urlshortener/blob/main/internal/core/domain/stats.go"

    %% Styles
    classDef aws fill:#E0F2FF,stroke:#0288D1,stroke-width:2px
    classDef code fill:#E8F5E9,stroke:#388E3C,stroke-width:1px
    classDef infra fill:#F5F5F5,stroke:#9E9E9E,stroke-width:1px
    classDef external fill:#FFF3E0,stroke:#FB8C00,stroke-width:1px
```
