Contributing Guide

Welcome Contributors

Thank you for your interest in contributing to ARCA! This guide will help you set up your development environment and understand our contribution workflow.

ARCA is an open-source project developed as a university thesis (TCC). Contributions are welcome to improve functionality, fix bugs, and enhance documentation.

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Node.js

Version 18 or higher

PostgreSQL

Version 12 or higher

npm

Version 10 or higher

Git

For version control

Initial Setup

Fork the Repository

Fork the ARCA repository to your GitHub account:

# Visit https://github.com/pedrokourly/arca and click "Fork"

Clone Your Fork

Clone your forked repository locally:

git clone https://github.com/YOUR_USERNAME/arca.git
cd arca

Install Dependencies

Install all project dependencies:

npm install

This will install dependencies for both backend and frontend workspaces.

Configure Environment

Set up your environment variables:

# Backend environment
cp apps/backend/.env.example apps/backend/.env

Edit apps/backend/.env with your PostgreSQL connection:

DATABASE_URL="postgresql://username:password@localhost:5432/arca_db"
JWT_SECRET="your-development-secret-key"
CORS_ORIGIN="http://localhost:3000"
PORT=3333

Initialize Database

Run Prisma migrations to set up the database schema:

cd apps/backend
npx prisma migrate dev
npx prisma generate

Optionally, seed the database with sample data:

npm run db:seed

Start Development Servers

Return to the root directory and start both applications:

cd ../..
npm run dev

This starts:

Backend at http://localhost:3333
Frontend at http://localhost:3000

Development Workflow

Branch Strategy

We follow a feature branch workflow:

# Create a new branch for your feature
git checkout -b feature/your-feature-name

Always create branches from the latest main branch. Pull the latest changes before starting:

git checkout main
git pull origin main
git checkout -b feature/your-feature

Commit Guidelines

Write clear, descriptive commit messages following this format:

<type>: <subject>

<optional body>

<optional footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, no logic change)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples:

feat: add patient search functionality

Implemented search bar in patient list with filters
for name, CPF, and registration date.

Resolves #123

Coding Standards

TypeScript

All code must be written in TypeScript with proper type definitions.

Backend (NestJS)
Frontend (Next.js)

// Use DTOs for request/response types
export class CreateUserDto {
  @IsString()
  @IsNotEmpty()
  nome: string;

  @IsEmail()
  email: string;

  @IsString()
  @MinLength(8)
  senha: string;

  @IsInt()
  roleId: number;
}

// Use proper service typing
@Injectable()
export class UsersService {
  constructor(private prisma: PrismaService) {}

  async create(createUserDto: CreateUserDto): Promise<Usuario> {
    return this.prisma.usuario.create({
      data: createUserDto,
    });
  }
}

// Define component prop types
interface PatientCardProps {
  patient: {
    id: string;
    nomeRegistro: string;
    nomeSocial?: string;
  };
  onEdit: (id: string) => void;
}

export function PatientCard({ patient, onEdit }: PatientCardProps) {
  return (
    <div className="card">
      <h3>{patient.nomeSocial || patient.nomeRegistro}</h3>
      <button onClick={() => onEdit(patient.id)}>Edit</button>
    </div>
  );
}

Code Formatting

We use Prettier and ESLint for consistent code formatting:

# Format all files
npm run format

# Lint and auto-fix
npm run lint

# Type check
npm run check-types

Run these commands before committing to ensure code quality.

Naming Conventions

Type	Convention	Example
Files	kebab-case	`patient-list.tsx`, `users.service.ts`
Components	PascalCase	`PatientCard`, `UserProfile`
Functions	camelCase	`getUserById`, `formatDate`
Variables	camelCase	`patientData`, `isActive`
Constants	UPPER_SNAKE_CASE	`API_URL`, `MAX_RETRY`
Types/Interfaces	PascalCase	`Patient`, `CreateUserDto`
Database Tables	UPPER_SNAKE_CASE	`USUARIOS`, `PACIENTE`

Testing

Backend Tests

# Run all tests
cd apps/backend
npm run test

# Watch mode
npm run test:watch

# Coverage report
npm run test:cov

Writing Tests

Example unit test for a service:

describe('UsersService', () => {
  let service: UsersService;
  let prisma: PrismaService;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [UsersService, PrismaService],
    }).compile();

    service = module.get<UsersService>(UsersService);
    prisma = module.get<PrismaService>(PrismaService);
  });

  it('should create a user', async () => {
    const dto = {
      nome: 'Test User',
      email: '[email protected]',
      senha: 'password123',
      roleId: 1,
    };

    const result = await service.create(dto);
    expect(result).toHaveProperty('id_User');
    expect(result.email).toBe(dto.email);
  });
});

Pull Request Process

