Traqify
Get started

Contributing to Traqify

This guide covers everything you need to set up a development environment, follow project conventions, and submit quality pull requests.

Getting Started

Prerequisites

ToolMin versionNotes
Node.js18.xRequired by Next.js 14 and Vercel runtime
npm9.xWorkspaces not used; run installs per folder
PostgreSQL14+A free Supabase project works out of the box
Supabase accountFree tierNeeded for Storage (images, avatars, downloadables)
1

Fork and clone

git clone https://github.com/<your-username>/traqify.git
cd traqify
2

Install dependencies

cd backend && npm install
cd ../frontend && npm install
3

Configure environment

# Backend
cp backend/.env.example backend/.env
# Fill in: DATABASE_URL, DIRECT_URL, JWT_SECRET,
# SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY,
# SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM,
# GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET,
# PAYSTACK_SECRET_KEY, FRONTEND_URL
# CRON_SECRET (any long random string for local testing)

# Frontend
cp frontend/.env.local.example frontend/.env.local
# Fill in: API_ORIGIN, PROXY_SHARED_SECRET
4

Push schema to database

cd backend
npx prisma db push
npx prisma generate
5

Start dev servers

# Terminal 1 — backend (port 5000)
cd backend && npm run dev

# Terminal 2 — frontend (port 3000)
cd frontend && npm run dev
6

Verify TypeScript compiles

# Run before every commit
cd backend && npx tsc --noEmit
cd ../frontend && npx tsc --noEmit

Code Conventions

TypeScript strict mode

No any types unless absolutely unavoidable. All new controllers, routes, and components must be fully typed.

Functional components only

React class components are not used anywhere in the codebase.

Named exports

Prefer named exports over default exports for components and utility functions.

Tailwind CSS only

All styling via Tailwind utility classes. No inline styles, no CSS modules.

Zod for validation

All request bodies must be validated with a Zod schema before any business logic runs. Schema lives in utils/validators.ts.

RBAC on every route

New backend routes must declare an explicit auth guard: isOwnerOnly, isOwnerOrManager, isAtLeastAuditor, or isAtLeastCashier. No unguarded authenticated routes.

Security Conventions

  • Never store plain-text secrets, tokens, or OTPs. Hash with crypto.createHash('sha256') before any database write.
  • Never add a new public endpoint that returns user data without authenticate + requireOrg middleware.
  • Always include organizationId in every Prisma where clause that touches org-scoped data.
  • Do not place tokens or sensitive values in URL query strings or redirect parameters.
  • New file upload endpoints must define an explicit MIME allowlist in the Multer fileFilter.
  • Any server-side HTTP fetch to a user-supplied URL must validate the hostname before executing.
  • Required environment variables must be added to the startup validation list in backend/src/index.ts.
  • Never commit .env files, secrets, or credentials to the repository.

Commit Messages

Follow the Conventional Commits spec:

<type>(<scope>): <short description>
feat

New feature

fix

Bug fix

security

Security fix or hardening

docs

Documentation only

style

Formatting, no logic change

refactor

Code restructure, no feature/fix

chore

Dependency updates, build config

perf

Performance improvement

Pull Request Process

  • Title: use the same Conventional Commits format as your commit messages
  • Description: include what changed, why, and how to test it
  • TypeScript must compile: cd backend && npx tsc --noEmit and cd frontend && npx tsc --noEmit must both pass
  • No breaking schema changes without running npx prisma migrate dev and committing the migration file
  • Security-related PRs: document what was fixed and how it was tested in the PR description
  • One concern per PR: split large features into reviewable chunks
  • Do not bypass existing RBAC middleware or remove Zod validation from existing routes

Reporting Bugs

Open a GitHub issue with the following information:

  • Environment: OS, Node version, browser, and whether it occurs on production or local
  • Steps to reproduce the issue exactly
  • Expected behaviour vs actual behaviour
  • Relevant console output or screenshots

For security vulnerabilities, do not open a public GitHub issue. Follow the responsible disclosure process on the Security Policy page instead.