Contributing

Join us in building a more secure future for academic credentials. We welcome contributions from developers, researchers, and anyone passionate about blockchain technology.

Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors. Harassment, discrimination, or any form of disrespectful behaviour will not be tolerated.

Development Setup

Prerequisites

Node.js 18+
PostgreSQL database
Ledger gateway (optional locally; the backend uses mock mode outside production)
Git

Local Development

# 1. Clone Repository

git clone https://github.com/oyedokunken/credence-app.git
cd credence-app

# 2. Backend Setup

cd backend npm install cp .env.example .env # Configure .env with database and blockchain credentials npx prisma db push npm run dev

# 3. Frontend Setup

cd frontend
npm install
npm run dev

# 4. Blockchain Setup (Optional for local dev)

cd blockchain
npm install && npm run keygen && npm test
# See LEDGER_DEPLOYMENT.md for the Render + Vercel setup
# Without a ledger the backend uses mock mode locally; production refuses to run

How to Contribute

Reporting Bugs

Before submitting a bug report, please search existing issues to avoid duplicates.

When reporting a bug, include:

A clear and descriptive title
The steps required to reproduce the issue
The expected behaviour and what actually happened
Screenshots or logs if applicable
Your environment details (OS, Node.js version, browser version)

Suggesting Enhancements

Feature requests are welcome. Please open an issue with:

A clear title and description of the proposed feature
The problem it solves or the value it adds
Any examples or mockups if available

Submitting Pull Requests

1
Fork the repository and create your branch from main
git checkout -b feature/your-feature-name
2
Make your changes following the code style guidelines below
3
Write or update tests for any new functionality
4
Ensure all tests pass before submitting
# Backend cd backend && npm run test # Frontend cd frontend && npm run test
5
Commit your changes using a clear and descriptive commit message
git commit -m "feat: add certificate revocation audit trail"
6
Push your branch and open a Pull Request against main

Commit Message Convention

This project follows the Conventional Commits specification.

Prefix	Usage
feat:	A new feature
fix:	A bug fix
docs:	Documentation changes only
style:	Code style changes (formatting, missing semicolons, etc.)
refactor:	Code changes that neither fix a bug nor add a feature
test:	Adding or correcting tests
chore:	Changes to the build process or auxiliary tools
perf:	Performance improvements

Code Style Guidelines

TypeScript (Frontend and Backend)

Use TypeScript strictly. Avoid any types wherever possible
Use interface for object shapes and type for unions and intersections
All exported functions must have explicit return type annotations
Follow the existing file and folder naming conventions

Naming Conventions

Element	Convention	Example
Variables and functions	camelCase	getCertificateById
React components	PascalCase	CertificateCard
Files (components)	PascalCase	CertificateCard.tsx
Files (utilities)	kebab-case	certificate-utils.ts
Constants	UPPER_SNAKE_CASE	MAX_VERIFICATION_TIME
Environment variables	UPPER_SNAKE_CASE	DATABASE_URL

Frontend Conventions

All pages live inside the app/ directory using Next.js App Router conventions
Route groups are used to organise pages without affecting the URL structure
All form validation is handled with zod schemas
No inline styles. Use Tailwind CSS utility classes exclusively
No emojis in the UI. Use Lucide React icons throughout

Backend Conventions

All routes are prefixed with /api/v1/
Controllers handle request/response logic only
Business logic lives in service files
All database access goes through Prisma
Use middleware for authentication and role-based access control

Blockchain (TypeScript ledger and JavaScript chaincode)

Follow the existing TypeScript style and keep ledger changes covered by tests (npm test in blockchain/)
Every ledger and chaincode function must validate all inputs before processing
Never store personal data (names, matric numbers, CGPAs) on the ledger; it is append-only

Project Structure

credence/
  frontend/
    app/
      (landing)/        # Public landing page
      (auth)/           # Authentication pages
      (dashboard)/      # Role-based dashboard pages
    components/         # Shared UI components
    lib/                # Utility functions and API clients
    hooks/              # Custom React hooks
    types/              # TypeScript type definitions
  backend/
    src/
      controllers/      # Route handler functions
      routes/           # Express route definitions
      middleware/       # Auth, role guard, error handler
      services/         # Business logic
      utils/            # Helper functions
      prisma/           # Prisma schema and migrations
  blockchain/
    src/                # Credence Ledger gateway (ledger core, Postgres store, routes, explorer)
    chaincode/          # Hyperledger Fabric chaincode (JavaScript, design target)
    scripts/            # Key generation (npm run keygen)
    test/               # Ledger tests

Testing

Backend Testing

The backend uses Jest for unit and integration tests. Tests are located in the backend/src/__tests__ directory.

cd backend
npm test
npm run test:watch # Watch mode for development
npm run test:coverage # Generate coverage report

Frontend Testing

The frontend uses React Testing Library for component tests. Tests are located in the frontend/__tests__ directory.

cd frontend
npm test
npm run test:watch # Watch mode for development
npm run test:coverage # Generate coverage report

Blockchain Testing

The ledger is tested with Node's built-in test runner. Tests are located in blockchain/test; set LEDGER_TEST_DATABASE_URL to also run the Postgres tests.

cd blockchain
npm test

Environment Variables

Backend (.env)

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/credence"

# JWT
JWT_SECRET="your-jwt-secret-key"
JWT_EXPIRES_IN="1d"
JWT_REFRESH_SECRET="your-refresh-secret-key"
JWT_REFRESH_EXPIRES_IN="7d"

# Ledger gateway
BLOCKCHAIN_MODE="gateway"
BLOCKCHAIN_GATEWAY_URL="https://your-ledger-gateway.onrender.com"
BLOCKCHAIN_GATEWAY_API_KEY="your-gateway-api-key"

# Email
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USER="your-email@gmail.com"
SMTP_PASS="your-app-password"
EMAIL_FROM="Credence <noreply@credencely.com>"

# Frontend URL
FRONTEND_URL="http://localhost:3000"

Frontend (.env.local)

NEXT_PUBLIC_API_URL="http://localhost:5000/api/v1"

Getting Help

Documentation

README.md - Project overview and quick start guide
API Documentation - Detailed API reference
Ledger Deployment Guide - Credence Ledger setup, backfill and rehearsal (LEDGER_DEPLOYMENT.md)

Community

GitHub Issues - Bug reports and feature requests
GitHub Discussions - General questions and discussions

Contact

For security vulnerabilities or private matters, please contact: security@credencely.com

License

By contributing to Credence, you agree that your contributions will be licensed under the same license as the project.

Questions?

If you have questions about contributing that are not covered here, please open an issue with the label question.

Ready to Contribute?

Fork the repository, make your changes, and submit a pull request. We review all contributions and appreciate your help!