Development Protocol

Overview
Repository Structure
Development Workflow
Pull Request Process
Code Quality Standards
Component Development Patterns
Security Considerations
Release Management
Issue Management
Communication Guidelines
Additional Best Practices
Enforcement
Questions and Support
- Internal Developer Program

Overview

This guide establishes the development protocols and best practices for contributing to the Striae project. Following these guidelines ensures code quality, security, and maintainability while facilitating effective collaboration among contributors.

👥 Developer Types: This guide covers protocols for both internal developers (with team access) and external contributors (community members).

Repository Structure

The Striae project uses different repository access patterns depending on your developer status:

For External Contributors:

Production Repository: striae-org/striae (fork this to your account)
Your Fork: your-username/striae (where you make changes)
Contribution Flow: Your Fork → Pull Request to striae-org/striae

For Internal Developers:

Development Repository: striae-org/striae-dev (direct access)
Production Repository: striae-org/striae (for reference)
Contribution Flow: Branch in striae-org/striae-dev → Pull Request within same repo

Development Workflow

Fork Management

For External Contributors:

Fork the Repository: Fork striae-org/striae to your GitHub account
Clone Your Fork: Work from your personal fork
Keep Updated: Regularly sync your fork with the upstream repository

# Initial setup
git clone https://github.com/YOUR_USERNAME/striae.git
cd striae

# Add upstream remote (one-time setup)
git remote add upstream https://github.com/striae-org/striae.git

# Sync your fork regularly
git fetch upstream
git checkout master
git merge upstream/master
git push origin master

For Internal Developers:

Direct Access: Clone striae-org/striae-dev directly (no forking needed)
Branch-Based Workflow: Create feature branches within the shared repository
Keep Updated: Regularly pull latest changes from the development repository

# Clone the development repository
git clone https://github.com/striae-org/striae-dev.git
cd striae-dev

# Stay updated
git checkout master
git pull origin master

Branch Strategy

Universal Guidelines (Both Developer Types):

Feature Branches: Create descriptive feature branches from the latest master branch
Branch Naming: Use descriptive names following the pattern:
- feature/feature-name
- bugfix/issue-description
- hotfix/critical-fix
- docs/documentation-update

For External Contributors:

# Branch creation in your fork
git checkout master
git pull upstream master
git checkout -b feature/user-authentication-improvements

For Internal Developers:

# Branch creation in shared repository
git checkout master
git pull origin master
git checkout -b feature/user-authentication-improvements

Development Environment Setup

External Contributors:

Must set up their own Cloudflare services (Pages, Workers, KV, R2, Images, Turnstile)
Must configure their own Firebase project with authentication
Must obtain their own SendLayer API key
Must manually configure all environment variables and config files
Follow the complete installation guide

Internal Developers:

Receive access to shared Cloudflare services (no separate setup needed)
Use pre-configured Firebase authentication and MFA
Access to shared SendLayer API service
Receive complete .env files and configuration files
Can skip most installation steps and focus on development

Commit Guidelines

Commit Frequency: Commit often with logical, atomic changes
File Limit: Avoid modifying more than 5 files per commit when possible
Commit Messages: Use clear, descriptive commit messages following conventional commit format:

type(scope): brief description

Detailed explanation of what changed and why

Commit Types:

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

Examples:

feat(auth): implement multi-factor authentication support

Add MFA functionality with TOTP support and backup codes.
Includes user settings UI and Firebase integration.

fix(canvas): resolve annotation positioning

Fixes issue where touch events were incorrectly calculated
on devices with different pixel densities.

Pull Request Process

PR Requirements

For External Contributors:

Target Repository: Submit pull requests from your fork to striae-org/striae
Cross-Repository PR: Your fork → striae-org/striae
Branch Protection: Ensure your branch is up-to-date with the target branch

For Internal Developers:

Target Repository: Submit pull requests within striae-org/striae-dev (branch → master)
Same-Repository PR: Your feature branch → striae-dev master branch
Direct Access: Work within the shared development repository

Both Developer Types:

