TPT Marketplace NZ

A verified peer-to-peer marketplace for New Zealand. All users authenticate via RealMe — the NZ Government identity service. High-value categories (vehicles, property, services) require RealMe Verified identity. No payment processing is involved; the platform facilitates discovery and communication only.

Features

• RealMe Authentication — all users must log in via RealMe SAML 2.0. Session cookies are HMAC-signed with a configurable SESSION_SECRET.
• Tiered Verification — vehicles, property, and services require RealMe Verified identity (Assurance Level 3+); other categories require login only.
• Browse & Search — full-text trigram search (PostgreSQL pg_trgm) with filters for category, region, and price range.
• Private Messaging — authenticated buyers can contact sellers via an in-app inbox.
• Reviews & Ratings — verified buyers can leave a star rating and comment on any listing they did not create. One review per user per listing enforced at the database level.
• Seller Dashboard — sellers can view, edit, change the status of, and delete their own listings.
• Pagination — 20 listings per page.

Tech Stack

| Layer | Technology | |---|---| | Backend | Go 1.23, chi router, pgx v5 | | Frontend | Next.js 14, TypeScript, App Router | | Auth | RealMe SAML 2.0 via packages/realme-go | | Database | PostgreSQL 16, pg_trgm for full-text search | | Infrastructure | Docker Compose (PostgreSQL, Redis, NATS) |

Quick Start

Prerequisites

• Go 1.23+
• Node.js 18+
• Docker & Docker Compose
• RealMe certificates, or the included mock IdP for local development

1 — Start infrastructure

docker compose up -d db

2 — Generate a local SP certificate

mkdir -p certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout certs/sp.key -out certs/sp.crt \
  -subj "/CN=localhost" -addext "subjectAltName=DNS:localhost"

3 — Configure environment

cp .env.example .env
# Edit .env — at minimum set DATABASE_URL and SESSION_SECRET

See .env.example for all variables and their descriptions.

4 — Run the database migration

psql $DATABASE_URL -f migrations/001_init.sql

5 — Start the mock RealMe IdP (development only)

go run ./packages/realme-go/testenv/ -addr :8081

6 — Start the API server

go run ./cmd/server

The API server starts on http://localhost:8080.

7 — Start the frontend

cd web
npm install
npm run dev

The frontend starts on http://localhost:3000.

API Reference

Auth

| Method | Path | Description | |---|---|---| | GET | /health | Health check | | GET | /auth/login | Initiate RealMe login | | GET | /auth/callback | RealMe SAML callback | | GET | /auth/logout | Logout | | GET | /auth/metadata | SAML SP metadata XML | | GET | /auth/status | Current user identity (unauthenticated returns {}) |

Listings

| Method | Path | Auth | Description | |---|---|---|---| | GET | /listings | No | Browse / search listings | | GET | /listings/categories | No | Available categories | | GET | /listings/{id} | No | Listing detail | | POST | /listings | Required | Create listing | | PUT | /listings/{id} | Owner | Full listing update | | PUT | /listings/{id}/status | Owner | Update listing status | | DELETE | /listings/{id} | Owner | Delete listing | | POST | /listings/{id}/reviews | Required | Submit a review | | GET | /my-listings | Required | Authenticated user's listings |

Messages

| Method | Path | Auth | Description | |---|---|---|---| | GET | /messages | Required | Inbox | | POST | /messages | Required | Send message | | GET | /messages/conversation/{listingId}/{otherUserId} | Required | Conversation thread |

Verification Gates

| Action | Requirement | |---|---| | Browse listings | None — public | | Send messages | RealMe login | | Submit a review | RealMe login, not the seller, one review per listing | | Create a listing | RealMe login | | Create in high-value category | RealMe Verified (Assurance Level 3+) | | Edit / delete own listing | RealMe login + ownership |

High-Value Categories

| Category | Requires Verification | |---|---| | Vehicles | Yes | | Property | Yes | | Services | Yes | | Electronics | No | | Agriculture | No | | Jobs | No | | Other | No |

RealMe Setup

Local Development (mock IdP)

The repository includes a mock RealMe IdP in packages/realme-go/testenv/. Start it on :8081 and set:

REALME_ENVIRONMENT=mts
REALME_IDP_METADATA_URL=http://localhost:8081/metadata

ITE (Integration Test Environment)

1. Log in to the RealMe Developer Portal and register a new service.
2. Submit your SP metadata (GET /auth/metadata) to DIA.
3. DIA provides the ITE IdP metadata URL.
4. Set:

   REALME_ENVIRONMENT=ite
   REALME_CERT_FILE=certs/ite.sp.crt
   REALME_KEY_FILE=certs/ite.sp.key
   REALME_IDP_METADATA_URL=<DIA-provided-ITE-url>
   

Production

Same as ITE with REALME_ENVIRONMENT=production and the DIA production metadata URL.

Project Structure

tpt-marketplace-nz/
├── cmd/server/          # Main entrypoint
├── internal/
│   ├── handlers/        # HTTP handlers
│   ├── services/        # Business logic
│   ├── repository/      # Database access
│   └── models/          # Shared types
├── migrations/          # SQL migration files
├── packages/
│   └── realme-go/       # RealMe SAML 2.0 SP library
├── web/                 # Next.js 14 frontend
│   ├── app/             # App Router pages
│   ├── components/      # Shared components
│   └── lib/             # api.ts, categories.ts
├── docker-compose.yml
├── Dockerfile
└── .env.example

Contributing

See CONTRIBUTING.md.

License

MIT