Before Submitting

Creating a Pull Request

Push Your Branch

git push origin feature/your-feature-name

Open Pull Request

Go to the original ARCA repository on GitHub
Click “Pull Requests” → “New Pull Request”
Select your fork and branch
Click “Create Pull Request”

Fill PR Template

Use this template for your PR description:

## Description
Brief description of what this PR does.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Changes Made
- Added X functionality
- Fixed Y issue
- Updated Z documentation

## Testing
- [ ] Unit tests added/updated
- [ ] E2E tests added/updated
- [ ] Manual testing performed

## Screenshots (if applicable)
[Add screenshots here]

## Related Issues
Closes #123

Wait for Review

A maintainer will review your PR and may request changes.Be responsive to feedback and make requested updates.

Database Changes

When making database schema changes:

Update Prisma Schema

Edit apps/backend/prisma/schema.prisma:

model Paciente {
  // ... existing fields ...
  
  // Add new field
  newField String? @db.VarChar(100)
}

Create Migration

cd apps/backend
npx prisma migrate dev --name add_new_field_to_paciente

Update Types

npx prisma generate

Update DTOs and Services

Update any affected DTOs, services, and controllers to handle the new field.

Never manually edit migration files. Always use prisma migrate to create migrations.

Working with Monorepo

Running Specific Workspace Commands

# Run backend-specific command
npm run -w backend start:dev

# Or from backend directory
cd apps/backend
npm run start:dev

Adding Dependencies

# Add to backend workspace
npm install <package> -w backend

Documentation Guidelines

Code Comments

Write clear comments for complex logic:

/**
 * Calculates the patient's age based on birth date.
 * 
 * @param dataNascimento - Patient's date of birth
 * @returns Age in years
 */
function calculateAge(dataNascimento: Date): number {
  const today = new Date();
  let age = today.getFullYear() - dataNascimento.getFullYear();
  const monthDiff = today.getMonth() - dataNascimento.getMonth();
  
  // Adjust if birthday hasn't occurred this year
  if (monthDiff < 0 || (monthDiff === 0 && today.getDate() < dataNascimento.getDate())) {
    age--;
  }
  
  return age;
}

API Documentation

Document API endpoints with clear descriptions:

/**
 * GET /api/patients/:id
 * 
 * Retrieves a patient by ID.
 * 
 * @param id - Patient UUID
 * @returns Patient object with full details
 * @throws NotFoundException if patient not found
 */
@Get(':id')
async findOne(@Param('id') id: string): Promise<Paciente> {
  return this.patientsService.findOne(id);
}

Getting Help

GitHub Issues

Report bugs or request features via GitHub Issues

Discussions

Ask questions in GitHub Discussions

Email

Contact the maintainer for private inquiries

Documentation

Check the docs for architecture and API references

Code of Conduct

Our Standards

Be respectful of differing viewpoints and experiences
Accept constructive criticism gracefully
Focus on what’s best for the community
Show empathy towards other contributors

Unacceptable Behavior

Harassment, trolling, or insulting comments
Public or private harassment
Publishing others’ private information
Other unethical or unprofessional conduct

License

By contributing to ARCA, you agree that your contributions will be licensed under the MIT License.

Thank You!

Your contributions help make ARCA better for psychology clinics everywhere. Every bug fix, feature, and documentation improvement makes a difference.

Happy coding! 🚀

Get Started

Core Features

User Management

Deployment

Development

​Welcome Contributors

​Getting Started

​Prerequisites

Node.js

PostgreSQL

npm

Git

​Initial Setup

​Development Workflow

​Branch Strategy

​Commit Guidelines

​Coding Standards

​TypeScript

​Code Formatting

​Naming Conventions

​Testing

​Backend Tests

​Writing Tests

​Pull Request Process

​Before Submitting

​Creating a Pull Request

​Database Changes

​Working with Monorepo

​Running Specific Workspace Commands

​Adding Dependencies

​Documentation Guidelines

​Code Comments

​API Documentation

​Getting Help

GitHub Issues

Discussions

Email

Documentation

​Code of Conduct

​Our Standards

​Unacceptable Behavior

​License

​Thank You!

Build docs developers (and LLMs) love

Welcome Contributors

Getting Started

Prerequisites

Initial Setup

Development Workflow

Branch Strategy

Commit Guidelines

Coding Standards

TypeScript

Code Formatting

Naming Conventions

Testing

Backend Tests

Writing Tests

Pull Request Process

Before Submitting

Creating a Pull Request

Database Changes

Working with Monorepo

Running Specific Workspace Commands

Adding Dependencies

Documentation Guidelines

Code Comments

API Documentation

Getting Help

Code of Conduct

Our Standards

Unacceptable Behavior

License

Thank You!