Use the provided PR template and fill out all sections
Ensure branch is up-to-date before submitting

Review Process

Mandatory Review: All pull requests must be reviewed and approved by a project admin before merging
Review Criteria: Reviews will assess:
- Code quality and adherence to standards
- Security implications
- Performance impact
- Test coverage
- Documentation completeness

Merge Guidelines

Admin Only: Only project administrators can merge pull requests
Merge Strategy: Use "Squash and Merge" for feature branches to maintain clean history
Delete Branches: Feature branches should be deleted after successful merge

PR Description Requirements

Required Information:

Summary: Clear description of what the PR accomplishes
Changes Made: Detailed list of modifications
Testing: Description of testing performed
Breaking Changes: Any breaking changes and migration notes
Related Issues: Link to related issues or discussions
Screenshots: For UI changes, include before/after screenshots
Security Impact: Any security considerations or changes

PR Description Template:

## Summary
Brief description of the changes and their purpose.

## Changes Made
- [ ] Feature 1: Description
- [ ] Feature 2: Description
- [ ] Bug fix: Description

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests verified
- [ ] Manual testing completed
- [ ] Browser compatibility verified

## Breaking Changes
List any breaking changes and migration steps.

## Security Impact
Describe any security considerations or changes.

## Related Issues
Closes #123
Related to #456

## Screenshots (if applicable)
[Include relevant screenshots]

Code Quality Standards

Code Style

Formatting: Use Prettier for consistent code formatting
Linting: Follow ESLint rules defined in the project
TypeScript: Maintain strict TypeScript compliance
Comments: Write clear, meaningful comments for complex logic

Testing Requirements

Unit Tests: Write unit tests for new functionality
Integration Tests: Include integration tests for API endpoints
Coverage: Maintain or improve code coverage
Test Naming: Use descriptive test names and organize tests logically

Documentation

Code Documentation: Document complex functions and classes
README Updates: Update relevant README files for new features
API Documentation: Update API documentation for endpoint changes
Guide Updates: Update relevant guides in the /guides directory

Component Development Patterns

Component Architecture

Directory Structure: Follow established patterns

app/components/[feature]/
├── component.tsx        # Main component file
├── component.module.css # Component-specific styles
├── components/          # Sub-components (for complex features)
├── hooks/              # Custom hooks for business logic
├── utils/              # Pure utility functions
└── index.ts            # Barrel export file

Component Composition Pattern: For complex features, use modular architecture

// Main orchestrator component
export const ComplexFeature = ({ ...props }: FeatureProps) => {
  // Use custom hooks for business logic
  const state = useFeatureState();
  const actions = useFeatureActions();
  
  return (
    <div>
      <SubComponent1 {...state} {...actions} />
      <SubComponent2 {...state} {...actions} />
      <SubComponent3 {...state} {...actions} />
    </div>
  );
};

// Sub-components handle specific UI concerns
const SubComponent1 = ({ data, onAction }: SubComponentProps) => {
  // Single responsibility UI logic
  return <div>{/* Specific UI */}</div>;
};

Custom Hooks for Business Logic: Encapsulate complex logic in reusable hooks

// State management hook
const useFeatureState = () => {
  const [isLoading, setIsLoading] = useState(false);
  const [data, setData] = useState(null);
  const [error, setError] = useState(null);
  
  return { isLoading, data, error, setIsLoading, setData, setError };
};

// Actions hook
const useFeatureActions = () => {
  const processData = useCallback(async (input) => {
    // Business logic here
  }, []);
  
  return { processData };
};

Barrel Exports: Use index.ts files for clean imports

// components/feature/index.ts
export { MainComponent } from './main-component';
export { SubComponent1, SubComponent2 } from './components';
export { useFeatureState, useFeatureActions } from './hooks';
export type { FeatureProps, SubComponentProps } from './types';

Component Interface Design:

// Always define props interface
interface ComponentProps {
  // Required props first
  data: DataType;
  onAction: (param: ParamType) => void;
  
  // Optional props with clear defaults
  isVisible?: boolean;
  className?: string;
}

