# apollo-level2-web-dev/gotickets architecture

> Architecture diagram of the GitHub repository apollo-level2-web-dev/gotickets, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apollo-level2-web-dev/gotickets
- Repository: https://github.com/apollo-level2-web-dev/gotickets

## Overview

1. **Overall shape**
   GoTickets is a layered Go REST API for ticket booking. The repository is organized around three business domains — user, event, and booking — with shared infrastructure for config, HTTP server setup, authentication, middleware, and uniform error responses.

2. **Application entrypoint and startup flow**
   `cmd/main.go` is the bootstrapping point. Startup likely follows this order: load environment variables, build configuration, open the PostgreSQL connection, initialize the Echo server, register routes, and start listening on the configured port.

3. **Configuration and persistence boundary**
   `internal/config` owns environment-driven setup. `config.go` reads values like `PORT` and `JWT_SECRET`, while `db.go` creates the GORM/PostgreSQL connection from the `DSN`. The database layer is not a separate service; it is shared infrastructure used by all domain repositories.

4. **HTTP server and routing boundary**
   `internal/server/http.go` is the central composition point for the web layer. It creates the Echo instance, attaches middleware, registers feature routes, and exposes a health endpoint. This package is the boundary between external HTTP traffic and the domain layer.

5. **Domain-oriented feature modules**
   Each business area lives under `internal/domain/<feature>`:
   - `user` for registration, login, and profile lookup
   - `event` for event management
   - `booking` for reserving tickets and listing a user’s bookings  
   Each domain contains its own handler, service, repository, entity, route registration, and DTOs, so the feature boundaries are explicit and self-contained.

6. **Request/response shaping with DTOs**
   Each domain has `dto/request.go` and `dto/response.go` packages. These are the API contract layer: handlers use request DTOs for validation/parsing and response DTOs to control what leaves the service boundary. This keeps HTTP payloads separate from database entities.

7. **Handler → service → repository flow**
   The core runtime path is consistent across features:
   - routes map URLs to handlers
   - handlers parse/validate input and build responses
   - services hold business rules
   - repositories execute GORM queries  
   This separation is the main architectural pattern in the repo and is the most important thing to show in a diagram.

8. **Authentication subsystem**
   `internal/auth/jwt.go` implements token creation/validation. `internal/domain/user` is the identity source for login and current-user lookup. The auth boundary is enforced at the HTTP layer, not inside repositories.

9. **Protected routes and middleware**
   `internal/middlewares/auth.go` guards protected endpoints such as bookings and `GET /auth/me`. The middleware validates the Bearer token, extracts user context, and makes that identity available to downstream handlers/services. This is the key cross-cutting concern in the system.

10. **Business rules by domain**
   The booking service is where ticket availability and reservation logic belongs; it depends on both event and user data. Event handlers/services manage event CRUD-style operations. User handlers/services manage registration, login, and profile access. The main business coupling is booking’s dependency on event inventory and authenticated user identity.

11. **Database model and schema management**
   Domain entities map to GORM models, and the README indicates tables are created via `AutoMigrate` on startup. There is no dedicated migrations subsystem in the tree, so schema creation is embedded in application initialization rather than handled externally.

12. **Shared HTTP error formatting**
   `internal/httpresponse/error.go` suggests a common error-response shape used across handlers. This is a small but important shared contract for consistent API responses and easier client consumption.

13. **Operational/tooling concerns**
   `.air.toml` enables live reload during development, and `.env.example` documents runtime configuration. The repo is a Go module with Echo, GORM, PostgreSQL, JWT, validation, and godotenv as the practical runtime stack; these materially define how the app starts, validates input, and persists data.

14. **Diagram takeaway**
   A good architecture diagram for this repo should show:
   external HTTP clients → Echo server → middleware/auth gate → domain handlers → services → repositories → PostgreSQL,
   with JWT auth as a supporting subsystem and config/database initialization as the startup foundation. The main internal boundaries are by domain feature rather than by technical layer alone.

