# sustatov027-max/url_shortener architecture

> Architecture diagram of the GitHub repository sustatov027-max/url_shortener, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sustatov027-max/url_shortener
- Repository: https://github.com/sustatov027-max/url_shortener

## Overview

#### Purpose and Entry Point
A Go HTTP API for creating and resolving shortened URLs, backed by PostgreSQL. The process starts in `cmd/app/main.go`; generated Swagger artifacts are embedded alongside it in `cmd/app/docs/docs.go`.

#### Composition Root and Runtime
`cmd/app/main.go` loads configuration, initializes PostgreSQL, constructs repository/service/handler layers, and starts the HTTP server. Container deployment is supported by `Dockerfile` and `docker-compose.yml`; environment inputs are documented by `.env.example`.

#### HTTP/API Boundary
Routing and request/response handling live in `internal/handler/router.go` and `internal/handler/url_handler.go`. This boundary owns HTTP semantics—route dispatch, input decoding/validation, status codes, and Swagger-facing API behavior—while delegating URL operations to the service layer.

#### URL Application Service
`internal/service/url_service.go` implements the core use cases: accepting an original URL, generating or assigning its short identifier, persisting the mapping, and resolving a short identifier back to its destination. It is the business boundary between transport handlers and persistence, and depends on repository abstractions rather than PostgreSQL directly.

#### Persistence Abstraction and PostgreSQL Adapter
`internal/repository/repository.go` defines the storage-facing contract used by services. PostgreSQL-specific connection setup is in `internal/repository/postgres/postgres.go`, with URL mapping queries in `internal/repository/postgres/url.go`. PostgreSQL is the material external dependency and durable source of URL mappings.

#### Identifier Generation
`pkg/generator/generator.go` provides short-code generation independently of HTTP and database concerns. The URL service consumes this capability when creating mappings; generated values must cooperate with persistence uniqueness rules to prevent collisions.

#### Schema Lifecycle and API Documentation
`migrations/000001_init_schema.up.sql` and `migrations/000001_init_schema.down.sql` define creation and rollback of the database schema. API documentation is published as generated OpenAPI/Swagger files at `cmd/app/docs/swagger.yaml` and `cmd/app/docs/swagger.json`, exposing the handler contract to clients.

#### Primary Flow
Create flow: HTTP request → `internal/handler/url_handler.go` → `internal/service/url_service.go` → `pkg/generator/generator.go` plus repository interface → `internal/repository/postgres/url.go` → PostgreSQL. Resolve flow reverses the lookup path: request handler → service → repository/PostgreSQL → HTTP redirect or response. Configuration is isolated in `internal/config/config.go`, keeping environment and connection details outside domain flow.

