Танилцуулга / Хөгжүүлэгчдэд

Dev workflow

Repo бүтэц, tech stack, local dev setup, CI pipeline, branch strategy, release cadence, observability stack — PSP integrate хийдэг хөгжүүлэгчид болон PayGrid өөрөө хөгжүүлэх инженер бүгдэд.

1. Repository structure

paygrid-mn/                            ← umbrella repo
├── PLAN/                              Engineering spec (16 docs)
├── paygrid-backend/                   Main Go service
│   ├── cmd/
│   │   ├── api/                       Main HTTP service
│   │   ├── clearing/                  Settlement worker
│   │   └── migrate/                   DB migration tool
│   ├── internal/
│   │   ├── alias/                     Alias registry domain
│   │   ├── psp/                       PSP onboarding domain
│   │   ├── routing/                   Routing engine
│   │   ├── frm/                       FRM rules + screening
│   │   ├── settlement/                Settlement engine
│   │   ├── eid/                       e-ID Mongolia X-Road client
│   │   ├── audit/                     Hash-chained audit log
│   │   ├── api/                       HTTP handlers + middleware
│   │   ├── crypto/                    HSM, JWS, mTLS
│   │   └── pg/                        Postgres connection + repos
│   ├── pkg/
│   │   ├── berlingroup/               NextGenPSD2 client/server
│   │   └── iso20022/                  pacs.008/pacs.002 marshalling
│   ├── migrations/                    SQL migrations (atlas / goose)
│   └── tests/                         Integration + E2E
│
├── paygrid-mock-bank/                 Mock Berlin Group PISP
├── paygrid-mock-wallet/               Mock wallet PSP client
├── paygrid-portal/                    Энэ landing platform
├── deploy/                            docker-compose, nginx, bootstrap
└── ops/                               Server provisioning, runbooks

2. Tech stack

3. Local dev quick start

# Clone
git clone github.com/geregedevops/paygrid-mn
cd paygrid-mn/paygrid-backend

# Install pre-commit
pip install pre-commit
pre-commit install

# Start deps
docker-compose up -d postgres redis softhsm

# Run migrations
make migrate-up

# Run tests
make test

# Run E2E
make e2e

# Start API
make run-api

# Health check
curl https://localhost:8443/v1/health/live

4. Sandbox онбоординг

Phase 1 одоогийн single-host sandbox-аар:

• Hostname: paygrid.mn
• Health: https://paygrid.mn/v1/health/live
• OpenAPI: https://paygrid.mn/.well-known/openapi/paygrid-v1.yaml

End-to-end happy path

cd /opt/paygrid-mn/deploy
docker compose --profile smoke run --rm paygrid-mock-wallet

This:
1. Registers `cafemonkey@gerege` against `SBGEREGEMNW` (sandbox wallet PSP)
2. Resolves the alias
3. Initiates a 1000.00 ₮ credit transfer
4. Polls the resulting payment status

Sandbox PSP self-onboarding

POST https://sandbox.paygrid.mn/v1/psp/onboard
{
  "name": "Test Wallet ABC",
  "type": "EMI",
  "country": "MN",
  "contact_email": "tech@testwallet.mn",
  "expected_use_cases": ["P2P", "P2M"],
  "csr": "<base64 PEM CSR for signing key>"
}

Response:
   bic_assigned, client_cert, credentials, sandbox_endpoints

5. Makefile targets

.PHONY: build test lint e2e migrate-up migrate-down run-api

build:
	go build -o bin/paygrid-api ./cmd/api
	go build -o bin/paygrid-clearing ./cmd/clearing

test:
	go test -race -cover ./...

lint:
	golangci-lint run ./...
	gosec -quiet ./...
	govulncheck ./...

e2e:
	go test -tags=e2e ./tests/e2e/...

migrate-up:
	atlas migrate apply --env local

migrate-down:
	atlas migrate down --env local

run-api:
	go run ./cmd/api -config=./config/local.yaml

docker-build:
	docker build -t paygrid-api:dev -f deploy/docker/api.Dockerfile .

sqlc-generate:
	sqlc generate

openapi-gen:
	oapi-codegen -package api -generate types,server,spec \
	    docs/openapi/paygrid-v1.yaml > internal/api/generated.go

