Skip to main content

Contributing to AI-Powered PDF Analysis Platform

Thank you for your interest in contributing to the AI-Powered PDF Analysis Platform!

Copyright © 2025 AZ1.AI Inc. / Coditect.AI - All Rights Reserved

📋 Table of Contents​

Code of Conduct​

This project adheres to a professional code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to 1@az1.ai.

Our Standards​

Positive behaviors include:

  • Using welcoming and inclusive language
  • Being respectful of differing viewpoints
  • Gracefully accepting constructive criticism
  • Focusing on what is best for the project
  • Showing empathy towards other contributors

Unacceptable behaviors include:

  • Harassment, discrimination, or offensive comments
  • Trolling, insulting/derogatory comments
  • Public or private harassment
  • Publishing others' private information
  • Other unethical or unprofessional conduct

Getting Started​

Prerequisites​

Before contributing, ensure you have:

  • Node.js 18.0.0 or higher
  • Python 3.11 or higher
  • Docker 24.0 or higher
  • Git with SSH configured
  • Anthropic API Key (for AI features)

Fork and Clone​

# Fork the repository on GitHub
# Then clone your fork
git clone git@github.com:YOUR_USERNAME/coditect-pdf-convertor.git
cd coditect-pdf-convertor

# Add upstream remote
git remote add upstream git@github.com:coditect-ai/coditect-pdf-convertor.git

Development Setup​

1. Environment Configuration​

# Copy environment templates
cp .env.example .env
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

# Edit .env files with your values
# IMPORTANT: Add your ANTHROPIC_API_KEY

2. Backend Setup​

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest tests/ -v

# Start development server
uvicorn src.api.main:app --reload

3. Frontend Setup​

cd frontend

# Install dependencies
npm install

# Run tests
npm run test

# Start development server
npm run dev
# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Project Structure​

coditect-pdf-convertor/
├── backend/
│   ├── src/
│   │   ├── api/          # FastAPI routes and WebSocket
│   │   ├── models/       # Database models
│   │   ├── middleware/   # Auth, rate limiting, RBAC
│   │   └── core/         # PDF processing logic
│   └── tests/            # Backend tests
├── frontend/
│   ├── src/
│   │   ├── components/   # React components
│   │   ├── hooks/        # Custom React hooks
│   │   ├── store/        # Zustand state management
│   │   └── types/        # TypeScript type definitions
│   └── public/           # Static assets
├── infrastructure/
│   ├── docker/           # Dockerfiles
│   ├── k8s/              # Kubernetes manifests
│   └── monitoring/       # Prometheus/Grafana config
└── docs/                 # Architecture & guides

Coding Standards​

Python (Backend)​

Style Guide: Follow PEP 8 with these tools:

  • Black for code formatting (line length: 88)
  • Pylint for linting (minimum score: 8.0)
  • MyPy for type checking (strict mode)
# Format code
black backend/src

# Lint code
pylint backend/src

# Type check
mypy backend/src --strict

File Headers: All Python files must include:

"""
AI-Powered PDF Analysis Platform - Module Name
Brief description of the module

Copyright (c) 2025 AZ1.AI Inc. / Coditect.AI
All Rights Reserved.

Author: Hal Casteel, CEO/CTO AZ1.AI Inc.
Contact: 1@az1.ai
License: Proprietary - See LICENSE file
"""

Best Practices:

  • Use async/await for all I/O operations
  • Add comprehensive docstrings to all functions
  • Include type hints for all parameters and return values
  • Handle exceptions appropriately with custom error messages
  • Log important operations with structured logging

TypeScript (Frontend)​

Style Guide: Follow Airbnb style with these tools:

  • ESLint for linting
  • Prettier for formatting
  • TypeScript strict mode enabled
# Format code
npm run format

# Lint code
npm run lint

# Type check
npm run type-check

File Headers: All TypeScript files must include:

/**
 * AI-Powered PDF Analysis Platform - Component Name
 * Brief description
 *
 * Copyright (c) 2025 AZ1.AI Inc. / Coditect.AI
 * All Rights Reserved.
 *
 * Author: Hal Casteel, CEO/CTO AZ1.AI Inc.
 * Contact: 1@az1.ai
 * License: Proprietary - See LICENSE file
 */

Best Practices:

  • Use functional components with hooks
  • Implement proper TypeScript types (no any)
  • Use Material-UI components consistently
  • Handle loading and error states
  • Implement proper cleanup in useEffect
  • Follow React best practices (memoization, lazy loading)