Main entry points: [`internal/server/http.go`](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/server/http.go) (HTTP Server), [`internal/config/db.go`](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/config/db.go) (Database), [`internal/domain/booking/service.go`](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/booking/service.go) (Booking Rules), [`internal/domain/user/handler.go`](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/user/handler.go) (User API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup & infra"]
  node_cmd_main["Main<br/>entrypoint<br/>[main.go]"]
  node_config["Config<br/>[config.go]"]
  node_db[("Database<br/>gorm postgres<br/>[db.go]")]
end

subgraph group_web["HTTP layer"]
  node_server["HTTP Server<br/>echo setup<br/>[http.go]"]
  node_auth_mw{{"Auth Guard<br/>middleware<br/>[auth.go]"}}
  node_err_resp["Error JSON<br/>response shape<br/>[error.go]"]
  node_jwt["JWT<br/>token auth<br/>[jwt.go]"]
end

subgraph group_domains["Business domains"]
  node_user_handler["User API<br/>handler<br/>[handler.go]"]
  node_user_service["User Rules<br/>[service.go]"]
  node_user_repo[("User Store<br/>[repository.go]")]
  node_event_handler["Event API<br/>handler<br/>[handler.go]"]
  node_event_service["Event Rules<br/>[service.go]"]
  node_event_repo[("Event Store<br/>[repository.go]")]
  node_booking_handler["Booking API<br/>handler<br/>[handler.go]"]
  node_booking_service["Booking Rules<br/>[service.go]"]
  node_booking_repo[("Booking Store<br/>[repository.go]")]
end

node_cmd_main -->|"loads"| node_config
node_cmd_main -->|"opens"| node_db
node_cmd_main -->|"starts"| node_server
node_config -->|"DSN"| node_db
node_config -->|"port"| node_server
node_server -->|"attaches"| node_auth_mw
node_server -->|"uses"| node_err_resp
node_server -->|"routes"| node_user_handler
node_server -->|"routes"| node_event_handler
node_server -->|"routes"| node_booking_handler
node_user_handler -->|"calls"| node_user_service
node_user_service -->|"queries"| node_user_repo
node_user_handler -->|"issues"| node_jwt
node_event_handler -->|"calls"| node_event_service
node_event_service -->|"queries"| node_event_repo
node_booking_handler -->|"calls"| node_booking_service
node_booking_service -->|"queries"| node_booking_repo
node_booking_service -->|"checks"| node_event_repo
node_booking_service -->|"uses"| node_user_repo
node_auth_mw -->|"verifies"| node_jwt
node_auth_mw -.->|"protects"| node_user_handler
node_db -->|"backing store"| node_user_repo
node_db -->|"backing store"| node_event_repo
node_db -->|"backing store"| node_booking_repo

click node_cmd_main "https://github.com/apollo-level2-web-dev/gotickets/blob/main/cmd/main.go"
click node_config "https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/config/config.go"
click node_db "https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/config/db.go"
click node_server "https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/server/http.go"
click node_auth_mw "https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/middlewares/auth.go"
click node_err_resp "https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/httpresponse/error.go"
click node_jwt "https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/auth/jwt.go"
click node_user_handler "https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/user/handler.go"
click node_user_service "https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/user/service.go"
click node_user_repo "https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/user/repository.go"
click node_event_handler "https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/event/handler.go"
click node_event_service "https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/event/service.go"
click node_event_repo "https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/event/repository.go"
click node_booking_handler "https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/booking/handler.go"
click node_booking_service "https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/booking/service.go"
click node_booking_repo "https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/booking/repository.go"

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_main,node_config,node_db toneBlue
class node_server,node_auth_mw,node_err_resp,node_jwt toneAmber
class node_user_handler,node_user_service,node_user_repo,node_event_handler,node_event_service,node_event_repo,node_booking_handler,node_booking_service,node_booking_repo toneMint
```

## Components

### Startup & infra

Application bootstrapping, configuration, database setup, and shared HTTP concerns

- [Main](https://github.com/apollo-level2-web-dev/gotickets/blob/main/cmd/main.go): entrypoint · Bootstraps the application and starts the HTTP server · `cmd/main.go`
- [Config](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/config/config.go): env config · Loads runtime settings such as port, JWT secret, and DB DSN · `internal/config/config.go`
- [Database](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/config/db.go): gorm postgres · Builds the PostgreSQL/GORM connection shared by all repositories · `internal/config/db.go`

### HTTP layer

Echo server composition, routing, middleware, and shared response handling

- [HTTP Server](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/server/http.go): echo setup · Creates Echo, wires routes and middleware, and exposes the web entrypoint · `internal/server/http.go`
- [Auth Guard](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/middlewares/auth.go): middleware · Validates Bearer tokens and injects user context for protected routes · `internal/middlewares/auth.go`
- [Error JSON](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/httpresponse/error.go): response shape · Shared error-response formatting used across handlers · `internal/httpresponse/error.go`
- [JWT](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/auth/jwt.go): token auth · Creates and validates authentication tokens · `internal/auth/jwt.go`

### Business domains

User, event, and booking feature modules

- [User API](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/user/handler.go): handler · Handles registration, login, and profile lookup requests · `internal/domain/user/handler.go`
- [User Rules](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/user/service.go): service · Implements identity and profile business logic · `internal/domain/user/service.go`
- [User Store](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/user/repository.go): repository · Persists and loads user records via GORM · `internal/domain/user/repository.go`
- [Event API](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/event/handler.go): handler · Handles event management requests · `internal/domain/event/handler.go`
- [Event Rules](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/event/service.go): service · Implements event management business logic · `internal/domain/event/service.go`
- [Event Store](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/event/repository.go): repository · Persists and loads events via GORM · `internal/domain/event/repository.go`
- [Booking API](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/booking/handler.go): handler · Handles ticket reservation and booking-list requests · `internal/domain/booking/handler.go`
- [Booking Rules](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/booking/service.go): service · Coordinates reservation logic, ticket availability, and user identity · `internal/domain/booking/service.go`
- [Booking Store](https://github.com/apollo-level2-web-dev/gotickets/blob/main/internal/domain/booking/repository.go): repository · Persists and loads bookings via GORM · `internal/domain/booking/repository.go`

## Connections

- Main → Config: loads · Reads environment-driven runtime settings
- Main → Database: opens · Initializes the shared PostgreSQL connection
- Main → HTTP Server: starts · Builds the web server and begins listening
- Config → Database: DSN · Supplies database connection settings
- Config → HTTP Server: port · Supplies HTTP listen configuration
- HTTP Server → Auth Guard: attaches · Installs authentication middleware on protected routes
- HTTP Server → Error JSON: uses · Shares consistent error formatting across endpoints
- HTTP Server → User API: routes · Registers user endpoints
- HTTP Server → Event API: routes · Registers event endpoints
- HTTP Server → Booking API: routes · Registers booking endpoints
- User API → User Rules: calls · Delegates request handling to business logic
- User Rules → User Store: queries · Reads and writes user records
- User API → JWT: issues · Creates tokens during login
- Event API → Event Rules: calls · Delegates request handling to business logic
- Event Rules → Event Store: queries · Reads and writes event records
- Booking API → Booking Rules: calls · Delegates request handling to business logic
- Booking Rules → Booking Store: queries · Reads and writes booking records
- Booking Rules → Event Store: checks · Verifies event inventory and availability
- Booking Rules → User Store: uses · Resolves authenticated user identity
- Auth Guard → JWT: verifies · Validates the Bearer token on protected requests
- Auth Guard → User API: protects · Gates profile and auth-me style endpoints
- Database → User Store: backing store · Shared persistence connection for user data
- Database → Event Store: backing store · Shared persistence connection for event data
- Database → Booking Store: backing store · Shared persistence connection for booking data