6. CI pipeline

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres: { image: postgres:16-alpine, env: { POSTGRES_PASSWORD: testpass }, ports: ['5432:5432'] }
      redis:    { image: redis:7-alpine, ports: ['6379:6379'] }
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with: { go-version: '1.24' }
      - run: make build
      - run: make migrate-up
      - run: make test
      - run: make e2e

  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
      - run: golangci-lint run ./...

  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: gosec -quiet ./...
      - run: govulncheck ./...
      - uses: gitleaks/gitleaks-action@v2

  conformance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: make conformance-tests   # Berlin Group + ISO 20022

7. Branch + PR workflow

main       Production-ready, protected, requires PR review
develop    Integration branch, auto-deploys to sandbox
feature/*  Feature branches, branched from develop
fix/*      Bug fixes, branched from main or develop
release/*  Release prep

PR rules:
   ─ Require 2 approving reviews (1 senior)
   ─ Require all CI checks pass
   ─ Require linked issue
   ─ Require CHANGELOG entry
   ─ Squash merge by default

Commit style:
   ─ Conventional commits: feat:, fix:, chore:, docs:, refactor:, test:
   ─ Subject line ≤ 72 chars
   ─ Imperative present tense ("Add alias resolution endpoint")

8. Configuration management

12-factor app principles:
   ─ Config via env vars or YAML
   ─ Secrets via Vault / KMS at startup
   ─ Per-environment configs: local.yaml, sandbox.yaml, prod.yaml

Example (local.yaml):
server:
  port: 8443
  tls:
    cert_pem: $TLS_CERT_PATH
    key_pem:  $TLS_KEY_PATH
db:
  dsn: $DB_DSN
redis:
  addrs: ["redis-1:6379","redis-2:6379"]
hsm:
  pkcs11_path: /usr/lib/softhsm/libsofthsm2.so
  slot_id: 0
  pin: $HSM_PIN
eid:
  xroad_ss_url: https://ss.paygrid.mn
  xroad_client: MN/COM/1234567/PAYGRID-CLIENT

9. Observability

Metrics (Prometheus)

• HTTP req/sec, latency p50/95/99
• Per-PSP volume + error rate
• DB connection pool utilization
• Redis cache hit rate
• HSM operation latency
• X-Road call latency
• Webhook delivery success/retry counts
• Settlement batch metrics

Tracing (OpenTelemetry)

• End-to-end request trace
• X-Road call spans
• DB query spans
• HSM operation spans
• External webhook spans

Logging (zerolog → Loki / ELK)

• Structured JSON
• Per-request request_id
• Per-PSP context
• Audit trail (subset; full trail in DB)

Alerting

• p95 latency > SLO
• Error rate > 1%
• DB primary down
• HSM down
• Sanctions hit
• Webhook delivery failures > threshold
• Settlement reconciliation mismatch

10. Test vectors (Estonia verbatim)

20 канонический тест PLAN/13-TEST-VECTORS.md дотор. Бүгд pass болсны дараа л Phase 1 → Phase 2-руу шилжинэ.

11. Release process

Cadence: weekly minor releases (Phase 1-2), bi-weekly Phase 3+

Steps:
   1. Cut release branch from develop
   2. Update CHANGELOG.md
   3. Tag (v1.2.3)
   4. CI builds + signs container image
   5. Deploy to sandbox
   6. Smoke test (24-48 цаг)
   7. Approve for prod (2 senior eng + 1 PM)
   8. Canary deploy (10% traffic)
   9. Monitor (24-48 цаг)
   10. Full deploy
   11. Tag main commit
   12. Notify participants of any breaking changes (≥30 хоног notice)

12. Definition of Done per task

• Code (Go) following project style
• Tests (unit + integration covering new logic)
• DB migration if schema changed
• OpenAPI updated if endpoint changed
• CHANGELOG.md entry (Added / Changed / Fixed)
• Runbook entry if new ops procedure
• Code reviewer approved
• All CI checks green
• No regression in E2E tests
• Backward compat verified (no breaking change without notice)

13. Quick reference: where things live

Эх сурвалж: PLAN/14-DEV-WORKFLOW.md, PLAN/13-TEST-VECTORS.md. ← Танилцуулга-аар буцах