Git Commit Messages​

Follow Conventional Commits format:

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

<body>

<footer>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting)
  • refactor: Code refactoring
  • perf: Performance improvements
  • test: Adding/updating tests
  • chore: Build process or auxiliary tool changes

Examples:

feat(backend): add user authentication endpoints

Implement JWT-based authentication with:
- Login endpoint
- Register endpoint
- Token refresh endpoint
- Password reset flow

Closes #123

---

fix(frontend): resolve WebSocket reconnection issue

The WebSocket was not reconnecting after network interruption.
Added exponential backoff retry logic.

Fixes #456

Testing Requirements​

Backend Tests​

Minimum Coverage: 80%

# Run all tests
pytest tests/ -v

# With coverage
pytest tests/ -v --cov=src --cov-report=html

# Run specific test file
pytest tests/test_converter.py -v

# Run with markers
pytest -m "unit" -v      # Only unit tests
pytest -m "integration" -v  # Only integration tests

Test Structure:

def test_pdf_upload_success():
    """Test successful PDF upload with valid file"""
    # Arrange
    file_path = "tests/fixtures/test.pdf"

    # Act
    result = upload_pdf(file_path)

    # Assert
    assert result.status == "success"
    assert result.document_id is not None

Frontend Tests​

Minimum Coverage: 70%

# Run all tests
npm run test

# With coverage
npm run test:coverage

# Watch mode
npm run test:watch

Test Structure:

describe('Login Component', () => {
  it('should display error for invalid email', () => {
    render(<Login />);

    const emailInput = screen.getByLabelText('Email');
    fireEvent.change(emailInput, { target: { value: 'invalid' } });
    fireEvent.blur(emailInput);

    expect(screen.getByText('Email is invalid')).toBeInTheDocument();
  });
});

Pull Request Process​

1. Create Feature Branch​

# Update main branch
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/your-feature-name

2. Make Changes​

  • Write code following coding standards
  • Add/update tests
  • Update documentation
  • Add file headers to new files

3. Test Locally​

# Backend
cd backend
pytest tests/ -v --cov=src
black . --check
pylint src/
mypy src/

# Frontend
cd frontend
npm run test
npm run lint
npm run type-check
npm run build

4. Commit Changes​

git add .
git commit -m "feat(scope): description"

5. Push to Fork​

git push origin feature/your-feature-name

6. Create Pull Request​

  1. Go to GitHub and create PR from your fork
  2. Fill out the PR template completely
  3. Link related issues
  4. Request review from maintainers
  5. Address review feedback
  6. Wait for CI/CD to pass

PR Checklist​

  • Code follows project style guidelines
  • File headers added to all new files
  • Tests added for new functionality
  • All tests passing locally
  • Documentation updated
  • No breaking changes (or clearly documented)
  • Commit messages follow conventions
  • PR description is complete

Security​

Reporting Security Issues​

DO NOT open public issues for security vulnerabilities.

Instead, email security details to: 1@az1.ai

Include:

  • Description of the vulnerability
  • Steps to reproduce
  • Potential impact
  • Suggested fix (if any)

We will respond within 48 hours.

Security Best Practices​

  • Never commit secrets, API keys, or credentials
  • Use environment variables for configuration
  • Validate all user inputs
  • Sanitize data before database operations
  • Use parameterized queries (SQLAlchemy ORM)
  • Implement proper authentication and authorization
  • Keep dependencies updated
  • Follow OWASP Top 10 guidelines

License​

This project is proprietary software owned by AZ1.AI Inc. / Coditect.AI.

All Rights Reserved - See LICENSE file.

By contributing to this project, you agree that:

  1. AZ1.AI Inc. retains all rights to your contributions
  2. You have the right to make these contributions
  3. Your contributions are original work
  4. You grant AZ1.AI Inc. perpetual license to use your contributions

Questions?​

  • Email: 1@az1.ai
  • GitHub Issues: For bug reports and feature requests
  • GitHub Discussions: For questions and general discussion

Maintainers​

  • Hal Casteel - CEO/CTO AZ1.AI Inc. - 1@az1.ai

Thank you for contributing to the AI-Powered PDF Analysis Platform!

Copyright © 2025 AZ1.AI Inc. / Coditect.AI - All Rights Reserved