Palmr/.github/copilot-instructions.md

GitHub Copilot Instructions for Palmr

This file contains instructions for GitHub Copilot to help contributors work effectively with the Palmr codebase.

Project Overview

Palmr is a flexible and open-source alternative to file transfer services like WeTransfer and SendGB. It's built with:

• Backend: Fastify (Node.js) with TypeScript, SQLite database, and filesystem/S3 storage
• Frontend: Next.js 15 + React + TypeScript + Shadcn/ui
• Documentation: Next.js + Fumadocs + MDX
• Package Manager: pnpm (v10.6.0)
• Monorepo Structure: Three main apps (web, server, docs) in the apps/ directory

Architecture and Structure

Monorepo Layout

apps/
├── docs/       # Documentation site (Next.js + Fumadocs)
├── server/     # Backend API (Fastify + TypeScript)
└── web/        # Frontend application (Next.js 15)

Key Technologies

• TypeScript: Primary language for all applications
• Database: Prisma ORM with SQLite (optional S3-compatible storage)
• Authentication: Multiple OAuth providers (Google, GitHub, Discord, etc.)
• Internationalization: Multi-language support with translation scripts
• Validation: Husky pre-push hooks for linting and type checking

Development Workflow

Base Branch

Always create new branches from and submit PRs to the next branch, not main.

Commit Convention

Use Conventional Commits format for all commits:

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

Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation changes
- test: Adding or updating tests
- refactor: Code refactoring
- style: Code formatting
- chore: Maintenance tasks

Examples:

• feat(web): add user authentication system
• fix(api): resolve null pointer exception in user service
• docs: update installation instructions in README
• test(server): add unit tests for user validation

Code Quality Standards

1. Linting: All apps use ESLint. Run pnpm lint before committing
2. Formatting: Use Prettier for code formatting. Run pnpm format
3. Type Checking: Run pnpm type-check to validate TypeScript
4. Validation: Run pnpm validate to run both linting and type checking
5. Pre-push Hook: Automatically validates all apps before pushing

Testing Changes

• Test incrementally during development
• Run validation locally before pushing: pnpm validate in each app directory
• Keep changes focused on a single issue or feature
• Review your work before committing

Application-Specific Guidelines

Web App (apps/web/)

• Framework: Next.js 15 with App Router
• Port: 3000 (development)
• Scripts:
  • pnpm dev: Start development server
  • pnpm build: Build for production
  • pnpm validate: Run linting and type checking
• Translations: Use Python scripts in scripts/ directory
  • pnpm translations:check: Check translation status
  • pnpm translations:sync: Synchronize translations

Server App (apps/server/)

• Framework: Fastify with TypeScript
• Port: 3333 (default)
• Scripts:
  • pnpm dev: Start development server with watch mode
  • pnpm build: Build TypeScript to JavaScript
  • pnpm validate: Run linting and type checking
  • pnpm db:seed: Seed database
• Database: Prisma ORM with SQLite

Docs App (apps/docs/)

• Framework: Next.js with Fumadocs
• Port: 3001 (development)
• Content: MDX files in content/docs/
• Scripts:
  • pnpm dev: Start development server
  • pnpm build: Build documentation site
  • pnpm validate: Run linting and type checking

Code Style and Best Practices

General Guidelines

1. Follow Style Guidelines: Ensure code adheres to ESLint and Prettier configurations
2. TypeScript First: Always use TypeScript, avoid any types when possible
3. Component Organization: Keep components focused and single-purpose
4. Error Handling: Implement proper error handling and logging
5. Comments: Add comments only when necessary to explain complex logic
6. Imports: Use absolute imports where configured, keep imports organized

API Development (Server)

• Use Fastify's schema validation for all routes
• Follow REST principles for endpoint design
• Implement proper authentication and authorization
• Handle errors gracefully with appropriate status codes
• Document API endpoints in the docs app

Frontend Development (Web)

• Use React Server Components where appropriate
• Implement proper loading and error states
• Follow accessibility best practices (WCAG guidelines)
• Optimize performance (lazy loading, code splitting)
• Use Shadcn/ui components for consistent UI

Documentation

• Write clear, concise documentation
• Include code examples where helpful
• Update documentation when changing functionality
• Use MDX features for interactive documentation
• Follow the existing documentation structure

Translation and Internationalization

• All user-facing strings should be translatable
• Use the Next.js internationalization system
• Translation files are in apps/web/messages/
• Reference file: en-US.json
• Run pnpm translations:check to verify translations
• Mark untranslated strings with [TO_TRANSLATE] prefix

Common Patterns

Authentication Providers

• Provider configurations in apps/server/src/modules/auth-providers/providers.config.ts
• Support for OAuth2 and OIDC protocols
• Field mappings for user data normalization
• Special handling for providers like GitHub that require additional API calls

File Storage

• Default: Filesystem storage
• Optional: S3-compatible object storage
• File metadata stored in SQLite database

Environment Variables

• Configure via .env files (not committed to repository)
• Required variables documented in README or docs
• Use environment-specific configurations

Contributing Guidelines

Pull Request Process

1. Fork the repository
2. Create a branch from next: git checkout -b feature/your-feature upstream/next
3. Make focused changes addressing a single issue/feature
4. Write or update tests as needed
5. Update documentation to reflect changes
6. Ensure all validations pass: pnpm validate in each app
7. Commit using Conventional Commits
8. Push to your fork
9. Create Pull Request targeting the next branch

Code Review

• Be responsive to feedback
• Keep discussions constructive and professional
• Make requested changes promptly
• Ask questions if requirements are unclear

What to Avoid

• Don't mix unrelated changes in a single PR
• Don't skip linting or type checking
• Don't commit directly to main or next branches
• Don't add unnecessary dependencies
• Don't ignore existing code style and patterns
• Don't remove or modify tests without good reason

Helpful Commands

Root Level

pnpm install          # Install all dependencies
git config core.hooksPath .husky  # Configure Git hooks

Per App (web/server/docs)

pnpm dev              # Start development server
pnpm build            # Build for production
pnpm lint             # Run ESLint
pnpm lint:fix         # Fix ESLint issues automatically
pnpm format           # Format code with Prettier
pnpm format:check     # Check code formatting
pnpm type-check       # Run TypeScript type checking
pnpm validate         # Run lint + type-check

Docker

docker-compose up     # Start all services
docker-compose down   # Stop all services

Resources

• Documentation: https://palmr.kyantech.com.br
• Contributing Guide: CONTRIBUTING.md
• Issue Tracker: GitHub Issues
• License: Apache-2.0

Getting Help

• Review existing documentation in apps/docs/content/docs/
• Check contribution guide in CONTRIBUTING.md
• Review existing code for patterns and examples
• Ask questions in PR discussions or issues
• Read error messages and logs carefully

Important Notes

• Beta Status: This project is in beta; expect changes and improvements
• Focus on Quality: Prioritize code quality and maintainability over speed
• Test Locally: Always test your changes locally before submitting
• Documentation Matters: Keep documentation synchronized with code
• Community First: Be respectful, patient, and constructive with all contributors