How aojedacs/go-url-shortener works
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: handler.go Handler · service.go Service · main.go Main · posgres.go DB Adapter
Components 7
Runtime
Executable entrypoint and process wiring
Application
HTTP transport and business logic
Data
Database integration and durable storage
- DB Adapter · Connects the app to PostgreSQL and manages URL mappings
internal/database/posgres.go - PostgreSQL · Persistent storage for shortened URL records
Other components
- Client · Sends URL shortening requests
Connections 9
- 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