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
Hyperledger Fabric network
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

cd blockchain
docker-compose up -d

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 (Go Chaincode)

Follow standard Go formatting conventions (gofmt)
Each chaincode function must validate all inputs before processing
Emit events for all state changes on the ledger

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/
    chaincode/          # Hyperledger Fabric smart contracts (Go)
    network/            # Docker Compose and Fabric configuration
    scripts/            # Network setup and deployment scripts

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

Blockchain smart contracts can be tested using the Fabric test network. Test scripts are located in blockchain/scripts/test.

cd blockchain
./scripts/test/test-chaincode.sh

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"

# Blockchain
FABRIC_CHANNEL="mychannel"
FABRIC_CHAINCODE="certificates"
FABRIC_PEER="peer0.org1.example.com:7051"
FABRIC_TLS_CERT="/path/to/tls/cert"

# Email
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USER="your-email@gmail.com"
SMTP_PASSWORD="your-app-password"
SMTP_FROM="noreply@credencely.com"

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

Frontend (.env.local)

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

Getting Help

Documentation

README.md - Project overview and quick start guide
API Documentation - Detailed API reference
Blockchain Guide - Hyperledger Fabric integration guide

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!