# lelecodedev/villa-backend architecture

> Architecture diagram of the GitHub repository lelecodedev/villa-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lelecodedev/villa-backend
- Repository: https://github.com/lelecodedev/villa-backend

## Overview

This is a Go backend for villa-site content and administration. Its principal workflow is an HTTP request routed to a feature handler, processed by a service, and persisted through repositories to PostgreSQL; authentication additionally validates credentials and issues JWTs. The tree shows distinct content domains for applications, hero sections, FAQs, galleries, testimonials, villa packages, and package lists. Wiring and authentication are supported by sampled source; other feature internals are inferred from the tree, so their repository-level call paths are not expanded.

Main entry points: [`internal/bootstrap/route.go`](https://github.com/lelecodedev/villa-backend/blob/main/internal/bootstrap/route.go) (Route registration), [`internal/service`](https://github.com/lelecodedev/villa-backend/tree/main/internal/service) (Content services), [`internal/service/auth_service.go`](https://github.com/lelecodedev/villa-backend/blob/main/internal/service/auth_service.go) (Auth service), [`internal/service/villa_package_service.go`](https://github.com/lelecodedev/villa-backend/blob/main/internal/service/villa_package_service.go) (Package service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["HTTP runtime"]
  node_app["App composition<br/>[app.go]"]
  node_routes["Route registration<br/>[route.go]"]
  node_authmw["Auth middleware<br/>[auth_middleware.go]"]
  node_rolemw["Role middleware<br/>[role_middleware.go]"]
end

subgraph group_identity["Identity"]
  node_authhandler["Auth endpoints<br/>[auth_handler.go]"]
  node_authservice["Auth service<br/>[auth_service.go]"]
  node_users["User repository<br/>[user_repository.go]"]
  node_jwt["JWT tokens<br/>[jwt.go]"]
end

subgraph group_content["Site content"]
  node_applications["Applications"]
  node_hero["Hero sections"]
  node_faqs["FAQs<br/>[faq_handler.go]"]
  node_gallery["Gallery<br/>[gallery_handler.go]"]
  node_testimonials["Testimonials"]
  node_applicationservice["Application service"]
  node_contentservices["Content services"]
  node_contentrepos["Content repositories"]
end

subgraph group_packages["Villa packages"]
  node_packageshandler["Package endpoints"]
  node_lists_handler["Package-list endpoints"]
  node_packageservice["Package service"]
  node_listsservice["Package-list service"]
  node_packagerepo["Package repository"]
  node_listsrepo["Package-list repository"]
end

subgraph group_storage["Persistence"]
  node_tx["Transaction manager<br/>[tx_manager.go]"]
  node_database["DB connection<br/>[database.go]"]
  node_postgres[("PostgreSQL")]
end

node_client(("API client"))

node_client -->|"sends requests"| node_routes
node_app -->|"opens connection"| node_database
node_app -->|"registers routes"| node_routes
node_routes -->|"dispatches"| node_authhandler
node_routes -->|"dispatches"| node_applications
node_routes -->|"dispatches"| node_hero
node_routes -->|"dispatches"| node_faqs
node_routes -->|"dispatches"| node_gallery
node_routes -->|"dispatches"| node_testimonials
node_routes -->|"dispatches"| node_packageshandler
node_routes -->|"dispatches"| node_lists_handler
node_authhandler -->|"calls"| node_authservice
node_authservice -->|"reads and writes"| node_users
node_authservice -->|"runs transaction"| node_tx
node_authservice -->|"issues token"| node_jwt
node_applications -->|"handles requests"| node_applicationservice
node_hero -->|"handles requests"| node_contentservices
node_faqs -->|"handles requests"| node_contentservices
node_gallery -->|"handles requests"| node_contentservices
node_testimonials -->|"handles requests"| node_contentservices
node_contentservices -->|"persists content"| node_contentrepos
node_packageshandler -->|"handles requests"| node_packageservice
node_lists_handler -->|"handles requests"| node_listsservice
node_packageservice -->|"reads and writes"| node_packagerepo
node_packageservice -->|"reads and writes"| node_listsrepo
node_listsservice -->|"reads and writes"| node_listsrepo
node_packagerepo -->|"queries"| node_postgres
node_listsrepo -->|"queries"| node_postgres
node_database -->|"connects"| node_postgres
node_users -->|"queries"| node_postgres

click node_app "https://github.com/lelecodedev/villa-backend/blob/main/internal/bootstrap/app.go"
click node_routes "https://github.com/lelecodedev/villa-backend/blob/main/internal/bootstrap/route.go"
click node_authmw "https://github.com/lelecodedev/villa-backend/blob/main/internal/middleware/auth_middleware.go"
click node_rolemw "https://github.com/lelecodedev/villa-backend/blob/main/internal/middleware/role_middleware.go"
click node_authhandler "https://github.com/lelecodedev/villa-backend/blob/main/internal/handler/auth_handler.go"
click node_authservice "https://github.com/lelecodedev/villa-backend/blob/main/internal/service/auth_service.go"
click node_users "https://github.com/lelecodedev/villa-backend/blob/main/internal/repository/user_repository.go"
click node_jwt "https://github.com/lelecodedev/villa-backend/blob/main/pkg/jwt/jwt.go"
click node_applications "https://github.com/lelecodedev/villa-backend/blob/main/internal/handler/application_handler.go"
click node_hero "https://github.com/lelecodedev/villa-backend/blob/main/internal/handler/hero_section_handler.go"
click node_faqs "https://github.com/lelecodedev/villa-backend/blob/main/internal/handler/faq_handler.go"
click node_gallery "https://github.com/lelecodedev/villa-backend/blob/main/internal/handler/gallery_handler.go"
click node_testimonials "https://github.com/lelecodedev/villa-backend/blob/main/internal/handler/testimony_handler.go"
click node_applicationservice "https://github.com/lelecodedev/villa-backend/blob/main/internal/service/application_service.go"
click node_contentservices "https://github.com/lelecodedev/villa-backend/tree/main/internal/service"
click node_contentrepos "https://github.com/lelecodedev/villa-backend/tree/main/internal/repository"
click node_packageshandler "https://github.com/lelecodedev/villa-backend/blob/main/internal/handler/villa_package_handler.go"
click node_lists_handler "https://github.com/lelecodedev/villa-backend/blob/main/internal/handler/villa_package_list_handler.go"
click node_packageservice "https://github.com/lelecodedev/villa-backend/blob/main/internal/service/villa_package_service.go"
click node_listsservice "https://github.com/lelecodedev/villa-backend/blob/main/internal/service/villa_package_list_service.go"
click node_packagerepo "https://github.com/lelecodedev/villa-backend/blob/main/internal/repository/villa_package_repository.go"
click node_listsrepo "https://github.com/lelecodedev/villa-backend/blob/main/internal/repository/villa_package_list_repository.go"
click node_tx "https://github.com/lelecodedev/villa-backend/blob/main/internal/repository/tx_manager.go"
click node_database "https://github.com/lelecodedev/villa-backend/blob/main/internal/database/database.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_app,node_routes,node_authmw,node_rolemw,node_client toneBlue
class node_authhandler,node_authservice,node_users,node_jwt toneAmber
class node_applications,node_hero,node_faqs,node_gallery,node_testimonials,node_applicationservice,node_contentservices,node_contentrepos toneMint
class node_packageshandler,node_lists_handler,node_packageservice,node_listsservice,node_packagerepo,node_listsrepo toneRose
class node_tx,node_database,node_postgres toneIndigo
```

## Components

### HTTP runtime

- [App composition](https://github.com/lelecodedev/villa-backend/blob/main/internal/bootstrap/app.go): `internal/bootstrap/app.go`
- [Route registration](https://github.com/lelecodedev/villa-backend/blob/main/internal/bootstrap/route.go): `internal/bootstrap/route.go`
- [Auth middleware](https://github.com/lelecodedev/villa-backend/blob/main/internal/middleware/auth_middleware.go): `internal/middleware/auth_middleware.go`
- [Role middleware](https://github.com/lelecodedev/villa-backend/blob/main/internal/middleware/role_middleware.go): `internal/middleware/role_middleware.go`

### Identity

- [Auth endpoints](https://github.com/lelecodedev/villa-backend/blob/main/internal/handler/auth_handler.go): `internal/handler/auth_handler.go`
- [Auth service](https://github.com/lelecodedev/villa-backend/blob/main/internal/service/auth_service.go): `internal/service/auth_service.go`
- [User repository](https://github.com/lelecodedev/villa-backend/blob/main/internal/repository/user_repository.go): `internal/repository/user_repository.go`
- [JWT tokens](https://github.com/lelecodedev/villa-backend/blob/main/pkg/jwt/jwt.go): `pkg/jwt/jwt.go`

### Site content

- [Applications](https://github.com/lelecodedev/villa-backend/blob/main/internal/handler/application_handler.go): `internal/handler/application_handler.go`
- [Hero sections](https://github.com/lelecodedev/villa-backend/blob/main/internal/handler/hero_section_handler.go): `internal/handler/hero_section_handler.go`
- [FAQs](https://github.com/lelecodedev/villa-backend/blob/main/internal/handler/faq_handler.go): `internal/handler/faq_handler.go`
- [Gallery](https://github.com/lelecodedev/villa-backend/blob/main/internal/handler/gallery_handler.go): `internal/handler/gallery_handler.go`
- [Testimonials](https://github.com/lelecodedev/villa-backend/blob/main/internal/handler/testimony_handler.go): `internal/handler/testimony_handler.go`
- [Application service](https://github.com/lelecodedev/villa-backend/blob/main/internal/service/application_service.go): `internal/service/application_service.go`
- [Content services](https://github.com/lelecodedev/villa-backend/tree/main/internal/service): `internal/service`
- [Content repositories](https://github.com/lelecodedev/villa-backend/tree/main/internal/repository): `internal/repository`

### Villa packages

- [Package endpoints](https://github.com/lelecodedev/villa-backend/blob/main/internal/handler/villa_package_handler.go): `internal/handler/villa_package_handler.go`
- [Package-list endpoints](https://github.com/lelecodedev/villa-backend/blob/main/internal/handler/villa_package_list_handler.go): `internal/handler/villa_package_list_handler.go`
- [Package service](https://github.com/lelecodedev/villa-backend/blob/main/internal/service/villa_package_service.go): `internal/service/villa_package_service.go`
- [Package-list service](https://github.com/lelecodedev/villa-backend/blob/main/internal/service/villa_package_list_service.go): `internal/service/villa_package_list_service.go`
- [Package repository](https://github.com/lelecodedev/villa-backend/blob/main/internal/repository/villa_package_repository.go): `internal/repository/villa_package_repository.go`
- [Package-list repository](https://github.com/lelecodedev/villa-backend/blob/main/internal/repository/villa_package_list_repository.go): `internal/repository/villa_package_list_repository.go`

### Persistence

- [Transaction manager](https://github.com/lelecodedev/villa-backend/blob/main/internal/repository/tx_manager.go): `internal/repository/tx_manager.go`
- [DB connection](https://github.com/lelecodedev/villa-backend/blob/main/internal/database/database.go): `internal/database/database.go`
- **PostgreSQL**

### Other components

- **API client**

## Connections

- API client → Route registration: sends requests
- App composition → DB connection: opens connection
- App composition → Route registration: registers routes
- Route registration → Auth endpoints: dispatches
- Route registration → Applications: dispatches
- Route registration → Hero sections: dispatches
- Route registration → FAQs: dispatches
- Route registration → Gallery: dispatches
- Route registration → Testimonials: dispatches
- Route registration → Package endpoints: dispatches
- Route registration → Package-list endpoints: dispatches
- Auth endpoints → Auth service: calls
- Auth service → User repository: reads and writes
- Auth service → Transaction manager: runs transaction
- Auth service → JWT tokens: issues token
- Applications → Application service: handles requests
- Hero sections → Content services: handles requests
- FAQs → Content services: handles requests
- Gallery → Content services: handles requests
- Testimonials → Content services: handles requests
- Content services → Content repositories: persists content
- Package endpoints → Package service: handles requests
- Package-list endpoints → Package-list service: handles requests
- Package service → Package repository: reads and writes
- Package service → Package-list repository: reads and writes
- Package-list service → Package-list repository: reads and writes
- Package repository → PostgreSQL: queries
- Package-list repository → PostgreSQL: queries
- DB connection → PostgreSQL: connects
- User repository → PostgreSQL: queries