# afloresc/ipquery architecture

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

- Interactive diagram: https://gitdiagram.com/afloresc/ipquery
- Repository: https://github.com/afloresc/ipquery

## Overview

#### Purpose and runtime
IPQuery is a Go HTTP microservice that returns normalized IP intelligence, including ISP, geolocation, and risk data. It exposes a versioned REST API, fronts an external IP-information provider, caches results in process memory, and is containerizable for platforms such as Render.

#### Entry point and composition
`cmd/server/main.go` is the application entry point. It is responsible for process startup and wiring the HTTP router, IP-info service/provider, logging, and server configuration. The service is intended to bind using environment-provided port configuration, including Render’s `PORT`.

Paths:
- `cmd/server/main.go`
- `Dockerfile`

#### HTTP boundary and API routing
The HTTP layer owns public endpoints and request/response behavior:
- `GET /v1/health` provides liveness/operational status.
- `GET /v1/ip/{ip}` resolves intelligence for the requested IP.

Routing and HTTP-specific concerns are separated from domain lookup logic, so handlers translate inbound requests into service calls and serialize JSON responses/errors.

Paths:
- `internal/handlers/routes.go`
- `internal/handlers/http.go`

#### Request protection and middleware pipeline
Requests pass through operational and security middleware before reaching handlers. README-defined controls include structured request logging, panic recovery, strict timeouts, rate limiting, CORS restrictions, security headers, and client-IP handling via `X-Forwarded-For` protection. This is the principal trust boundary between internet-facing traffic and lookup execution.

Paths:
- `internal/handlers/routes.go`
- `internal/logger/middleware.go`

#### IP intelligence domain service
The IP-info layer contains the core lookup orchestration: it validates/uses the requested IP, checks cached data, calls the provider on a miss, and returns a unified result shape to handlers. This isolates external-provider-specific behavior from the API contract.

Paths:
- `internal/ipinfo/service.go`
- `internal/ipinfo/provider.go`

#### Caching and resilience boundary
Lookup results are cached in memory using `sync.Map` with a one-hour lifetime, reducing latency and external API dependence. Provider calls are guarded by strict timeouts; failures are surfaced through the HTTP layer rather than destabilizing the process. Cache state is local to one service instance and is lost on restart or not shared across replicas.

Paths:
- `internal/ipinfo/service.go`
- `internal/ipinfo/provider.go`

#### Observability and deployment
Logging is structured JSON using Go’s `slog`, implemented as HTTP middleware for cloud-log ingestion and request tracing/diagnosis. The Docker build artifact supports container deployment; Render is the documented target and consumes the health endpoint for service checks.

Paths:
- `internal/logger/middleware.go`
- `Dockerfile`
- `cmd/server/main.go`

