Developer Contribution Guide

This guide explains how to contribute to the Aitana frontend project, from initial setup to getting your changes deployed.

Quick Start

1. Repository Setup

# Clone the repository
git clone https://github.com/Aitana-Labs/frontend.git
cd frontend

# Install dependencies
npm install

# Set up backend
cd backend
uv venv --python 3.10
source .venv/bin/activate
uv sync
cd ..

2. Environment Configuration

Create .env.local with Firebase configuration:

cp env.local.example .env.local
# Edit .env.local with your Firebase project details

3. Start Development

# Development with Firebase emulators (recommended)
npm run dev

# Or development with cloud Firebase
npm run dev:cloud

Development Workflow

For Small Changes (Direct to dev)

# 1. Switch to dev and pull latest
git checkout dev
git pull origin dev

# 2. Make your changes
# ... edit files ...

# 3. Run quality checks
npm run quality:check:fast  # Quick check
npm run quality:check       # Full check (recommended)

# 4. Commit and push
git add .
git commit -m "fix: resolve issue with user authentication"
git push origin dev

For Features/Major Changes (Feature Branch)

# 1. Create feature branch from dev
git checkout dev
git pull origin dev
git checkout -b feature/user-profile-page

# 2. Develop your feature
# ... make changes ...

# 3. Test locally
npm run quality:check       # Lint, typecheck, test, build
npm run docker:check        # Docker build simulation

# 4. Push and create PR
git push origin feature/user-profile-page
# Go to GitHub and create PR: feature/user-profile-page → dev

Code Quality Requirements

Before Every Commit

# Essential checks (all must pass)
npm run lint                # ESLint
npm run typecheck          # TypeScript
npm test                   # Frontend tests
cd backend && python -m pytest tests/  # Backend tests
npm run build              # Production build

Shortcuts

# Quick check (lint + typecheck only)
npm run quality:check:fast

# Full check (lint + typecheck + test + build)
npm run quality:check

# Docker consistency check
npm run docker:check

Code Style Guidelines

  1. React Hooks: Always call hooks before any conditional returns
  2. TypeScript: No implicit any types, proper type definitions
  3. Error Handling: Check for null/undefined before use
  4. Patterns: Follow existing code patterns and conventions

Testing Requirements

Frontend Tests (Vitest + React Testing Library)

# Run tests
npm test                           # Watch mode
npm run test:run                   # Run once
npm run test:coverage              # With coverage
npm test ComponentName.test.tsx    # Specific test

Backend Tests (Pytest)

cd backend
source .venv/bin/activate

# Run all tests
python -m pytest tests/

# Run with coverage
python -m pytest tests/ --cov=. --cov-report=html

# Run specific test suites
python -m pytest tests/api_tests/      # API tests
python -m pytest tests/tool_tests/     # Tool tests
python -m pytest tests/integration_tests/  # Integration tests

Test Writing Guidelines

  • ✅ Test business logic, not UI text
  • ✅ Focus on functionality and data transformations
  • ✅ Mock external services and APIs
  • ✅ Maintain high coverage (70%+ target)
  • ❌ Don’t test CSS classes or visual elements

Deployment Process

1. Development Testing

Your changes in dev branch are for development only. Test locally:

npm run dev        # Local development
npm run build      # Production build test

2. Staging Deployment

Create PR from dev to test:

# Via GitHub UI: dev → test
# Auto-merge when CI passes
# Deployed to: https://ai2.aitana.chat

3. Manual Testing

Test your changes on https://ai2.aitana.chat:

  • ✅ Feature functionality
  • ✅ Cross-browser compatibility
  • ✅ Mobile responsiveness
  • ✅ Performance impact
  • ✅ User experience

4. Production Deployment

Create PR from test to prod:

# Via GitHub UI: test → prod
# Requires manual review and approval
# Deployed to: https://ai.aitana.chat

CI/CD Pipeline

Automated Checks

Every PR triggers:

  • Frontend CI:
    • ESLint code quality checks
    • TypeScript compilation
    • Vitest unit tests
    • Production build verification
    • Coverage report generation
    • Docker image build
  • Backend CI:
    • API tests (authentication, endpoints)
    • Tool tests (AI search, document processing)
    • Integration tests (external services)
    • Model tests (AI/LLM functionality)
    • Utility tests (utils, monitoring)
    • Coverage badge generation

