# divineninja/usld-go-api architecture

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

- Interactive diagram: https://gitdiagram.com/divineninja/usld-go-api
- Repository: https://github.com/divineninja/usld-go-api

## Overview

This Go service exposes one listings endpoint: an HTTP client requests listings, the handler queries the MySQL-backed listing view, checks a short-lived in-memory response cache, maps rows into listing JSON, and returns the response. Startup initializes the database from environment variables and registers the route. The tree and sampled source show no other product workflows; the DTO file defines response fields and conversion helpers, though the handler performs its own row mapping.

Main entry points: [`go/api/listing.go`](https://github.com/divineninja/usld-go-api/blob/main/go/api/listing.go) (Listings handler), [`go/db/db.go`](https://github.com/divineninja/usld-go-api/blob/main/go/db/db.go) (MySQL initialization), [`go/main.go`](https://github.com/divineninja/usld-go-api/blob/main/go/main.go) (Service startup), [`go/api/listing_cache.go`](https://github.com/divineninja/usld-go-api/blob/main/go/api/listing_cache.go) (Response cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["HTTP service"]
  node_main["Service startup<br/>[main.go]"]
  node_handler["Listings handler<br/>[listing.go]"]
  node_dto["Listing response DTO<br/>[listing_dto.go]"]
end

subgraph group_data["Listing data"]
  node_cache[("Response cache<br/>[listing_cache.go]")]
  node_dbinit["MySQL initialization<br/>[db.go]"]
end

node_client(("HTTP client"))
node_mysql[("MySQL database")]
node_env(("Environment variables"))
node_response["JSON response"]

node_main -->|"initializes"| node_dbinit
node_env -->|"configures"| node_dbinit
node_dbinit -->|"opens connection"| node_mysql
node_main -->|"registers route"| node_handler
node_client -->|"requests listings"| node_handler
node_handler -->|"queries listing view"| node_mysql
node_handler -->|"reads cache"| node_cache
node_handler -->|"writes response"| node_cache
node_handler -->|"uses conversion helpers"| node_dto
node_handler -->|"marshals and writes"| node_response
node_response -->|"returns JSON"| node_client

click node_main "https://github.com/divineninja/usld-go-api/blob/main/go/main.go"
click node_handler "https://github.com/divineninja/usld-go-api/blob/main/go/api/listing.go"
click node_dto "https://github.com/divineninja/usld-go-api/blob/main/go/api/listing_dto.go"
click node_cache "https://github.com/divineninja/usld-go-api/blob/main/go/api/listing_cache.go"
click node_dbinit "https://github.com/divineninja/usld-go-api/blob/main/go/db/db.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_main,node_handler,node_dto,node_client toneBlue
class node_cache,node_dbinit,node_mysql toneAmber
class node_env,node_response toneIndigo
```

## Components

### HTTP service

- [Service startup](https://github.com/divineninja/usld-go-api/blob/main/go/main.go): `go/main.go`
- [Listings handler](https://github.com/divineninja/usld-go-api/blob/main/go/api/listing.go): `go/api/listing.go`
- [Listing response DTO](https://github.com/divineninja/usld-go-api/blob/main/go/api/listing_dto.go): `go/api/listing_dto.go`

### Listing data

- [Response cache](https://github.com/divineninja/usld-go-api/blob/main/go/api/listing_cache.go): `go/api/listing_cache.go`
- [MySQL initialization](https://github.com/divineninja/usld-go-api/blob/main/go/db/db.go): `go/db/db.go`

### Other components

- **HTTP client**
- **MySQL database**
- **Environment variables**
- **JSON response**

## Connections

- Service startup → MySQL initialization: initializes
- Environment variables → MySQL initialization: configures
- MySQL initialization → MySQL database: opens connection
- Service startup → Listings handler: registers route
- HTTP client → Listings handler: requests listings
- Listings handler → MySQL database: queries listing view
- Listings handler → Response cache: reads cache
- Listings handler → Response cache: writes response
- Listings handler → Listing response DTO: uses conversion helpers
- Listings handler → JSON response: marshals and writes
- JSON response → HTTP client: returns JSON