API Gateway — Agent Instructions

Service Overview

This is the Unigox API Gateway. It authenticates partners via X-API-Key and proxies requests to backend microservices (account, verification, trades, currencies, offers). It does not have its own database.

Architecture

• internal/handler/router.go — All route definitions. Partner routes require API key middleware.

• internal/handler/handler.go — Proxy handlers with path transformations for each backend service.

• internal/models/config.go — Environment variable configuration.

• docs/swagger.yaml — Internal OpenAPI specification (not the public-facing one).

Path Transformations

The gateway transforms some paths before proxying. Key mappings:

Gateway Path	Backend Path	Service
/partner/users/{id}/kyc-submissions	/partner/kyc-submissions/{id}	verification
/partner/users/{id}/verification-status	/partner/verification-status/{id}	verification
/partner/users/{id}/kyc/documents	/partner/{id}/kyc/documents	verification
/partner/users/{id}/kyc	/partner/users/{id}/kyc	verification (no transform)

When adding new routes, check handler.go to see if a path transformation is needed for the target service.

Adding New Routes

1. Add the route in router.go under the correct group (public or partner).

2. Point it to the correct proxy handler (ProxyAccount, ProxyVerification, ProxyTrades, etc.).

3. If the backend service expects a different path format, add a transformation in the proxy handler in handler.go.

4. Update docs/swagger.yaml with the new endpoint documentation.

Swagger Documentation

Two swagger files exist:

• docs/swagger.yaml — Internal API documentation (this repo).

• Unigox/api-guides/openapi/swagger.yaml — Public-facing partner documentation (separate repo).

Both must be updated when adding or changing partner API endpoints.

E2E Testing

When to run E2E tests: After any change to routing, proxy logic, path transformations, or when backend services add new partner API endpoints that flow through this gateway.

See E2E_TESTING.md for the full end-to-end testing guide. It covers:

• Local Docker service setup (all 5 backend services + infrastructure)

• Test partner and route config creation in PostgreSQL

• 6 test cases covering user creation, KYC, payment details, offramp, and regression

• Known local environment issues and workarounds

• Debugging tips for cross-service failures

Run E2E tests locally before pushing changes that affect partner API flows.

Code Style

Follow the root-level CLAUDE.md rules at /Users/a/unigox/CLAUDE.md. Key points for this service:

• No business logic in the gateway — it only proxies and transforms paths.

• Keep routes in router.go, not in separate files.

• HTTP responses must not contain internal data (stack traces, internal IDs).