Development Workflows

This document outlines the development environment setup, coding standards, and workflows for contributing to the project.

Prerequisites

Before starting development, ensure you have the required tools installed and configured. For complete installation instructions and repository setup, see Getting Started.

---

Coding Standards

Frontend (TypeScript/React)

Naming Conventions

Element	Convention	Example
Files	kebab-case	user-profile.tsx
Components	PascalCase	UserProfile
Functions/Variables	camelCase	getUserData
Constants	UPPER_SNAKE_CASE	MAX_RETRY_COUNT

Best Practices

• Use Biome for linting and formatting
• Enable strict type checking in tsconfig.json
• Avoid using any types; prefer explicit typing
• Use functional components with hooks
• Implement proper error boundaries

Example Component Structure

// user-profile.tsx
import { useState, useEffect } from 'react';

interface UserProfileProps {
  userId: string;
}

const MAX_DISPLAY_NAME_LENGTH = 50;

export function UserProfile({ userId }: UserProfileProps) {
  const [userData, setUserData] = useState<User | null>(null);

  const getUserData = async (id: string): Promise<User> => {
    // Implementation
  };

  return (
    // JSX
  );
}

Backend (Python/FastAPI)

Naming Conventions

Element	Convention	Example
Files	snake_case	user_service.py
Classes	PascalCase	UserService
Functions/Variables	snake_case	get_user_data
Constants	UPPER_SNAKE_CASE	MAX_RETRY_COUNT

Best Practices

• Follow PEP 8 style guidelines
• Use type hints for all function signatures
• Document public functions with docstrings
• Use dependency injection for services

Example Service Structure

# user_service.py
from typing import Optional

class UserService:
    """Service for managing user operations."""

    MAX_RETRY_COUNT = 3

    async def get_user_data(self, user_id: str) -> Optional[User]:
        """
        Retrieve user data by ID.

        Args:
            user_id: The unique identifier for the user.

        Returns:
            User object if found, None otherwise.
        """
        # Implementation

---

Git Workflow

Branch Naming

Type	Pattern	Example
Feature	feature/<name>	feature/user-authentication
Bug Fix	bugfix/<issue>	bugfix/login-redirect
Hotfix	hotfix/<critical>	hotfix/security-patch

Pull Request Process

1. Create Branch

   git checkout -b feature/my-feature
   

2. Develop and Commit

   git add .
   git commit -m "feat: add user authentication flow"
   

3. Push and Create PR

   git push origin feature/my-feature
   

4. Submit PR with:
   • Clear description of changes
   • Evidence of passing builds
   • Link to related issues (if applicable)
5. Review and Approval
   • Minimum 1 approval required
   • All CI checks must pass
6. Merge and Cleanup
   • Merge to main branch
   • Delete feature branch

Branch Protection Rules

The main branch is protected with the following requirements:

• All CI builds must pass
• Minimum 1 approving review required
• Direct pushes are not allowed

---

CI/CD Pipeline

The project uses GitHub Actions pipelines triggered from GitHub events.

Pipeline Stages

Build --> Lint--> TypeCheck--> Test --> Deploy

Stage	Description
Build	Install dependencies, compile assets
Lint	Run linters (Biomes for frontend, ruff for backend)
TypeCheck	Run type checker (MyPy for backend)
Test	Run unit and integration tests
Deploy	Build Docker images and deploy to GCP

Pipeline Configuration

Pipelines are defined in the repository and automatically triggered on:

• Push to main branch
• Pull request creation/update
• Manual trigger for deployments

Next Steps

Goal	Documentation
Learn about testing practices	Testing Strategy
Understand the API	API Documentation
Start implementing features	Implementation Guidance
Contribute to the project	Contributing