Skip to main content

​
Welcome Contributors

Thank you for your interest in contributing to Sistema Financiero! This guide will help you get started with contributing to the project, whether you’re fixing bugs, adding features, or improving documentation.

​
Getting Started

1

Fork the Repository

Start by forking the repository to your GitHub account:
git clone https://github.com/YOUR_USERNAME/sistema-financiero-app.git
cd sistema-financiero-app
2

Install Dependencies

Install all required packages:
npm install
3

Set Up Environment

Copy the example environment file and configure your local environment:
cp .env.example .env.local
Add your Supabase credentials and API keys as needed.
4

Create a Feature Branch

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

​
Development Workflow

​
Running the Development Server

Start the Next.js development server: 
npm run dev
The application will be available at http://localhost:3000.

​
Building for Production

Test your changes with a production build: 
npm run build
npm run start
Always test your changes with a production build before submitting a pull request to catch any build-time errors.

​
Commit Conventions

We follow Conventional Commits for clear and structured commit messages:

​
Commit Types

TypeDescriptionExample
featNew featurefeat: add expense category filter
fixBug fixfix: resolve date picker timezone issue
docsDocumentation onlydocs: update API reference
styleFormatting, missing semicolonsstyle: format components with prettier
refactorCode refactoringrefactor: simplify chart data processing
testAdding teststest: add unit tests for KPI calculations
choreMaintenance taskschore: update dependencies
perfPerformance improvementsperf: optimize transaction queries

​
Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>
Examples: 
# Simple commit
git commit -m "feat: add dark mode toggle"

# Commit with scope
git commit -m "fix(dashboard): correct KPI calculation for monthly view"

# Commit with body
git commit -m "refactor(api): improve transaction endpoint performance

Optimized database queries and added caching layer.
Reduced average response time from 500ms to 150ms."

​
Pull Request Process

1

Ensure Quality

Before submitting, make sure:
  • All tests pass (if applicable)
  • Code builds successfully
  • No console errors or warnings
  • Code follows existing style patterns
2

Push Your Changes

git add .
git commit -m "feat: your feature description"
git push origin feature/your-feature-name
3

Create Pull Request

Go to GitHub and create a pull request with:
  • Clear title: Summarize the change in one line
  • Description: Explain what changed and why
  • Screenshots: Include visual changes (if applicable)
  • Testing: Describe how you tested the changes
4

Code Review

  • Address any feedback from reviewers
  • Make requested changes in new commits
  • Push updates to the same branch

​
Pull Request Template

## Description
Brief description of what this PR does.

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

## Changes Made
- List of specific changes
- Another change

## Testing
Describe how you tested these changes.

## Screenshots (if applicable)
Add screenshots for UI changes.

## Related Issues
Closes #123

​
Code Style Guidelines

​
TypeScript

  • Use TypeScript for all new files
  • Define proper interfaces and types
  • Avoid using any type when possible
// Good
interface Transaction {
  id: string;
  fecha: string;
  tipo: 'ingreso' | 'gasto';
  monto: number;
  categoria: string;
}

// Avoid
const data: any = {...};

​
React Components

  • Use functional components with hooks
  • Keep components focused and single-purpose
  • Extract reusable logic into custom hooks
// Good
export default function TransactionCard({ transaction }: { transaction: Transaction }) {
  return (
    <div className="p-4 border rounded-lg">
      {/* component content */}
    </div>
  );
}

​
File Naming

  • Components: PascalCase.tsx (e.g., KPICard.tsx)
  • Hooks: camelCase.ts with use prefix (e.g., useEnhancedChat.ts)
  • Utilities: camelCase.ts (e.g., supabase.ts)
  • API Routes: route.ts (Next.js convention)

​
Testing Your Changes

​
Manual Testing Checklist

  • Test in development mode (npm run dev)
  • Test production build (npm run build && npm run start)
  • Test on different screen sizes (mobile, tablet, desktop)
  • Test with dark mode enabled
  • Verify no console errors or warnings
  • Test edge cases and error scenarios

​
Feature-Specific Testing

For Dashboard Changes:
  • Verify KPIs calculate correctly
  • Check charts render properly
  • Test date range filters
For AI Agent Changes:
  • Test natural language parsing
  • Verify transactions are saved correctly
  • Check error handling for failed requests
For API Changes:
  • Test all endpoints with different parameters
  • Verify error responses
  • Check database queries are optimized

​
Common Contribution Areas

Good First Issues

Perfect for newcomers:
  • Fix typos in documentation
  • Add new expense/income categories
  • Improve error messages
  • Add input validation
  • Enhance mobile responsiveness

Feature Additions

More involved contributions:
  • Add new chart types
  • Implement transaction filters
  • Add export functionality (CSV, PDF)
  • Create recurring transactions
  • Add budget tracking

Performance Improvements

Optimization opportunities:
  • Optimize database queries
  • Implement caching strategies
  • Reduce bundle size
  • Improve loading states
  • Add pagination for large datasets

​
Need Help?

If you’re stuck or have questions:
  • GitHub Issues: Ask questions or report bugs
  • GitHub Discussions: General questions and ideas
  • Documentation: Check the Code Structure guide
Don’t be afraid to ask for help! We’re here to support contributors at all skill levels.

​
Code of Conduct

  • Be respectful and inclusive
  • Provide constructive feedback
  • Focus on the code, not the person
  • Welcome newcomers and help them learn
  • Follow the project’s technical standards

​
License

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

Build docs developers (and LLMs) love

Get started for freeTalk to us