# aojedacs/go-url-shortener architecture

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

- Interactive diagram: https://gitdiagram.com/aojedacs/go-url-shortener
- Repository: https://github.com/aojedacs/go-url-shortener

## Overview

1. **Project shape**
   - This is a small Go backend service organized around a single HTTP API for URL shortening.
   - The repository is split into a runtime entrypoint under `cmd/` and application logic under `internal/`, which is a common Go boundary for keeping implementation details private to the module.

2. **Process entrypoint**
   - `cmd/server/main.go` is the executable entrypoint.
   - It likely wires together configuration, database connection, HTTP handler registration, and server startup on port `8080` as implied by the README usage example.

3. **HTTP/API layer**
   - `internal/shortener/handler.go` is the transport boundary.
   - It handles incoming requests such as `GET /shorten?url=...`, extracts parameters, delegates to the service layer, and returns the response to the client.
   - This layer should be the only place aware of HTTP-specific concerns like status codes, query parameters, and request/response formatting.

4. **Application/business layer**
   - `internal/shortener/service.go` contains the core URL-shortening behavior.
   - It likely generates the shortened identifier, validates input URL data, and coordinates persistence through the database layer.
   - This is the main abstraction boundary between web handling and storage.

5. **Persistence layer**
   - `internal/database/posgres.go` (note the filename typo) is the PostgreSQL integration point.
   - It likely establishes the DB connection and exposes methods used by the shortener service to store and retrieve URL mappings.
   - The architecture implies persistence is mandatory, not in-memory, so shortened links survive process restarts.

6. **Primary data flow**
   - A client sends an HTTP request to the `/shorten` endpoint with a full URL.
   - The handler passes the request data into the service.
   - The service transforms the input into a shortened representation and uses the database layer to persist the mapping.
   - The response is then returned through the handler to the client.

7. **State and storage boundaries**
   - PostgreSQL is the only explicit stateful component in the repo.
   - The application appears to be stateless outside the database, which makes horizontal scaling of the Go server straightforward as long as all instances share the same PostgreSQL backend.

8. **Runtime and deployment model**
   - The project targets Go 1.22+.
   - Docker is part of the local environment, and `docker-compose.yml` likely orchestrates the app plus PostgreSQL for development.
   - `make dev` is the expected developer entry command, suggesting the Makefile wraps startup and possibly dependency bootstrapping.

9. **Configuration**
   - `.env.example` indicates the service is configured through environment variables.
   - Typical architecture impact here is database connection settings, server port, and possibly any environment-specific behavior such as local vs. containerized startup.

10. **Repository boundaries**
   - `internal/shortener` is the domain-focused module.
   - `internal/database` is an infrastructure module.
   - `cmd/server` is a thin composition layer that assembles the application from these packages.
   - This separation helps keep transport, business logic, and infrastructure from becoming tightly coupled.

11. **External dependencies**
   - The only materially important external technology visible from the repo is PostgreSQL.
   - Docker is used for local infrastructure management, not as part of the application logic itself.

12. **Architecture summary**
   - Overall, this is a classic layered Go service: HTTP handler → shortener service → PostgreSQL repository/connection.
   - The main diagram should show one stateless Go API process, one PostgreSQL datastore, and the request path centered on shortening URLs through a single HTTP endpoint.

Main entry points: [`internal/shortener/handler.go`](https://github.com/aojedacs/go-url-shortener/blob/main/internal/shortener/handler.go) (Handler), [`internal/shortener/service.go`](https://github.com/aojedacs/go-url-shortener/blob/main/internal/shortener/service.go) (Service), [`cmd/server/main.go`](https://github.com/aojedacs/go-url-shortener/blob/main/cmd/server/main.go) (Main), [`internal/database/posgres.go`](https://github.com/aojedacs/go-url-shortener/blob/main/internal/database/posgres.go) (DB Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Runtime"]
  node_cmd_server_main["Main<br/>entrypoint<br/>[main.go]"]
  node_docker_compose["Compose<br/>dev orchestration<br/>[docker-compose.yml]"]
end

subgraph group_grp_app["Application"]
  node_http_handler["Handler<br/>HTTP transport<br/>[handler.go]"]
  node_shortener_service["Service<br/>[service.go]"]
end

subgraph group_grp_data["Data"]
  node_db_adapter["DB Adapter<br/>postgres integration<br/>[posgres.go]"]
  node_postgres[("PostgreSQL<br/>datastore")]
end

node_client(("Client<br/>external actor"))

node_client -->|"HTTP request"| node_http_handler
node_cmd_server_main -->|"registers"| node_http_handler
node_http_handler -->|"delegates"| node_shortener_service
node_shortener_service -->|"stores mapping"| node_db_adapter
node_db_adapter -->|"SQL"| node_postgres
node_cmd_server_main -->|"initializes"| node_db_adapter
node_docker_compose -->|"starts"| node_cmd_server_main
node_docker_compose -->|"provisions"| node_postgres
node_shortener_service -->|"result"| node_http_handler

click node_cmd_server_main "https://github.com/aojedacs/go-url-shortener/blob/main/cmd/server/main.go"
click node_http_handler "https://github.com/aojedacs/go-url-shortener/blob/main/internal/shortener/handler.go"
click node_shortener_service "https://github.com/aojedacs/go-url-shortener/blob/main/internal/shortener/service.go"
click node_db_adapter "https://github.com/aojedacs/go-url-shortener/blob/main/internal/database/posgres.go"
click node_docker_compose "https://github.com/aojedacs/go-url-shortener/blob/main/docker-compose.yml"

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_server_main,node_docker_compose toneBlue
class node_http_handler,node_shortener_service toneAmber
class node_db_adapter,node_postgres toneMint
class node_client toneNeutral
```

## Components

### Runtime

Executable entrypoint and process wiring

- [Main](https://github.com/aojedacs/go-url-shortener/blob/main/cmd/server/main.go): entrypoint · Composes the application and starts the HTTP server · `cmd/server/main.go`
- [Compose](https://github.com/aojedacs/go-url-shortener/blob/main/docker-compose.yml): dev orchestration · Runs the app and database together for local development · `docker-compose.yml`

### Application

HTTP transport and business logic

- [Handler](https://github.com/aojedacs/go-url-shortener/blob/main/internal/shortener/handler.go): HTTP transport · Parses requests and formats responses for the shorten endpoint · `internal/shortener/handler.go`
- [Service](https://github.com/aojedacs/go-url-shortener/blob/main/internal/shortener/service.go): domain service · Implements URL shortening rules and coordinates persistence · `internal/shortener/service.go`

### Data

Database integration and durable storage

- [DB Adapter](https://github.com/aojedacs/go-url-shortener/blob/main/internal/database/posgres.go): postgres integration · Connects the app to PostgreSQL and manages URL mappings · `internal/database/posgres.go`
- **PostgreSQL**: datastore · Persistent storage for shortened URL records

### Other components

- **Client**: external actor · Sends URL shortening requests

## Connections

- Client → Handler: HTTP request · Client calls the shorten endpoint with a URL
- Main → Handler: registers · Main wires the handler into the server
- Handler → Service: delegates · Handler passes parsed request data to the domain service
- Service → DB Adapter: stores mapping · Service persists or retrieves shortened URL data
- DB Adapter → PostgreSQL: SQL · Adapter talks to PostgreSQL for durable storage
- Main → DB Adapter: initializes · Main creates or configures the database connection
- Compose → Main: starts · Compose launches the Go API process in development
- Compose → PostgreSQL: provisions · Compose brings up PostgreSQL alongside the app
- Service → Handler: result · Service outcome is returned back through the handler
