Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
93 lines (65 loc) · 3.6 KB

CONTRIBUTING.md

File metadata and controls

93 lines (65 loc) · 3.6 KB
Raw

Contributing — Local setup and IssuerProfile update

This repo contains backend (NestJS), frontend (Vite + React), and Soroban contracts.

Goal: ensure IssuerProfile uses real API data by default and allow optionally using dummy data.

Quick start (development)

  1. Start required services (Postgres + Redis) using Docker Compose:
# from repo root
docker-compose up -d postgres redis
  1. Build and run the backend (recommended in a separate terminal). Provide required env vars — at minimum the backend requires JWT_SECRET and DB connection info. Example .env values:
# Example env (create .env or export in shell)
export NODE_ENV=development
export PORT=3000
export DB_HOST=localhost
export DB_PORT=5432
export DB_USERNAME=kaystcx_user
export DB_PASSWORD=kaystcx_password
export DB_NAME=kaystcx
export JWT_SECRET=dev-secret
export JWT_EXPIRES_IN=24h
export ALLOWED_ORIGINS=http://localhost:5173

Then start the backend:

cd backend
npm install
npm run start:dev
  1. Start frontend (defaults to real API). In a new terminal:
cd frontend
# Use real API (default)
VITE_USE_DUMMY_DATA=false npm run dev

# To run with dummy data for offline dev
VITE_USE_DUMMY_DATA=true npm run dev

Notes and verification

  • The frontend reads VITE_USE_DUMMY_DATA to decide whether to use hardcoded mock data or call real API endpoints. This was changed to default to false (real API) — see frontend/src/api/endpoints.ts.
  • Frontend expects backend API at VITE_API_URL (defaults to http://localhost:3000/api/v1). Set VITE_API_URL in your environment or .env if your backend runs on a different host/port.
  • Ensure you have an issuer account and valid JWT; the frontend uses tokenStorage to attach the Authorization header.

Testing and CI

  • The repository contains backend e2e tests (backend/test) and a CI workflow .github/workflows/ci.yml.
  • Consider adding frontend tests for IssuerProfile to cover API integration and rendering.

Backend code conventions — DTOs and entities

To keep the backend consistent and easy to navigate, follow these conventions when adding or refactoring modules:

DTOs (backend/src/modules/*/dto/)

  • Request DTOs are named {action}-{entity}.dto.ts — e.g. create-user.dto.ts, search-certificates.dto.ts, verify-email.dto.ts.
  • Response DTOs are named {entity}-response.dto.ts — e.g. user-response.dto.ts, audit-statistics-response.dto.ts.
  • Keep one DTO class per file, and export it through the module's dto/index.ts barrel.
  • DTOs are for data transfer only (request validation / response serialization). Do not mix unrelated request and response shapes in the same file.

Entities (backend/src/modules/*/entities/)

  • Entities are pure data models. Keep @Column/@Entity metadata and relationships, but do not add business-logic methods (e.g. isLocked(), isPasswordResetTokenValid(), addVerificationRecord()).
  • Business rules that operate on an entity belong in a service (or a small pure helper module under utils/), where they can be unit-tested independently.

Branch and PR

  • I created branch feat/issuerprofile-real-stats which includes the change to respect VITE_USE_DUMMY_DATA.
  • To push and open a PR:
git push -u origin feat/issuerprofile-real-stats
# then open a PR on GitHub

If you'd like, I can:

  • Start backend+frontend locally here to verify the IssuerProfile page (requires setting JWT_SECRET and creating a test issuer user), or
  • Add a small integration test to the frontend that mocks issuerProfileApi and ensures IssuerProfile renders fetched data.

Tell me which you'd prefer and I'll proceed.