Main entry points: [`cmd/app/main.go`](https://github.com/sustatov027-max/url_shortener/blob/main/cmd/app/main.go) (Application bootstrap), [`internal/handler/url_handler.go`](https://github.com/sustatov027-max/url_shortener/blob/main/internal/handler/url_handler.go) (URL handler), [`internal/service/url_service.go`](https://github.com/sustatov027-max/url_shortener/blob/main/internal/service/url_service.go) (URL service), [`internal/repository/postgres/url.go`](https://github.com/sustatov027-max/url_shortener/blob/main/internal/repository/postgres/url.go) (URL mapping queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main{{"Application bootstrap<br/>Go entry point<br/>[main.go]"}}
  node_config["Configuration<br/>config loader<br/>[config.go]"]
  node_container["Container deployment<br/>deployment definition"]
  node_compose["Compose stack<br/>local deployment<br/>[docker-compose.yml]"]
end

subgraph group_api["HTTP API"]
  node_router["HTTP router<br/>route dispatch<br/>[router.go]"]
  node_url_handler["URL handler<br/>HTTP handler<br/>[url_handler.go]"]
end

subgraph group_application["Application"]
  node_url_service["URL service<br/>application service<br/>[url_service.go]"]
  node_generator["Short-code generator<br/>identifier generator<br/>[generator.go]"]
end

subgraph group_persistence["Persistence"]
  node_repository_contract["Repository contract<br/>storage interface<br/>[repository.go]"]
  node_postgres_connection["PostgreSQL setup<br/>database adapter<br/>[postgres.go]"]
  node_url_repository["URL mapping queries<br/>PostgreSQL repository<br/>[url.go]"]
  node_postgres[("PostgreSQL<br/>durable datastore")]
end

subgraph group_delivery["Schema &amp; Docs"]
  node_migrations_up["Schema migration<br/>SQL migration"]
  node_migrations_down["Schema rollback<br/>SQL migration"]
  node_swagger_docs["OpenAPI documents<br/>generated API docs<br/>[swagger.yaml]"]
  node_swagger_embed["Embedded Swagger<br/>generated Go docs<br/>[docs.go]"]
end

node_main -->|"loads"| node_config
node_main -->|"initializes"| node_postgres_connection
node_main -->|"starts"| node_router
node_router -->|"dispatches requests"| node_url_handler
node_url_handler -->|"create / resolve"| node_url_service
node_url_service -->|"generates code"| node_generator
node_url_service -->|"persists / looks up"| node_repository_contract
node_url_repository -.->|"implements"| node_repository_contract
node_postgres_connection -->|"provides connection"| node_url_repository
node_url_repository -->|"queries mappings"| node_postgres
node_migrations_up -->|"creates schema"| node_postgres
node_migrations_down -->|"rolls back schema"| node_postgres
node_swagger_embed -.->|"generated from"| node_swagger_docs
node_url_handler -.->|"documents contract"| node_swagger_docs
node_container -->|"runs"| node_main
node_compose -->|"orchestrates"| node_container
node_compose -->|"provisions"| node_postgres

click node_main "https://github.com/sustatov027-max/url_shortener/blob/main/cmd/app/main.go"
click node_config "https://github.com/sustatov027-max/url_shortener/blob/main/internal/config/config.go"
click node_router "https://github.com/sustatov027-max/url_shortener/blob/main/internal/handler/router.go"
click node_url_handler "https://github.com/sustatov027-max/url_shortener/blob/main/internal/handler/url_handler.go"
click node_url_service "https://github.com/sustatov027-max/url_shortener/blob/main/internal/service/url_service.go"
click node_generator "https://github.com/sustatov027-max/url_shortener/blob/main/pkg/generator/generator.go"
click node_repository_contract "https://github.com/sustatov027-max/url_shortener/blob/main/internal/repository/repository.go"
click node_postgres_connection "https://github.com/sustatov027-max/url_shortener/blob/main/internal/repository/postgres/postgres.go"
click node_url_repository "https://github.com/sustatov027-max/url_shortener/blob/main/internal/repository/postgres/url.go"
click node_migrations_up "https://github.com/sustatov027-max/url_shortener/blob/main/migrations/000001_init_schema.up.sql"
click node_migrations_down "https://github.com/sustatov027-max/url_shortener/blob/main/migrations/000001_init_schema.down.sql"
click node_swagger_docs "https://github.com/sustatov027-max/url_shortener/blob/main/cmd/app/docs/swagger.yaml"
click node_swagger_embed "https://github.com/sustatov027-max/url_shortener/blob/main/cmd/app/docs/docs.go"
click node_container "https://github.com/sustatov027-max/url_shortener/blob/main/Dockerfile"
click node_compose "https://github.com/sustatov027-max/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_main,node_config,node_container,node_compose toneBlue
class node_router,node_url_handler toneAmber
class node_url_service,node_generator toneMint
class node_repository_contract,node_postgres_connection,node_url_repository,node_postgres toneRose
class node_migrations_up,node_migrations_down,node_swagger_docs,node_swagger_embed toneIndigo
```

## Components

### Runtime

- [Application bootstrap](https://github.com/sustatov027-max/url_shortener/blob/main/cmd/app/main.go): Go entry point · Composes dependencies and starts the HTTP server. · `cmd/app/main.go`
- [Configuration](https://github.com/sustatov027-max/url_shortener/blob/main/internal/config/config.go): config loader · Loads environment and connection settings. · `internal/config/config.go`
- [Container deployment](https://github.com/sustatov027-max/url_shortener/blob/main/Dockerfile): deployment definition · `Dockerfile`
- [Compose stack](https://github.com/sustatov027-max/url_shortener/blob/main/docker-compose.yml): local deployment · `docker-compose.yml`

### HTTP API

- [HTTP router](https://github.com/sustatov027-max/url_shortener/blob/main/internal/handler/router.go): route dispatch · `internal/handler/router.go`
- [URL handler](https://github.com/sustatov027-max/url_shortener/blob/main/internal/handler/url_handler.go): HTTP handler · Owns request validation, responses, and redirects. · `internal/handler/url_handler.go`

### Application

- [URL service](https://github.com/sustatov027-max/url_shortener/blob/main/internal/service/url_service.go): application service · Creates mappings and resolves short identifiers. · `internal/service/url_service.go`
- [Short-code generator](https://github.com/sustatov027-max/url_shortener/blob/main/pkg/generator/generator.go): identifier generator · `pkg/generator/generator.go`

### Persistence

- [Repository contract](https://github.com/sustatov027-max/url_shortener/blob/main/internal/repository/repository.go): storage interface · Persistence boundary consumed by the service. · `internal/repository/repository.go`
- [PostgreSQL setup](https://github.com/sustatov027-max/url_shortener/blob/main/internal/repository/postgres/postgres.go): database adapter · `internal/repository/postgres/postgres.go`
- [URL mapping queries](https://github.com/sustatov027-max/url_shortener/blob/main/internal/repository/postgres/url.go): PostgreSQL repository · `internal/repository/postgres/url.go`
- **PostgreSQL**: durable datastore · Durable source of URL mappings.

### Schema & Docs

- [Schema migration](https://github.com/sustatov027-max/url_shortener/blob/main/migrations/000001_init_schema.up.sql): SQL migration · Creates the URL mapping schema. · `migrations/000001_init_schema.up.sql`
- [Schema rollback](https://github.com/sustatov027-max/url_shortener/blob/main/migrations/000001_init_schema.down.sql): SQL migration · Rolls back the initial schema. · `migrations/000001_init_schema.down.sql`
- [OpenAPI documents](https://github.com/sustatov027-max/url_shortener/blob/main/cmd/app/docs/swagger.yaml): generated API docs · Published handler contract for API clients. · `cmd/app/docs/swagger.yaml`
- [Embedded Swagger](https://github.com/sustatov027-max/url_shortener/blob/main/cmd/app/docs/docs.go): generated Go docs · `cmd/app/docs/docs.go`

## Connections

- Application bootstrap → Configuration: loads
- Application bootstrap → PostgreSQL setup: initializes
- Application bootstrap → HTTP router: starts
- HTTP router → URL handler: dispatches requests
- URL handler → URL service: create / resolve
- URL service → Short-code generator: generates code
- URL service → Repository contract: persists / looks up
- URL mapping queries → Repository contract: implements
- PostgreSQL setup → URL mapping queries: provides connection
- URL mapping queries → PostgreSQL: queries mappings
- Schema migration → PostgreSQL: creates schema
- Schema rollback → PostgreSQL: rolls back schema
- Embedded Swagger → OpenAPI documents: generated from
- URL handler → OpenAPI documents: documents contract
- Container deployment → Application bootstrap: runs
- Compose stack → Container deployment: orchestrates
- Compose stack → PostgreSQL: provisions