export const Component = ({ data, onAction, isVisible = true }: ComponentProps) => {
  // Component implementation
};

State Management Patterns:
- Use useState for local component state
- Use useContext for shared state (e.g., AuthContext)
- Implement custom hooks for reusable logic
- Follow "Props Down, Events Up" pattern
- Separate business logic from UI components using custom hooks
Integration Requirements:
- Canvas components must integrate with existing annotation system
- Toolbar components must connect to toolbar state management
- PDF workers must receive consistent data structures
- All components must support automatic saving workflow

Type Definition Management

Centralized Types: Define all interfaces in dedicated type files

// types/annotations.ts
export interface BoxAnnotation {
  id: string;
  x: number;      // Percentage 0-100
  y: number;      // Percentage 0-100
  width: number;  // Percentage 0-100
  height: number; // Percentage 0-100
  color: string;  // Hex color code
  label?: string; // Optional label text
  timestamp: string; // Creation timestamp
}

export interface AnnotationData {
  // ... existing fields
  boxAnnotations?: BoxAnnotation[];
}

Type Import Patterns:

// Import from centralized location
import type { BoxAnnotation, AnnotationData } from '~/types/annotations';

// Use in component
interface ComponentProps {
  annotations: BoxAnnotation[];
  data: AnnotationData;
}

Type Consistency Requirements:
- All annotation-related types must be consistent across frontend and workers
- PDF worker must use same type definitions for data processing
- API documentation must reflect actual type definitions
- Type changes require updates across all consuming components
Type Cleanup Protocols:
- Remove unused interfaces and properties promptly to maintain code clarity
- Update all import statements when reorganizing type definitions
- Maintain barrel exports (index.ts) for clean import paths
- Document type changes in API reference documentation

Export System Development

Multi-Format Export Architecture:

// Export interface consistency
export interface ExportOptions {
  includeAnnotations?: boolean;
  format?: 'json' | 'csv' | 'zip';
  includeImages?: boolean;
  includeMetadata?: boolean;
}

// Format-specific functions
export const downloadCaseAsJSON = (exportData: CaseExportData): void
export const downloadCaseAsCSV = (exportData: CaseExportData): void
export const downloadCaseAsZip = async (exportData: CaseExportData, includeImages: boolean): Promise<void>

ZIP Export Development Requirements:
- Use JSZip library for browser-based ZIP creation
- Implement progress tracking for image downloads and ZIP generation
- Handle image fetch failures gracefully with error reporting
- Structure ZIP contents logically (data files + images/ directory)
CSV/Excel Export Standards:
- Maintain data parity between JSON and CSV/Excel formats
- Split box annotations into separate rows for data analysis
- Use consistent column ordering across all export formats
- Implement multi-worksheet Excel support for bulk exports
Export UI Integration:
- Synchronize UI states (checkboxes, buttons) during export operations
- Provide clear format indicators with tooltips
- Implement proper loading states and error handling
- Ensure keyboard navigation accessibility
Performance Considerations:
- Implement configurable annotation inclusion for faster exports
- Use progress callbacks for long-running operations
- Handle large image downloads with timeout management
- Optimize memory usage during ZIP file creation

Integration Testing Patterns

Component Integration Tests:

// Test component interaction with Canvas system
describe('BoxAnnotations Integration', () => {
  it('should integrate with Canvas coordinate system', () => {
    // Test percentage-based positioning
  });
  
  it('should trigger automatic save on annotation creation', () => {
    // Test save workflow integration
  });
});

API Integration Tests:
- Test worker endpoints with actual component data structures
- Verify PDF generation includes box annotations when expected
- Test data flow from component through save API to storage
Cross-Component Testing:
- Test toolbar state management with annotation components
- Verify color selector integration with box annotation system
- Test visibility controls across all annotation types

Security Considerations

Sensitive Data: Never commit sensitive data (API keys, passwords, etc.)
Dependencies: Keep dependencies updated and scan for vulnerabilities
Input Validation: Validate all user inputs
Authentication: Follow established authentication patterns
Environment Variables: Use environment variables for configuration

Release Management