Main entry points: [`internal/handlers/routes.go`](https://github.com/afloresc/ipquery/blob/main/internal/handlers/routes.go) (API router), [`internal/handlers/http.go`](https://github.com/afloresc/ipquery/blob/main/internal/handlers/http.go) (HTTP handlers), [`internal/ipinfo/service.go`](https://github.com/afloresc/ipquery/blob/main/internal/ipinfo/service.go) (IP lookup service), [`cmd/server/main.go`](https://github.com/afloresc/ipquery/blob/main/cmd/server/main.go) (Server bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Service Runtime"]
  node_container["Docker image<br/>container build"]
  node_server["Server bootstrap<br/>Go entry point<br/>[main.go]"]
end

subgraph group_http["HTTP Boundary"]
  node_router["API router<br/>routing + middleware<br/>[routes.go]"]
  node_handlers["HTTP handlers<br/>REST handlers<br/>[http.go]"]
  node_logging["Request logging<br/>slog middleware<br/>[middleware.go]"]
end

subgraph group_domain["IP Intelligence"]
  node_service["IP lookup service<br/>domain service<br/>[service.go]"]
  node_cache[("In-memory cache<br/>sync.Map cache<br/>[service.go]")]
  node_provider["Provider adapter<br/>IP-info provider<br/>[provider.go]"]
end

subgraph group_external["External Systems"]
  node_clients(("Internet clients<br/>HTTP clients"))
  node_ip_provider{{"External IP provider<br/>third-party API"}}
  node_render{{"Render platform<br/>deployment platform"}}
end

node_container -->|"packages"| node_server
node_render -->|"deploys"| node_container
node_render -.->|"PORT"| node_server
node_clients -->|"HTTP requests"| node_router
node_router -->|"request logging"| node_logging
node_router -->|"middleware-protected routes"| node_handlers
node_handlers -->|"GET /v1/ip/&#123;ip&#125;"| node_service
node_handlers -.->|"GET /v1/health"| node_render
node_service -->|"read/write results"| node_cache
node_service -->|"cache miss"| node_provider
node_provider -->|"timeout-bounded lookup"| node_ip_provider
node_logging -.->|"structured logs"| node_server

click node_container "https://github.com/afloresc/ipquery/blob/main/Dockerfile"
click node_server "https://github.com/afloresc/ipquery/blob/main/cmd/server/main.go"
click node_router "https://github.com/afloresc/ipquery/blob/main/internal/handlers/routes.go"
click node_handlers "https://github.com/afloresc/ipquery/blob/main/internal/handlers/http.go"
click node_logging "https://github.com/afloresc/ipquery/blob/main/internal/logger/middleware.go"
click node_service "https://github.com/afloresc/ipquery/blob/main/internal/ipinfo/service.go"
click node_cache "https://github.com/afloresc/ipquery/blob/main/internal/ipinfo/service.go"
click node_provider "https://github.com/afloresc/ipquery/blob/main/internal/ipinfo/provider.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_container,node_server toneBlue
class node_router,node_handlers,node_logging toneAmber
class node_service,node_cache,node_provider toneMint
class node_clients,node_ip_provider,node_render toneRose
```

## Components

### Service Runtime

- [Docker image](https://github.com/afloresc/ipquery/blob/main/Dockerfile): container build · Container artifact for deployment platforms. · `Dockerfile`
- [Server bootstrap](https://github.com/afloresc/ipquery/blob/main/cmd/server/main.go): Go entry point · Wires router, IP service, logging, and port configuration. · `cmd/server/main.go`

### HTTP Boundary

- [API router](https://github.com/afloresc/ipquery/blob/main/internal/handlers/routes.go): routing + middleware · Applies request protection before versioned endpoints. · `internal/handlers/routes.go`
- [HTTP handlers](https://github.com/afloresc/ipquery/blob/main/internal/handlers/http.go): REST handlers · Serves health and IP lookup JSON responses. · `internal/handlers/http.go`
- [Request logging](https://github.com/afloresc/ipquery/blob/main/internal/logger/middleware.go): slog middleware · Emits structured JSON request logs. · `internal/logger/middleware.go`

### IP Intelligence

- [IP lookup service](https://github.com/afloresc/ipquery/blob/main/internal/ipinfo/service.go): domain service · Coordinates cache lookup, provider calls, and normalized results. · `internal/ipinfo/service.go`
- [In-memory cache](https://github.com/afloresc/ipquery/blob/main/internal/ipinfo/service.go): sync.Map cache · Per-instance results cached for one hour. · `internal/ipinfo/service.go`
- [Provider adapter](https://github.com/afloresc/ipquery/blob/main/internal/ipinfo/provider.go): IP-info provider · Executes timeout-bounded external intelligence requests. · `internal/ipinfo/provider.go`

### External Systems

- **Internet clients**: HTTP clients
- **External IP provider**: third-party API
- **Render platform**: deployment platform · Supplies PORT and checks service health.

## Connections

- Docker image → Server bootstrap: packages
- Render platform → Docker image: deploys
- Render platform → Server bootstrap: PORT
- Internet clients → API router: HTTP requests
- API router → Request logging: request logging
- API router → HTTP handlers: middleware-protected routes
- HTTP handlers → IP lookup service: GET /v1/ip/{ip}
- HTTP handlers → Render platform: GET /v1/health
- IP lookup service → In-memory cache: read/write results
- IP lookup service → Provider adapter: cache miss
- Provider adapter → External IP provider: timeout-bounded lookup
- Request logging → Server bootstrap: structured logs