card-to-iban/README.md

Card to IBAN

A small full-stack application that converts an Iranian bank card number to its IBAN through ZarinHub.

• Backend: Go, net/http, SQLite
• Frontend: Nuxt, Vue, Tailwind CSS
• API documentation: OpenAPI 3.0 and Swagger UI

Quick start with Docker

Copy the environment template and add your ZarinHub API credentials:

Copy-Item .env.sample .env

ZARINHUB_API_USERNAME=your-api-username
ZARINHUB_API_PASSWORD=your-api-password

Build and start the application:

docker compose up --build

Open:

• App: http://127.0.0.1:3000
• Health check: http://127.0.0.1:8080/health
• Swagger UI: http://127.0.0.1:8080/docs/
• OpenAPI document: http://127.0.0.1:8080/openapi.json

After backend changes, restart it or run docker compose up --build again so the running container uses the latest code.

Local development

Start the backend:

cd backend
go run ./cmd/api

Start the frontend in another terminal:

cd frontend
npm ci
npm run dev

The backend loads .env from the project root. The frontend uses http://127.0.0.1:8080 by default; override it with NUXT_PUBLIC_API_BASE_URL when needed.

API

POST /api/v1/card-to-iban
Content-Type: application/json

{"card":"6037997512345678"}

Successful response:

{
  "data": {
    "iban": "IR820540102680020817909002"
  },
  "requestId": "SERVER_GENERATED_REQUEST_ID"
}

Errors use the same requestId returned in the X-Request-ID header. See Swagger UI for the complete request, response, and error contract.

Implementation notes

• The backend validates card numbers and refreshes ZarinHub access tokens automatically.
• Every conversion attempt is audited in SQLite.
• Card numbers and upstream responses are sanitized before storage; credentials and tokens are not persisted.
• Unknown frontend routes display a branded 404 page with a link back to the application.
• SQLite data is stored in the card_to_iban_data Docker volume when using Compose.

Tests

cd backend
go test ./...
go vet ./...

cd frontend
npm test
npm run build