99 lines
2.1 KiB
Markdown
99 lines
2.1 KiB
Markdown
# 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:
|
|
|
|
```powershell
|
|
Copy-Item .env.sample .env
|
|
```
|
|
|
|
```env
|
|
ZARINHUB_API_USERNAME=your-api-username
|
|
ZARINHUB_API_PASSWORD=your-api-password
|
|
```
|
|
|
|
Build and start the application:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
cd backend
|
|
go run ./cmd/api
|
|
```
|
|
|
|
Start the frontend in another terminal:
|
|
|
|
```powershell
|
|
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
|
|
|
|
```http
|
|
POST /api/v1/card-to-iban
|
|
Content-Type: application/json
|
|
|
|
{"card":"6037997512345678"}
|
|
```
|
|
|
|
Successful response:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```powershell
|
|
cd backend
|
|
go test ./...
|
|
go vet ./...
|
|
```
|
|
|
|
```powershell
|
|
cd frontend
|
|
npm test
|
|
npm run build
|
|
```
|