Pipeline Success Requirements

All of these must pass:

  • ✅ No ESLint errors
  • ✅ TypeScript compilation succeeds
  • ✅ All frontend tests pass
  • ✅ All backend test suites pass
  • ✅ Docker build succeeds
  • ✅ Coverage requirements met (70%+)

Project Structure

Frontend (src/)

src/
├── components/          # React components
├── contexts/           # React contexts
├── lib/               # Utility libraries
├── utils/             # Helper functions
├── types/             # TypeScript type definitions
├── app/               # Next.js app router pages
└── __tests__/         # Test files

Backend (backend/)

backend/
├── models/            # AI model integrations
├── tools/             # AI assistant tools
├── tests/             # Test suites
├── agents/            # AI agents
└── app.py             # Main Flask application

Documentation (docs/)

docs/
├── development/       # Build, API, deployment
├── features/          # Feature documentation
├── testing/           # Testing guides
└── troubleshooting/   # Common issues

Adding New Features

1. Plan Your Feature

  • Review existing patterns in the codebase
  • Check if similar functionality exists
  • Consider impact on existing features
  • Plan test coverage strategy

2. Frontend Components

// Follow existing patterns
interface ComponentProps {
  config: Configuration;
  onChange: (config: Configuration) => void;
}

export function MyComponent({ config, onChange }: ComponentProps) {
  // Hooks before conditionals
  const [state, setState] = useState();
  
  if (!config) return null;
  
  return <div>{/* component JSX */}</div>;
}

3. Backend Tools

# Add new tools in backend/tools/
def my_new_tool(params: dict) -> dict:
    """Tool description for AI model."""
    # Implementation
    return {"result": "success"}

4. Tests

// Frontend test
describe('MyComponent', () => {
  it('should handle configuration changes', () => {
    const onChange = vi.fn();
    render(<MyComponent config={mockConfig} onChange={onChange} />);
    // Test logic, not UI text
  });
});

# Backend test
def test_my_new_tool():
    """Test tool functionality."""
    result = my_new_tool({"param": "value"})
    assert result["result"] == "success"

Documentation Updates

When to Update Docs

  • ✅ New features or components
  • ✅ API changes
  • ✅ Configuration changes
  • ✅ New development processes
  • ✅ Breaking changes

Documentation Structure

Place docs in appropriate subdirectories:

  • docs/development/ → Build, API, deployment
  • docs/features/ → Feature guides, usage
  • docs/testing/ → Testing strategies
  • docs/troubleshooting/ → Bug fixes, issues

Requesting Documentation

Create GitHub issue with @claude mention:

Hi @claude, can you add documentation for the new user profile 
feature, including setup and usage examples?

Common Issues & Solutions

Build Failures

# Clear all caches and reinstall
rm -rf node_modules package-lock.json
npm install

# Backend dependency issues
cd backend
uv sync --reinstall

Test Failures

# Update test snapshots
npm test -- --update-snapshots

# Run tests with debugging
npm test -- --verbose

# Check coverage
npm run test:coverage

TypeScript Errors

# Check types without running
npx tsc --noEmit

# Clear TypeScript cache
rm -rf .next tsconfig.tsbuildinfo

Docker Issues

# Match exact CI environment
npm run docker:check

# Debug Docker build
docker build -t test-build .

Getting Help

Internal Resources

External Resources

Support Channels

  • GitHub Issues for bugs and feature requests
  • Code reviews for implementation feedback
  • Documentation requests via @claude mentions

Best Practices Summary

Development

  • ✅ Start from dev branch
  • ✅ Run quality checks before pushing
  • ✅ Write tests for new functionality
  • ✅ Follow existing code patterns
  • ✅ Update documentation when needed

Testing

  • ✅ Test locally before pushing
  • ✅ Use staging environment (ai2.aitana.chat) for integration testing
  • ✅ Ensure all CI checks pass
  • ✅ Maintain test coverage above 70%

Deployment

  • ✅ Small changes: direct to dev
  • ✅ Features: feature branch → dev → test → prod
  • ✅ Manual testing on staging before production
  • ✅ Monitor deployments for issues

Code Quality

  • ✅ No ESLint errors
  • ✅ Proper TypeScript types
  • ✅ Consistent code formatting
  • ✅ Clear commit messages
  • ✅ Helpful PR descriptions