Skip to main content

​
Goals

This guide explains how to contribute to the Winstory.io codebase without breaking critical Web3 and economic flows. It is intended for:
  • Internal engineers
  • External contributors (agencies, partners)

​
Branching & Workflow

  • Use feature branches: feature/<area>-<short-description>
  • Never push directly to main without a PR
  • Use small, focused PRs:
    • 1 feature or fix
    • 1–5 files touched when possible

​
Code Quality

  • Language: TypeScript everywhere (frontend + backend)
  • Follow existing patterns:
    • API routes in app/api/*
    • Shared logic in lib/*
    • UI in components/*
  • Prefer pure functions in lib/ over logic inside components

​
Safety Rules (Web3 & Payments)

Before merging any change touching these areas:
  • Blockchain / contracts
    • Never change contract addresses without updating deployments/ and contract-registry
    • Run the Base Sepolia E2E tests
  • Payments (Stripe/Crypto)
    • Keep verification logic in lib/payment-verification.ts and lib/crypto-payment-verification.ts
    • Never bypass amount checks in production
  • Rewards
    • Use existing helpers for reward types and tiers
    • If in doubt, update docs in ACCESS_REWARDS_IMPLEMENTATION_SUMMARY.md

​
Testing

For any non-trivial change:
  • Run npm run build locally
  • Run targeted tests:
    • npm test -- __tests__/b2c-agency-e2e-flow.test.ts
    • tsx scripts/test-b2c-agency-e2e.ts (when touching B2C/Agency)

​
Documentation

  • Any new public endpoint → update advanced/api-reference.mdx
  • Any architectural change → update advanced/architecture.mdx