Versioning Scheme: Follow the project's versioning format:
- Beta Releases: v0.#.#-beta (e.g., v0.9.06-beta)
  - First number: Always 0 for beta releases
  - Second number: Month (1-12)
  - Third number: Date (01-31)
- Production Releases: v#.##.## (e.g., v1.01.00)
  - First number: Major release (breaking changes, major features)
  - Second number: Minor release (new features, enhancements)
  - Third number: Patch release (bug fixes, small improvements)
Release Notes: Maintain comprehensive release notes for each version
Changelog: Update README.md changelog for each release
Tag Management: Use proper Git tags matching the version format (v0.#.#-beta or v#.##.##)
Beta to Production: Beta versions should be thoroughly tested before removing the -beta suffix and promoting version numbers to production releases
Release Immutability: Once a release is tagged and published, it is immutable and cannot be modified. If issues are discovered, create a new release with an incremented version number

Issue Management

Issue Templates: Use provided issue templates
Labels: Apply appropriate labels to issues
Assignees: Assign issues to appropriate team members
Milestones: Associate issues with relevant milestones
Documentation: Link related documentation and PRs

Communication Guidelines

Respectful Communication: Maintain professional and respectful communication
Clear Communication: Be clear and specific in issue descriptions and comments
Response Time: Respond to reviews and comments in a timely manner
Code of Conduct: Follow the project's Code of Conduct at all times

Additional Best Practices

Performance Considerations

Profile performance impact of changes
Optimize database queries and API calls
Consider caching strategies for improved performance

Accessibility

Ensure UI changes meet accessibility standards
Test with screen readers and keyboard navigation
Include proper ARIA labels and semantic HTML

Error Handling

Implement comprehensive error handling
Provide meaningful error messages to users
Log errors appropriately for debugging

Monitoring and Observability

Include appropriate logging for new features
Consider monitoring and alerting needs
Document operational procedures for new services

Enforcement

Failure to follow these protocols may result in:

PR rejection and request for revision
Additional review requirements
Temporary restriction from contributing

Questions and Support

For questions about these protocols or development practices:

GitHub Issues: Open an issue with the question label
Email: Contact project administrators at dev@striae.org
Discord: Contact team members on the Striae Discord #development channel (private)
Documentation: Refer to the project documentation in the /guides directory

Internal Developer Program

If you're interested in becoming an internal developer with direct access to the development infrastructure:

Contact: Stephen at dev@striae.org
Benefits: Internal developers receive:
- Pre-configured Environment: Complete .env files with all required variables
- Cloudflare Access: Access to shared Cloudflare services (no separate account needed)
- Pre-configured Services: Firebase authentication, MFA, and SendLayer API already set up
- Configuration Files: All config.json, firebase.ts, and wrangler.jsonc files ready to use
- Direct Repository Access: Push access to striae-org/striae-dev
- Development Environment: Access to https://dev.striae.org for testing
- Enhanced Development Privileges: Streamlined setup and deployment process
- Private Communication Channels: Access to Discord #development channel
- Faster Development Cycle: Skip complex setup steps and focus on coding

Internal Developer Workflow:

Clone striae-org/striae-dev directly
Use provided configuration files
Create feature branches within the shared repository
Submit pull requests within the same repository
Test on the shared development environment

This guide is a living document and will be updated as the project evolves. Contributors are encouraged to suggest improvements to these protocols.

Development Protocol

Table of Contents

Overview

Repository Structure

For External Contributors:

For Internal Developers:

Development Workflow

Fork Management

Branch Strategy

Development Environment Setup

Commit Guidelines

Pull Request Process

PR Requirements

Review Process

Merge Guidelines

PR Description Requirements

Code Quality Standards

Code Style

Testing Requirements

Documentation

Component Development Patterns

Component Architecture

Type Definition Management

Export System Development

Integration Testing Patterns

Security Considerations

Release Management

Issue Management

Communication Guidelines

Additional Best Practices

Performance Considerations

Accessibility

Error Handling

Monitoring and Observability

Enforcement

Questions and Support

Internal Developer Program